Vertrag zuerst-ToolContract-First Tool

Dienstverträge müssen häufig aus vorhandenen Diensten erstellt werden.Service contracts often need to be created from existing services. In .NET Framework 4.5.NET Framework 4.5 können Datenvertragsklassen mithilfe des Vertrag zuerst-Tools automatisch aus vorhandenen Diensten erstellt werden.In .NET Framework 4.5.NET Framework 4.5, data contract classes can be created automatically from existing services using the contract-first tool. Zum Verwenden des Vertrag zuerst-Tools muss die XSD (XML Schema Definition)-Datei lokal heruntergeladen werden. Das Tool kann keine Remotedatenverträge per HTTP importieren.To use the contract-first tool, the XML schema definition file (XSD) must be downloaded locally; the tool cannot import remote data contracts via HTTP.

Das Vertrag zuerst-Tool ist als Buildaufgabe in Visual Studio 2012Visual Studio 2012 integriert.The contract-first tool is integrated into Visual Studio 2012Visual Studio 2012 as a build task. Die von der Buildaufgabe generierten Codedateien werden bei jeder Projekterstellung erzeugt, sodass das Projekt einfach Änderungen im zugrunde liegenden Dienstvertrag übernehmen kann.The code files generated by the build task are created every time the project is built, so that the project can easily adopt changes in the underlying service contract.

Folgende Schematypen können vom Vertrag zuerst-Tool importiert werden:Schema types that the contract-first tool can import include the following:

<xsd:complexType>  
<xsd:simpleType>  

Einfache Typen werden nicht generiert, wenn es sich um primitive Typen, z. B. Int16 oder String, handelt. Komplexe Typen werden nicht generiert, wenn sie vom Typ Collection sind.Simple types will not be generated if they are primitives such as Int16 or String; complex types will not be generated if they are of type Collection. Typen werden ebenfalls nicht generiert, wenn sie Teil eines anderen xsd:complexType sind.Types will also not be generated if they are part of another xsd:complexType. In allen diesen Fällen werden stattdessen Verweise dieser Typen auf im Projekt vorhandene Typen verwendet.In all these cases, the types will be referenced to existing types in the project instead.

Hinzufügen eines Datenvertrags zu einem ProjektAdding a data contract to a project

Bevor das Vertrag zuerst-Tool verwendet werden kann, muss dem Projekt der Dienstvertrag (XSD) hinzugefügt werden.Before the contract-first tool can be used, the service contract (XSD) must be added to the project. In dieser Übersicht wird zum Veranschaulichen von Vertrag zuerst-Funktionen der folgende Vertrag verwendet.For the purposes of this overview, the following contract will be used to illustrate contract-first functions. Diese Dienstdefinition ist eine kleine Teilmenge des Dienstvertrags, der von der Such-API von Bing verwendet wird.This service definition is a small subset of the service contract used by Bing’s search API.

<?xml version="1.0" encoding="utf-8"?>  
<xs:schema id="ServiceSchema"  
    targetNamespace="http://tempuri.org/ServiceSchema.xsd"  
    elementFormDefault="qualified"  
    xmlns="http://tempuri.org/ServiceSchema.xsd"  
    xmlns:mstns="http://tempuri.org/ServiceSchema.xsd"  
    xmlns:xs="http://www.w3.org/2001/XMLSchema"  
>  
  <xs:complexType name="SearchRequest">  
    <xs:sequence>  
      <xs:element minOccurs="0" maxOccurs="1" name="Version" type="xs:string" default="2.2" />  
      <xs:element minOccurs="0" maxOccurs="1" name="Market" type="xs:string" />  
      <xs:element minOccurs="0" maxOccurs="1" name="UILanguage" type="xs:string" />  
      <xs:element minOccurs="1" maxOccurs="1" name="Query" type="xs:string" />  
      <xs:element minOccurs="1" maxOccurs="1" name="AppId" type="xs:string" />  
      <xs:element minOccurs="0" maxOccurs="1" name="Latitude" type="xs:double" />  
      <xs:element minOccurs="0" maxOccurs="1" name="Longitude" type="xs:double" />  
      <xs:element minOccurs="0" maxOccurs="1" name="Radius" type="xs:double" />  
    </xs:sequence>  
  </xs:complexType>  
  <xs:simpleType name="WebSearchOption">  
    <xs:restriction base="xs:string">  
      <xs:enumeration value="DisableHostCollapsing" />  
      <xs:enumeration value="DisableQueryAlterations" />  
    </xs:restriction>  
  </xs:simpleType>  
