Nástroj Contract-First
Kontrakty služeb je často potřeba vytvářet z existujících služeb. V rozhraní .NET Framework 4.5 a novějších lze třídy kontraktů dat vytvořit automaticky z existujících služeb pomocí nástroje pro první kontrakt. Chcete-li použít nástroj contract-first, soubor definice schématu XML (XSD) musí být stažen místně; nástroj nemůže importovat vzdálené kontrakty dat prostřednictvím protokolu HTTP.
První nástroj kontraktu je integrovaný do sady Visual Studio 2012 jako úloha sestavení. Soubory kódu vygenerované úlohou sestavení se vytvoří při každém sestavení projektu, aby projekt mohl snadno přijmout změny v podkladovém kontraktu služby.
Typy schématu, které nástroj pro kontrakt-first může importovat, zahrnují následující:
<xsd:complexType>
<xsd:simpleType>
</xsd:simpleType>
</xsd:complexType>
Jednoduché typy nebudou generovány, pokud jsou primitivy, například Int16 nebo String; komplexní typy nebudou generovány, pokud jsou typu Collection. Typy také nebudou generovány, pokud jsou součástí jiné xsd:complexType. Ve všech těchto případech budou typy odkazovány na existující typy v projektu.
Přidání kontraktu dat do projektu
Před použitím nástroje pro první kontrakt musí být do projektu přidán kontrakt služby (XSD). Pro účely tohoto přehledu se k ilustraci funkcí prvního kontraktu použije následující kontrakt. Tato definice služby je malá podmnožina kontraktu služby používaného rozhraním API Bingu pro vyhledávání.
<?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>
Chcete-li do projektu přidat výše uvedený kontrakt služby, klikněte pravým tlačítkem myši na projekt a vyberte Přidat nový.... V dialogovém okně Šablony vyberte definici schématu a pojmenujte nový soubor SampleContract.xsd. Zkopírujte a vložte výše uvedený kód do zobrazení kódu nového souboru.
Konfigurace možností pro první kontrakt
V nabídce Vlastnosti projektu WCF je možné konfigurovat možnosti první smlouvy. Chcete-li povolit vývoj pro kontrakty, zaškrtněte políčko Povolit XSD jako jazyk definice typu na stránce WCF okna vlastností projektu.
Chcete-li konfigurovat upřesňující vlastnosti, klikněte na tlačítko Upřesnit.
Následující upřesňující nastavení je možné nakonfigurovat pro generování kódu z kontraktů. Nastavení lze nakonfigurovat pouze pro všechny soubory v projektu; nastavení nelze v tuto chvíli nakonfigurovat pro jednotlivé soubory.
Režim serializátoru: Toto nastavení určuje, který serializátor se používá pro čtení souborů kontraktů služby. Je-li vybrán serializátor XML, jsou zakázány možnosti Typy kolekcí a Znovu použít typy . Tyto možnosti platí pouze pro serializátor kontraktu dat.
Typy opakovaného použití: Toto nastavení určuje, které knihovny se používají pro opakované použití typu. Toto nastavení platí pouze v případě, že je režim serializátoru dat nastaven na serializátor kontraktu dat.
Typ kolekce: Toto nastavení určuje plně kvalifikovaný typ nebo typ kvalifikovaný pro sestavení pro datový typ kolekce. Toto nastavení platí pouze v případě, že je režim serializátoru dat nastaven na serializátor kontraktu dat.
Typ slovníku: Toto nastavení určuje plně kvalifikovaný typ nebo typ sestavení, který se má použít pro datový typ slovníku.
EnableDataBinding: Toto nastavení určuje, jestli se má implementovat INotifyPropertyChanged rozhraní pro všechny datové typy pro implementaci datové vazby.
ExcludedTypes:Toto nastavení určuje seznam plně kvalifikovaných nebo sestavení kvalifikovaných typů, které mají být vyloučeny z odkazovaných sestavení. Toto nastavení platí pouze v případě, že je režim serializátoru dat nastaven na serializátor kontraktu dat.
GenerateInternalTypes: Toto nastavení určuje, zda se mají generovat třídy, které jsou označeny jako interní. Toto nastavení platí pouze v případě, že je režim serializátoru dat nastaven na serializátor kontraktu dat.
GenerateSerializableTypes: Toto nastavení určuje, zda se mají generovat třídy s atributem SerializableAttribute . Toto nastavení platí pouze v případě, že je režim serializátoru dat nastaven na serializátor kontraktu dat.
ImportXMLTypes: Toto nastavení určuje, zda má konfigurace serializátoru kontraktu dat použít SerializableAttribute atribut na třídy bez atributu DataContractAttribute . Toto nastavení platí pouze v případě, že je režim serializátoru dat nastaven na serializátor kontraktu dat.
SupportFx35TypedDataSets: Toto nastavení určuje, jestli se mají poskytovat další funkce pro typové datové sady vytvořené pro rozhraní .NET Framework 3.5. Pokud je serializátor režim nastaven na XML Serializer, TypedDataSetSchemaImporterExtensionFx35 rozšíření bude přidáno do importu schématu XML, pokud je tato hodnota nastavena na True. Pokud je serializační režim nastaven na Serializátor kontrakt dat, typ DateTimeOffset bude vyloučen z odkazy, pokud je tato hodnota nastavena na False, takže DateTimeOffset je vždy generován pro starší verze rozhraní.
InputXsdFiles: Toto nastavení určuje seznam vstupních souborů. Každý soubor musí obsahovat platné schéma XML.
Jazyk: Toto nastavení určuje jazyk generovaného kódu kontraktu. Nastavení musí být rozpoznatelné pomocí CodeDomProvider.
NamespaceMappings: Toto nastavení určuje mapování z cílových oborů názvů XSD na obory názvů CLR. Každé mapování by mělo používat následující formát:
"Schema Namespace, CLR Namespace"Serializátor XML přijímá pouze jedno mapování v následujícím formátu:
"*, CLR Namespace"OutputDirectory: Toto nastavení určuje adresář, ve kterém se budou generovat soubory kódu.
Nastavení se použije k vygenerování typů kontraktů služeb ze souborů kontraktů služeb při sestavení projektu.
Použití vývoje prvního kontraktu
Po přidání kontraktu služby do projektu a potvrzení nastavení sestavení sestavte projekt stisknutím klávesy F6. Typy definované v kontraktu služby budou pak k dispozici pro použití v projektu.
Chcete-li použít typy definované ve smlouvě o poskytování služeb, přidejte do aktuálního oboru názvů odkaz ContractTypes :
using MyProjectNamespace.ContractTypes;
Typy definované ve smlouvě o poskytování služeb se pak v projektu přeloží, jak je znázorněno níže:
Typy vygenerované nástrojem jsou vytvořeny v souboru GeneratedXSDTypes.cs. Soubor se ve výchozím nastavení vytvoří v <adresáři> projektu/obj/<build configuration>/XSDGeneratedCode/directory. Ukázkové schéma na začátku tohoto článku je převedeno takto:
//------------------------------------------------------------------------------
// <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,
}
}
Chyby a upozornění
Chyby a upozornění, ke kterým došlo při analýze schématu XSD, se zobrazí jako chyby sestavení a upozornění.
Dědičnost rozhraní
Dědičnost rozhraní není možné použít s vývojem prvního kontraktu; to je konzistentní se způsobem, jakým se rozhraní chovají v jiných operacích. Pokud chcete použít rozhraní, které dědí základní rozhraní, použijte dva samostatné koncové body. První koncový bod používá zděděný kontrakt a druhý koncový bod implementuje základní rozhraní.