Importing Custom Metadata for a WCF Extension

In Windows Communication Foundation (WCF), metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, WCF can import ServiceEndpoint instances, Binding instances or ContractDescription instances from a WSDL document for a service. To import service metadata in WCF, use an implementation of the System.ServiceModel.Description.MetadataImporter abstract class. Types that derive from the MetadataImporter class implement support for importing metadata formats that take advantage of the WS-Policy import logic in WCF.

Custom metadata consists of XML elements that the system-provided metadata importers cannot import. Typically, this includes custom WSDL extensions and custom policy assertions.

This section describes how to import custom WSDL extensions and policy assertions. It does not focus on the importing process itself. For more information about how to use the types that export and import metadata regardless of whether the metadata is custom or system-supported, see Exporting and Importing Metadata.

Overview

The System.ServiceModel.Description.WsdlImporter type is the implementation of the MetadataImporter abstract class included with WCF. The WsdlImporter type imports WSDL metadata with attached policies that are bundled in a System.ServiceModel.Description.MetadataSet object. Policy assertions and WSDL extensions that the default importers do not recognize are passed to any registered custom policy and WSDL importers for importing. Typically, importers are implemented to support user-defined binding elements or to modify the imported contract.

This section describes:

1. How to implement and use the System.ServiceModel.Description.IWsdlImportExtension interface, which exposes the WSDL data to custom importers prior to the generation of descriptions and the generation of code. You can use this interface to examine or modify the description types and code compilation performed using a given set of metadata.

2. How to implement and use the System.ServiceModel.Description.IPolicyImportExtension interface, which exposes policy assertions to importers prior to the generation of description objects. You can use this interface to examine or modify the binding or contract based on the downloaded policies.

For more information about exporting custom WSDL and policy assertions, see Exporting Custom Metadata for a WCF Extension.

Importing Custom WSDL Extensions

To add support for importing WSDL extensions, implement the IWsdlImportExtension interface and then add your implementation to the WsdlImportExtensions property. The WsdlImporter can also load implementations of the IWsdlImportExtension interface registered in your application configuration file. Note that a number of WSDL importers are registered by default and the order of the registered WSDL importers is significant.

When the custom WSDL importer is loaded and used by the WsdlImporter, first the BeforeImport method is called to enable the modification of metadata prior to the import process. Next, the contracts are imported after which the ImportContract method is called to enable the modification of the contracts imported from the metadata. Finally, the ImportEndpoint method is called to enable the modification of the imported endpoints.

For more information, see How to: Import Custom WSDL.

Importing Custom Policy Assertions

The WsdlImporter type and the ServiceModel Metadata Utility Tool (Svcutil.exe) automatically handle processing a variety of policy assertion types in policy expressions attached to WSDL documents. These tools collect, normalize, and merge policy expressions attached to WSDL bindings and WSDL ports.

To add support for importing custom policy assertions, implement the IPolicyImportExtension interface and then add your implementation to the PolicyImportExtensions property. The MetadataImporter can also load implementations of the IPolicyImportExtension interface registered in your application configuration file. Note that a number of policy importers are registered by default and the order of the registered policy importers is significant.

The metadata system repeatedly calls the System.ServiceModel.Description.IPolicyImportExtension.ImportPolicy(System.ServiceModel.Description.MetadataImporter,System.ServiceModel.Description.PolicyConversionContext) method on all registered policy import extensions for each combination of policy alternatives attached to the message, operation, and endpoint policy subjects. When importing a WSDL port, policies attached to the port and to the corresponding WSDL binding are merged before calling into the policy import extensions. The policy alternatives are made available through a PolicyConversionContext as PolicyAssertionCollection objects. Each PolicyAssertionCollection is a collection of policy assertions represented by XmlElement objects.

The Contract and BindingElements properties on the PolicyConversionContext object expose the ContractDescription and BindingElement objects that were imported from the WSDL. Policy import extensions process policy assertions by finding instances of a particular policy assertion type, making corresponding changes to the ContractDescription or BindingElement objects and then removing the policy assertions from the corresponding PolicyAssertionCollection instance.

The wsp:Optional attribute and nested policy expressions are not normalized, so policy import extensions must handle these policy constructs. Also, policy import extensions may be called multiple times with the same ContractDescription and BindingElement objects, so policy import extensions should be robust to this behavior.

Note:
Invalid or improper metadata can be passed to the importer. Ensure that custom importers are robust to all forms of XML.

See Also

Tasks

How to: Import Custom WSDL
How to: Import Custom Policy Assertions
How to: Write an Extension for the ServiceContractGenerator