</xs:schema>  

Um dem Projekt den obigen Dienstvertrag hinzufügen, mit der rechten Maustaste des Projekts, und wählen Sie neue hinzufügen... .To add the above service contract to the project, right-click the project and select Add New…. Wählen Sie im WCF-Bereich des Dialogfelds Vorlagen die Schemadefinition aus, und benennen Sie die neue Datei mit SampleContract.xsd.Select Schema Definition from the WCF pane of the Templates dialog, and name the new file SampleContract.xsd. Kopieren Sie den obigen Code, und fügen Sie ihn in die Codeansicht der neuen Datei ein.Copy and paste the above code into the code view of the new file.

Konfigurieren von Vertrag zuerst-OptionenConfiguring contract-first options

Vertrag zuerst-Optionen können im Eigenschaftenmenü eines WCF-Projekts konfiguriert werden.Contract-first options can be configured in the Properties menu of a WCF project. Um die Vertrag zuerst-Entwicklung aktivieren möchten, wählen Sie die XSD als Typdefinitionssprache aktivieren Kontrollkästchen in der WCF-Seite des Fensters Eigenschaften Projekt.To enable contract-first development, select the Enable XSD as Type Definition Language check box in the WCF page of the project properties window.

WCF-Projektoptionen mit Vertrag-ersteWCF Project Options showing contract-first

Um erweiterte Eigenschaften zu konfigurieren, klicken Sie auf die Schaltfläche Erweitert.To configure advanced properties, click the Advanced button.

Erweiterte Vertrag-Eigenschaften erstenAdvanced Contract-First Properties

