This documentation is archived and is not being maintained.

Web Service Endpoints Based on WSDL Files

Visual Studio 2008

You can use a contract-driven approach to define service behavior. You can perform this task by creating Web service provider endpoints from the Web Services Description Language (WSDL) files. You can also conform existing Web service provider endpoints to WSDL files.

NoteNote:

You can perform these tasks using .disco files. This release supports only WSDL files that contain single WSDL bindings and .disco files that reference single Web services. For more information, see Communication Between Applications.

For more information, see the following sections:

For more information about contract-driven service design, see the Contract First Web Services Interoperability page on MSDN online at http://go.microsoft.com/fwlink/?LinkId=49584.

You can create WSDL-based endpoints on ASP.NET applications and systems. This endpoint appears on the application or system. It populates with operation signatures referenced by the WSDL file. These operation signatures also appear in the Web service class file if the associated application is implemented already. Additional class files might also appear in the application's project if these signatures reference any custom types. For more information, see Custom Types Referenced in Operation Signatures.

NoteNote:

Only applications can be implemented, not systems.

Creating a Web service provider endpoint from a WSDL file produces a result equivalent to using the Wsdl.exe command line utility with the /server option. For more information, see the following:

You can conform existing Web service provider endpoints to WSDL files. This action adds or changes any existing operation signatures, conforming them to the WSDL file. This action might also affect operation signatures and type names in code if the associated application is implemented already. However, nested types within Datasets will not be conformed.

NoteNote:

Conforming an endpoint on a member of a system actually conforms the underlying endpoint definition. This action modifies the uses of that definition in other systems.

Though no method body code will change, changes to operation signatures and type names might cause method body code to no longer compile. Therefore, review your code. Identify the changes that might be required to fix any compiler errors. For more information, see Code Changes After Conforming Web Service Endpoints to WSDL Files.

A WSDL file specifies the requirements for providing and consuming a Web service. It acts as a contract between provider and consumer. Web service endpoints based on the same version of a WSDL file also allows you to substitute those endpoints. For more information, see Web Service Endpoint Substitution.

The WSDL binding definition in a WSDL file describes the operations offered by a Web service. The Web service provider endpoint represents this WSDL binding. If the associated ASP.NET application enables WSDL file generation, Visual Studio generates a new WSDL file for each Web service on that application (once the application is implemented). Visual Studio also uses this WSDL file to generate Web references for associated Web service consumer applications (once they are implemented). For more information, see How to: Control WSDL File Generation for ASP.NET Web Services.

After the WSDL file for a Web service is published, each change to a Web service definition is considered a new WSDL binding.

TipTip:

If you change the Web service definition, change the WSDL binding name, the WSDL binding namespace, or both. Changing a Web service definition without changing its WSDL binding name or namespace might hide the fact that the Web service is no longer compatible with connected or previously connected applications. The default value for the WSDL service name and the WSDL binding name is "WebServiceN"; "N" represents an ordinal number. However, once you implement the application, deleting the WSDL binding name in the Web service class file changes the default value to "WebServiceNSoap". The default value for the WSDL service namespace and WSDL binding namespace is "http://tempuri.org". The WSDL service description and WSDL binding location properties do not have a default value. The default value for the WSDL binding name is "WebServiceN".

When you change the WSDL binding name or binding namespace on an unimplemented Web service provider endpoint, the corresponding properties of any connected and unimplemented consumer endpoints either update automatically or update when they are reconnected. However, when you change these properties on an implemented Web service provider endpoint, any connected and implemented Web service consumer endpoints might not update immediately. However, you can manually update these properties for these consumer endpoints.

The operation signatures in a Web service endpoint might reference CLR classes that handle XML serialization for complex XML types referenced in the WSDL file or related XML schema files. If the associated application is not yet implemented, Visual Studio generates code files for these classes upon implementation. It generates these files along with the corresponding Web service and application project files. If the application is already implemented, it adds code files for these classes to the existing project. For more information, see Overview of ASP.NET Applications on Application Diagrams.

NoteNote:

When you copy a WSDL-based Web service endpoint to another application, Visual Studio copies only the operation signatures. If the destination application is implemented already, it does not copy the code files for additional CLR classes. If the destination application is not yet implemented, it will not generate the code files for these classes upon implementation. To avoid this situation, create endpoints from the same WSDL or .disco file used for the endpoints you want to copy.

In some XML schemas, the Web service class and data serialization classes require additional serialization attributes to make sure that the XML is formatted correctly. However, WSDL-based Web service provider endpoints support only a small set of these serialization attributes. In a small number of cases, the resulting WSDL file generated for the Web service endpoint and the resulting XML messages might not be consistent with the original WSDL file used to create the Web service provider endpoint.

TipTip:

If these problems occur, use the Wsdl.exe utility to generate the Web service class and data serialization classes instead of creating a Web service provider endpoint from a WSDL file. However, you will need to manually add the generated code to your project and then create the required .asmx file. A correct Web service provider endpoint then appears. This makes it possible for you use the designer to edit the endpoint.

The following list contains more information about support for these serialization attributes:

  • These XML serialization attributes are added to classes generated for complex XML types: SerializableAttribute, SoapTypeAttribute, XmlIncludeAttribute, XmlRootAttribute, and XmlTypeAttribute.

  • These XML serialization attributes are added to class fields: XmlAnyAttribute, XmlArrayAttribute, XmlArrayItemAttribute, XmlAttributeAttribute, XmlChoiceIdentifierAttribute, XmlElementAttribute, XmlEnumAttribute, XmlIgnoreAttribute, XmlNamespaceDeclarationsAttribute, and XmlTextAttribute.

  • Serialization attributes are not applied to the return type for Web methods.

  • Serialization attributes are not applied to the parameters of Web methods.

  • The following SOAP-encoded serialization attributes are not applied to these classes: SoapElementAttribute, SoapIgnoreAttribute, SoapAttributeAttribute, SoapAttributeOverrides, SoapAttributes, SoapEnumAttribute, and SoapIncludeAttribute.

  • Attribute arguments that require a complex XML type are generated as a String type with the fully qualified name of the type. This will cause a compiler error that will need to be fixed.

    For example, <XmlIncludeAttribute(GetType("ClassName"))> in Visual Basic is generated as <XmlIncludeAttribute("ClassName")>, while [XmlIncludeAttribute(typeof("ClassName"))] in Visual C# is generated as [XmlIncludeAttribute("ClassName")].

Show: