Metadata Tools

This section describes two tools that are used with metadata and services. The first tool is named Wsdl.exe; it is a Web Service Description Language (WSDL) tool designed to generate server code for ASMX services and client proxies from metadata. The second tool is named Svcutil.exe; it is used to generate client proxies from metadata or to generate metadata from assemblies and other services. For this discussion, metadata includes WSDL contract files, XSD schemas, and .discomap discovery documents.

A client proxy consists of classes added to client applications that can be used to invoke operations on a remote server. In the case of ASMX or WCF services, the remote server is the host that implements the service. Many of the classes used to implement a proxy are semantically equivalent to classes in the service. For example, data types in an ASMX client application have the same structure and public property names as data types in the ASMX service. Other classes in the client proxy are used to invoke operations on the remote service.

When using the Add Web Reference dialog box in Visual Studio, a client proxy is generated using WSDL information and is added to the Visual Studio project. This is usually used for ASMX services, but you can also use the Add Web Reference dialog box to create a client proxy for WCF services. However, you need to manually type the service URL, and the proxy that is generated uses XML serialization, which is the only type of serialization supported. To create client proxies for WCF services that support the data contract serializer, you can use the Svcutil.exe tool or use the Add Service Reference feature of the Visual Studio Development Tools for the .NET Framework 3.x.

The main difference between the two tools is that the Wsdl.exe tool is meant to be used with ASMX services and generates only proxy code; the Svcutil.exe tool is meant to be used with WCF services and it can translate back and forth between metadata and code. In addition, the default behavior for Wsdl.exe is to generate both synchronous and asynchronous methods, while the Svcutil.exe tool generates asynchronous methods only if the /async option is used. The Svcutil.exe tool also supports new features in WCF, such as a policy section in a WSDL file that can be used to describe services security requirements.

Code Generation

Typically, the Wsdl.exe tool is used to create client proxies that are used to access ASMX services. In addition, the Wsdl.exe tool can also be used to generate XML Web service classes by using the /server option or the /serverInterface option to generate service interface contracts that are supported in ASP.NET 2.0.

The Svcutil.exe tool can be used to create client proxies for both WCF and ASMX services. When Svcutil.exe is used create a proxy from an ASMX service, the data types that are generated in the code usually use XML serialization. If all the data types in an ASMX service are supported by the data contract serializer, it is possible to generate data contracts by using the /dconly option; however, that cannot be used against a running service. In other words, the /dconly option will work only against a physical file, such as a WSDL, XSD, or assembly file.

When the Svcutil.exe is tool used to generate proxy code from a WCF service, the default behavior is to generate data contracts; however, it is also possible to generate data types that use XML serialization. If a WCF service contract uses the XmlSerialzerFormat attribute, the Svcutil.exe tool treats it the same way it treats an ASMX service.

Finally, WCF uses import statements in WSDL files to include different elements and never includes the schema directly in the file. The end result is that you cannot generate a WSDL file from a WCF service that contains the schema. To access the schema associated with a running WCF service, you can use query string values to specify which schema you want. The following example shows how to retrieve a schema identified as xsd0 in a WSDL import statement, such as https://localhost/EmployeeService.Host/EmployeeService.svc?xsd=xsd0.

XSD Schemas

Many services use stand-alone XML Schema (XSD) files to define common data types that are shared by other services. This approach is very common and both the Wsdl.exe and Svcutil.exe tools can be used to generate the appropriate data types or data contracts from XML schemas. However, the Svcutil.exe tool is limited when it is used on XSD files. Specifically, the Svcutil.exe tool is able to generate data contracts only from an XSD file, which means that it does not support attribute-based schemas.

When the Svcutil.exe tool is used with a WSDL file, it is able to generate data types that use XML serialization or data contracts that use the data contract serializer. However, when used with XSD files, it cannot generate data types that use XML serialization. Instead, it returns an error message if any elements in the schema are not supported by data contracts. This means that the XML schema must be element-based so that the Svcutil.exe tool can generate data contracts. This may seem like a major limitation, but you can still use the Xsd.exe tool to generate data types from an XSD file that can be used in a WCF service. As a result, the recommendation is to use Svcutil.exe when the XML schema in an XSD file supports data contracts; otherwise, you should use the Wsdl.exe tool to generate data types.

Metadata Generation

Between the Wsdl.exe and the Svcutil.exe tools, only the Svcutil.exe tool can be used to generate metadata. This can be accomplished by running the tool against an assembly that contains data contracts, or by running the tool against a service and using switches to generate metadata. The following options are available with Svcutil.exe when generating metadata:

• /serviceName:<serviceConfigName>. This option specifies the configuration name of a service to export. If this option is used, an executable assembly with an associated configuration file must be passed as input. The Svcutil.exe tool searches through all associated configuration files for the service configuration. If the configuration files contain any extension types, the assemblies containing these types must be in the global assembly cache or explicitly provided using the /r option.
• /reference:<file path> (Short Form: /r). This option adds the specified assembly to the set of assemblies used for resolving type references. If you are exporting or validating a service that uses third-party extensions that are registered in the configuration (such as behaviors, bindings, and binding elements), use this option to locate extension assemblies that are not in the binding elements.
• /dataContractOnly (Short Form: /dconly). This option operates only on data contract types. Service contracts will not be processed.
• /excludeType:<type> (Short Form: /et). Use this option to specify the fully-qualified or assembly-qualified name of a type to exclude it from export. This option can be used when exporting metadata for a service or on a set of service contracts to exclude types from being exported. This option cannot be used with the /dconly option.

When working with ASMX services, you can use two methods to generate metadata. One method is to pass a query string value of "wsdl", which generates a WSDL file and the other is to use Xsd.exe with assemblies that contain the ASMX data types to generate an XML Schema (XSD) file. When using the Add Web Reference operation, a WSDL file is also generated and added to the service folder. The following examples demonstrate how to perform these operations:

• https://localhost/ASMXEmploye/EmployeeManager.asmx?wsdl. This option generates a WSDL file from the ASMX service and displays it in a browser. You can save the browser source to disk using a .wsdl file name extension when saving the file.
• xsd.exe <assembly>.dll|exe. This option generates an XML Schema (XSD) file with data types in the assembly. Classes in the assembly also need to support XML serialization by using attributes, such as the XmlRootAttribute, which is required on the class declaration.