Die folgenden erweiterten Einstellungen können für die Codegenerierung aus Verträgen konfiguriert werden.The following advanced settings can be configured for code generation from contracts. Die Einstellungen können nur für alle Dateien im Projekt konfiguriert werden. Das Konfigurieren der Einstellungen für einzelne Dateien ist derzeit nicht möglich.Settings can only be configured for all of the files in the project; settings cannot be configured for individual files at this time.

  • Serialisierungsmodus: Diese Einstellung legt fest, welches Serialisierungsprogramm zum Lesen von Vertragsdateien verwendet wird.Serializer Mode: This setting determines which serializer is used for reading service contract files. Wenn XML-Serialisierungsprogramm ausgewählt ist, die Auflistungstypen und Typen wiederverwenden Optionen sind deaktiviert.When XML Serializer is selected, the Collection Types and Reuse Types options are disabled. Diese Optionen gelten nur für die Datenvertragsserialisierer.These options only apply to the Data Contract Serializer.

  • Typen wiederverwenden: Diese Einstellung gibt an, welche Bibliotheken für die Wiederverwendung von Typen verwendet werden.Reuse Types: This setting specifies which libraries are used for type reuse. Diese Einstellung gilt nur, wenn Serialisierungsmodus festgelegt ist, um Datenvertragsserialisierer.This setting only applies if Serializer Mode is set to Data Contract Serializer.

  • "Sammlung": Diese Einstellung gibt den vollqualifizierten oder assemblyqualifizierten Typ für den Auflistungsdatentyp verwendet werden soll.Collection Type: This setting specifies the fully-qualified or assembly-qualified type to be used for the collection data type. Diese Einstellung gilt nur, wenn Serialisierungsmodus festgelegt ist, um Datenvertragsserialisierer.This setting only applies if Serializer Mode is set to Data Contract Serializer.

  • Wörterbuchtyp: Diese Einstellung gibt den vollqualifizierten oder assemblyqualifizierten Typ für den wörterbuchdatentyp verwendet werden soll.Dictionary Type: This setting specifies the fully-qualified or assembly-qualified type to be used for the dictionary data type.

  • EnableDataBinding: Diese Einstellung gibt an, ob zum Implementieren der INotifyPropertyChanged -Schnittstelle für alle Datentypen, um die Datenbindung zu implementieren.EnableDataBinding: This setting specifies whether to implement the INotifyPropertyChanged interface on all data types to implement data binding.

  • ExcludedTypes: Diese Einstellung gibt die Liste der vollqualifizierten oder assemblyqualifizierten Typen aus der referenzierten Assemblys ausgeschlossen werden sollen.ExcludedTypes:This setting specifies the list of fully-qualified or assembly-qualified types to be excluded from the referenced assemblies. Diese Einstellung gilt nur, wenn Serialisierungsmodus festgelegt ist, um Datenvertragsserialisierer.This setting only applies if Serializer Mode is set to Data Contract Serializer.

  • GenerateInternalTypes: Diese Einstellung gibt an, ob Klassen generiert werden, die als intern markiert sind.GenerateInternalTypes: This setting specifies whether to generate classes that are marked as internal. Diese Einstellung gilt nur, wenn Serialisierungsmodus festgelegt ist, um Datenvertragsserialisierer.This setting only applies if Serializer Mode is set to Data Contract Serializer.

  • GenerateSerializableTypes: Diese Einstellung gibt an, ob zum Generieren von Klassen, mit der SerializableAttribute Attribut.GenerateSerializableTypes: This setting specifies whether to generate classes with the SerializableAttribute attribute. Diese Einstellung gilt nur, wenn Serialisierungsmodus festgelegt ist, um Datenvertragsserialisierer.This setting only applies if Serializer Mode is set to Data Contract Serializer.

  • ImportXMLTypes: Diese Einstellung gibt an, ob die Datenvertragsserialisierung so anwenden konfiguriert die SerializableAttribute -Attribut auf Klassen ohne das DataContractAttribute Attribut.ImportXMLTypes: This setting specifies whether to configure the data contract serializer to apply the SerializableAttribute attribute to classes without the DataContractAttribute attribute. Diese Einstellung gilt nur, wenn Serialisierungsmodus festgelegt ist, um Datenvertragsserialisierer.This setting only applies if Serializer Mode is set to Data Contract Serializer.

  • SupportFx35TypedDataSets: Diese Einstellung gibt an, ob zusätzliche Funktionen für typisierte Datasets für .net erstellt bereitzustellen Framework 3.5.SupportFx35TypedDataSets: This setting specifies whether to provide additional functionality for typed data sets created for .Net Framework 3.5. Wenn Serialisierungsmodus festgelegt ist, um XML-Serialisierungsprogramm, die TypedDataSetSchemaImporterExtensionFx35 Erweiterung wird an den XML-Schema-Importer hinzugefügt werden, wenn dieser Wert auf "true" festgelegt ist.When Serializer Mode is set to XML Serializer, the TypedDataSetSchemaImporterExtensionFx35 extension will be added to the XML schema importer when this value is set to True. Wenn Serialisierungsmodus festgelegt ist, um Datenvertrags-Serialisierer, den Typ DateTimeOffset werden aus den Referenzen ausgeschlossen werden, wenn dieser Wert auf "false" festgelegt ist, damit eine DateTimeOffset wird immer generiert Bei älteren Framework-Versionen.When Serializer Mode is set to Data Contract Serializer, the type DateTimeOffset will be excluded from the References when this value is set to False, so that a DateTimeOffset is always generated for older framework versions.

  • InputXsdFiles: Diese Einstellung gibt die Liste der Eingabedateien an.InputXsdFiles: This setting specifies the list of input files. Jede Datei muss ein gültiges XML-Schema enthalten.Each file must contain a valid XML schema.

  • Sprache: Diese Einstellung gibt die Sprache für den generierten Vertragscode.Language: This setting specifies the language of the generated contract code. Die Einstellung muss vom CodeDomProvider erkannt werden können.The setting must be recognizable by CodeDomProvider.

  • NamespaceMappings: Diese Einstellung gibt an, das Zuordnungen aus der XSD-Zielnamespaces für CLR-Namespaces.NamespaceMappings: This setting specifies the mappings from the XSD Target Namespaces to CLR namespaces. Jede Zuordnung sollte folgendes Format aufweisen:Each mapping should use the following format:

    "<Schema Namespace>, <CLR Namespace>"  
    

    Die XML-Serialisierung akzeptiert nur eine Zuordnung im folgenden Format:The XML Serializer only accepts one mapping in the following format:

    "*, <CLR Namespace>"  
    
  • OutputDirectory: Diese Einstellung gibt an, das Verzeichnis, in dem die Codedateien generiert werden.OutputDirectory: This setting specifies the directory where the code files will be generated.

