Edit

Share via

Schema Import and Export

  • Article

Windows Communication Foundation (WCF) includes a new serialization engine, the DataContractSerializer. The DataContractSerializer translates between .NET Framework objects and XML (in both directions). In addition to the serializer itself, WCF includes associated schema import and schema export mechanisms. Schema is a formal, precise, and machine-readable description of the shape of XML that the serializer produces or that the deserializer can access. WCF uses the World Wide Web Consortium (W3C) XML Schema definition language (XSD) as its schema representation, which is widely interoperable with numerous third-party platforms.

The schema import component, XsdDataContractImporter, takes an XSD schema document and generates .NET Framework classes (normally data contract classes) such that the serialized forms correspond to the given schema.

For example, the following schema fragment:

XsdDataContractImporter importer = new XsdDataContractImporter();
importer.Options.Namespaces.Add(new KeyValuePair<string, string>("http://schemas.contoso.com/carSchema", "Contoso.Cars"));

Dim importer As New XsdDataContractImporter
importer.Options.Namespaces.Add(New KeyValuePair(Of String, String)("http://schemas.contoso.com/carSchema", "Contoso.Cars"))

generates the following type (simplified slightly for better readability).

[DataContract]
public partial class Vehicle : IExtensibleDataObject
{
    private int yearField;
    private string colorField;

    [DataMember]
    public int year
    {
        get { return this.yearField; }
        set { this.yearField = value; }
    }
    [DataMember]
    public string color
    {
        get { return this.colorField; }
        set { this.colorField = value; }
    }

    private ExtensionDataObject extensionDataField;
    public ExtensionDataObject ExtensionData
    {
        get { return this.extensionDataField; }
        set { this.extensionDataField = value; }
    }
}

Partial Class Vehicle
    Implements IExtensibleDataObject

    Private yearField As Integer
    Private colorField As String

    <DataMember()> _
    Public Property year() As Integer
        Get
            Return Me.yearField
        End Get
        Set
            Me.yearField = value
        End Set
    End Property

    <DataMember()> _
    Public Property color() As String
        Get
            Return Me.colorField
        End Get
        Set
            Me.colorField = value
        End Set
    End Property
    Private extensionDataField As ExtensionDataObject

    Public Property ExtensionData() As ExtensionDataObject _
        Implements IExtensibleDataObject.ExtensionData
        Get
            Return Me.extensionDataField
        End Get
        Set(ByVal value As ExtensionDataObject)
            Me.extensionDataField = value
        End Set
    End Property
End Class

Note that the generated type follows several data contract best practices (found in Best Practices: Data Contract Versioning):

  • The type implements the IExtensibleDataObject interface. For more information, see Forward-Compatible Data Contracts.

  • Data members are implemented as public properties that wrap private fields.

  • The class is a partial class, and additions can be made without modifying generated code.

The XsdDataContractExporter enables you to do the reverse—take types that are serializable with the DataContractSerializer and generate an XSD Schema document.

Fidelity Is Not Guaranteed

It is not guaranteed that schema or types make a round trip with total fidelity. (A round trip means to import a schema to create a set of classes, and export the result to create a schema again.) The same schema may not be returned. Reversing the process is also not guaranteed to preserve fidelity. (Export a type to generate its schema, and then import the type back. It is unlikely the same type is returned.)

Supported Types

The data contract model supports only a limited subset of the WC3 schema. Any schema that does not conform to this subset will cause an exception during the import process. For example, there is no way to specify that a data member of a data contract should be serialized as an XML attribute. Thus, schemas that require the use of XML attributes are not supported and will cause exceptions during import, because it is impossible to generate a data contract with the correct XML projection.

For example, the following schema fragment cannot be imported using the default import settings.

<xs:complexType name="Vehicle">
  <xs:sequence>
    <xs:element name="year" type="xs:int" />
    <xs:element name="color" type="xs:string" />
  </xs:sequence>
  <xs:attribute name="engineHorsePower" type="xs:int" />
</xs:complexType>

For more information, see Data Contract Schema Reference. If a schema does not conform to the data contract rules, use a different serialization engine. For example, the XmlSerializer uses its own separate schema import mechanism. Also, there is a special import mode in which the range of supported schema is expanded. For more information, see the section about generating IXmlSerializable types in Importing Schema to Generate Classes.

The XsdDataContractExporter supports any .NET Framework types that can be serialized with the DataContractSerializer. For more information, see Types Supported by the Data Contract Serializer. Note that schema generated using the XsdDataContractExporter is normally valid data that the XsdDataContractImporter can use (unless the XmlSchemaProviderAttribute is used to customize the schema).

For more information about using the XsdDataContractImporter, see Importing Schema to Generate Classes.

For more information about using the XsdDataContractExporter, see Exporting Schemas from Classes.

See also