Die Einstellungen werden verwendet, um Dienstvertragstypen aus Vertragsdateien zu generieren, wenn das Projekt erstellt wird.The settings will be used to generate service contract types from the service contract files when the project is built.

Verwenden der Vertrag zuerst-EntwicklungUsing contract-first development

Nachdem das Projekt die Dienstvertrag hinzugefügt und die Buildeinstellungen bestätigt haben, erstellen Sie das Projekt durch Drücken von F6.After adding the service contract to the project and confirming the build settings, build the project by pressing F6. Die Typen, die im Dienstvertrag definiert sind, stehen dann für die Verwendung im Projekt bereit.The types defined in the service contract will then be available for use in the project.

Um die im Dienstvertrag definierten Typen zu verwenden, fügen Sie unter dem aktuellen Namespace einen Verweis auf ContractTypes hinzu:To use the types defined in the service contract, add a reference to ContractTypes under the current namespace:

using MyProjectNamespace.ContractTypes;  

Die im Dienstvertrag definierten Typen sind dann wie unten dargestellt im Projekt auflösbar.The types defined in the service contract will then be resolvable in the project, as shown below.

Verwenden von Typen aus einem Dienstvertrag abgeleitetUsing types derived from a service contract

Die vom Tool generierten Typen werden in der Datei GeneratedXSDTypes.cs erstellt.The types generated by the tool are created in the GeneratedXSDTypes.cs file. Die Datei wird erstellt, der <Projektverzeichnis > /obj/<Buildkonfiguration > /XSDGeneratedCode/ Directory standardmäßig.The file is created in the <project directory>/obj/<build configuration>/XSDGeneratedCode/ directory by default. Das Beispielschema am Anfang dieses Themas wird wie folgt konvertiert:The sample schema at the beginning of this topic is converted as follows:

//------------------------------------------------------------------------------  
// <auto-generated>  
//     This code was generated by a tool.  
//     Runtime Version:4.0.30319.17330  
//  
//     Changes to this file may cause incorrect behavior and will be lost if  
//     the code is regenerated.  
// </auto-generated>  
//------------------------------------------------------------------------------  

namespace TestXSD3.ContractTypes  
{  
    using System.Xml.Serialization;  

    /// <remarks/>  
    [System.CodeDom.Compiler.GeneratedCodeAttribute("System.Xml", "4.0.30319.17330")]  
    [System.SerializableAttribute()]  
    [System.Diagnostics.DebuggerStepThroughAttribute()]  
    [System.ComponentModel.DesignerCategoryAttribute("code")]  
    [System.Xml.Serialization.XmlTypeAttribute(Namespace="http://tempuri.org/ServiceSchema.xsd")]  
    [System.Xml.Serialization.XmlRootAttribute(Namespace="http://tempuri.org/ServiceSchema.xsd", IsNullable=true)]  
    public partial class SearchRequest  
    {  

        private string versionField;  

        private string marketField;  

        private string uILanguageField;  

        private string queryField;  

        private string appIdField;  

        private double latitudeField;  

        private bool latitudeFieldSpecified;  

        private double longitudeField;  

        private bool longitudeFieldSpecified;  

        private double radiusField;  

        private bool radiusFieldSpecified;  

        public SearchRequest()  
        {  
            this.versionField = "2.2";  
        }  

        /// <remarks/>  
        [System.ComponentModel.DefaultValueAttribute("2.2")]  
        public string Version  
        {  
            get  
            {  
                return this.versionField;  
            }  
            set  
            {  
                this.versionField = value;  
            }  
        }  

        /// <remarks/>  
        public string Market  
        {  
            get  
            {  
                return this.marketField;  
            }  
            set  
            {  
                this.marketField = value;  
            }  
        }  

        /// <remarks/>  
        public string UILanguage  
        {  
            get  
            {  
                return this.uILanguageField;  
            }  
            set  
            {  
                this.uILanguageField = value;  
            }  
        }  

        /// <remarks/>  
        public string Query  
        {  
            get  
            {  
                return this.queryField;  
            }  
            set  
            {  
                this.queryField = value;  
            }  
        }  

        /// <remarks/>  
        public string AppId  
        {  
            get  
            {  
                return this.appIdField;  
            }  
            set  
            {  
                this.appIdField = value;  
            }  
        }  

        /// <remarks/>  
        public double Latitude  
        {  
            get  
            {  
                return this.latitudeField;  
            }  
            set  
            {  
                this.latitudeField = value;  
            }  
        }  

        /// <remarks/>  
        [System.Xml.Serialization.XmlIgnoreAttribute()]  
        public bool LatitudeSpecified  
        {  
            get  
            {  
                return this.latitudeFieldSpecified;  
            }  
            set  
            {  
                this.latitudeFieldSpecified = value;  
            }  
        }  

        /// <remarks/>  
        public double Longitude  
        {  
            get  
            {  
                return this.longitudeField;  
            }  
            set  
            {  
                this.longitudeField = value;  
            }  
        }  

        /// <remarks/>  
        [System.Xml.Serialization.XmlIgnoreAttribute()]  
        public bool LongitudeSpecified  
        {  
            get  
            {  
                return this.longitudeFieldSpecified;  
            }  
            set  
            {  
                this.longitudeFieldSpecified = value;  
            }  
        }  

        /// <remarks/>  
        public double Radius  
        {  
            get  
            {  
                return this.radiusField;  
            }  
            set  
            {  
                this.radiusField = value;  
            }  
        }  

        /// <remarks/>  
        [System.Xml.Serialization.XmlIgnoreAttribute()]  
        public bool RadiusSpecified  
        {  
            get  
            {  
                return this.radiusFieldSpecified;  
            }  
            set  
            {  
                this.radiusFieldSpecified = value;  
            }  
        }  
    }  

    /// <remarks/>  
    [System.CodeDom.Compiler.GeneratedCodeAttribute("System.Xml", "4.0.30319.17330")]  
    [System.SerializableAttribute()]  
    [System.Xml.Serialization.XmlTypeAttribute(Namespace="http://tempuri.org/ServiceSchema.xsd")]  
    [System.Xml.Serialization.XmlRootAttribute(Namespace="http://tempuri.org/ServiceSchema.xsd", IsNullable=false)]  
    public enum WebSearchOption  
    {  

        /// <remarks/>  
        DisableHostCollapsing,  

        /// <remarks/>  
        DisableQueryAlterations,  
    }  
}  

Fehler und WarnungenErrors and warnings

Fehler und Warnungen, die bei der Analyse des XSD-Schemas auftreten, werden als Buildfehler und Warnungen angezeigt.Errors and warnings encountered in parsing the XSD schema will appear as build errors and warnings.

SchnittstellenvererbungInterface Inheritance

Bei der Vertrag zuerst-Entwicklung kann keine Schnittstellenvererbung verwendet werden. Dies entspricht dem Verhalten von Schnittstellen in anderen Vorgängen.It is not possible to use interface inheritance with contract-first development; this is consistent with the way interfaces behave in other operations. Verwenden Sie für eine Schnittstelle, die eine Basisschnittstelle erbt, zwei verschiedene Endpunkte.In order to use an interface that inherits a base interface, use two separate endpoints. Der erste Endpunkt verwendet den geerbten Vertrag, und der zweite Endpunkt implementiert die Basisschnittstelle.The first endpoint uses the inherited contract, and the second endpoint implements the base interface.