Contract-First Tool
Servicecontracten moeten vaak worden gemaakt op basis van bestaande services. In .NET Framework 4.5 en hoger kunnen gegevenscontractklassen automatisch worden gemaakt op basis van bestaande services met behulp van het hulpprogramma contract-first. Als u het hulpprogramma contract-first wilt gebruiken, moet het XML-schemadefinitiebestand (XSD) lokaal worden gedownload; het hulpprogramma kan geen externe gegevenscontracten importeren via HTTP.
Het contract-first-hulpprogramma is als build-taak geïntegreerd in Visual Studio 2012. De codebestanden die door de build-taak worden gegenereerd, worden telkens wanneer het project wordt gemaakt, gemaakt, zodat het project eenvoudig wijzigingen kan aanbrengen in het onderliggende servicecontract.
Schematypen die door het hulpprogramma voor het eerste contract kunnen worden geïmporteerd, zijn onder andere:
<xsd:complexType>
<xsd:simpleType>
</xsd:simpleType>
</xsd:complexType>
Eenvoudige typen worden niet gegenereerd als ze primitieven zijn, zoals Int16 of String; complexe typen worden niet gegenereerd als ze van het type Collectionzijn. Typen worden ook niet gegenereerd als ze deel uitmaken van een andere xsd:complexType. In al deze gevallen worden de typen in plaats daarvan naar bestaande typen in het project verwezen.
Een gegevenscontract toevoegen aan een project
Voordat het contract-first hulpprogramma kan worden gebruikt, moet het servicecontract (XSD) worden toegevoegd aan het project. In het kader van dit overzicht wordt het volgende contract gebruikt om contract-first-functies te illustreren. Deze servicedefinitie is een kleine subset van het servicecontract dat wordt gebruikt door de zoek-API van Bing.
<?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>
Als u het bovenstaande servicecontract aan het project wilt toevoegen, klikt u met de rechtermuisknop op het project en selecteert u Nieuwe toevoegen.... Selecteer Schemadefinitie in het WCF-deelvenster van het dialoogvenster Sjablonen en geef het nieuwe bestand SampleContract.xsd een naam. Kopieer en plak de bovenstaande code in de codeweergave van het nieuwe bestand.
Opties voor contract-first configureren
Contract-first opties kunnen worden geconfigureerd in het menu Eigenschappen van een WCF-project. Als u contract-first-ontwikkeling wilt inschakelen, schakelt u het selectievakje XSD inschakelen als Typedefinitietaal in op de WCF-pagina van het venster met projecteigenschappen.
Als u geavanceerde eigenschappen wilt configureren, klikt u op de knop Geavanceerd.
De volgende geavanceerde instellingen kunnen worden geconfigureerd voor het genereren van code vanuit contracten. Instellingen kan alleen worden geconfigureerd voor alle bestanden in het project. De instellingen kunnen momenteel niet worden geconfigureerd voor afzonderlijke bestanden.
Serializer-modus: Deze instelling bepaalt welke serializer wordt gebruikt voor het lezen van servicecontractbestanden. Wanneer XML Serializer is geselecteerd, worden de opties Verzamelingstypen en Typen hergebruik uitgeschakeld. Deze opties zijn alleen van toepassing op de Serializer van het gegevenscontract.
Typen hergebruiken: met deze instelling geeft u op welke bibliotheken worden gebruikt voor typehergebruik. Deze instelling is alleen van toepassing als de Serializer-modus is ingesteld op Serializer voor gegevenscontract.
Verzamelingstype: Met deze instelling geeft u het volledig gekwalificeerde of assembly-gekwalificeerde type op dat moet worden gebruikt voor het gegevenstype van de verzameling. Deze instelling is alleen van toepassing als de Serializer-modus is ingesteld op Serializer voor gegevenscontract.
Woordenlijsttype: Met deze instelling geeft u het volledig gekwalificeerde of assembly-gekwalificeerde type op dat moet worden gebruikt voor het gegevenstype van de woordenlijst.
EnableDataBinding: met deze instelling wordt aangegeven of de INotifyPropertyChanged interface op alle gegevenstypen moet worden geïmplementeerd om gegevensbinding te implementeren.
ExcludedTypes:Met deze instelling geeft u de lijst met volledig gekwalificeerde of assembly-gekwalificeerde typen op die moeten worden uitgesloten van de assembly's waarnaar wordt verwezen. Deze instelling is alleen van toepassing als de Serializer-modus is ingesteld op Serializer voor gegevenscontract.
GenerateInternalTypes: met deze instelling wordt aangegeven of klassen moeten worden gegenereerd die zijn gemarkeerd als intern. Deze instelling is alleen van toepassing als de Serializer-modus is ingesteld op Serializer voor gegevenscontract.
GenerateSerializableTypes: met deze instelling wordt aangegeven of klassen met het SerializableAttribute kenmerk moeten worden gegenereerd. Deze instelling is alleen van toepassing als de Serializer-modus is ingesteld op Serializer voor gegevenscontract.
ImportXMLTypes: deze instelling geeft aan of de serializer van het gegevenscontract moet worden geconfigureerd om het SerializableAttribute kenmerk toe te passen op klassen zonder het DataContractAttribute kenmerk. Deze instelling is alleen van toepassing als de Serializer-modus is ingesteld op Serializer voor gegevenscontract.
SupportFx35TypedDataSets: met deze instelling wordt aangegeven of er extra functionaliteit moet worden geboden voor getypte gegevenssets die zijn gemaakt voor .NET Framework 3.5. Wanneer de Serializer-modus is ingesteld op XML Serializer, wordt de TypedDataSetSchemaImporterExtensionFx35 extensie toegevoegd aan de XML-schemaimporteur wanneer deze waarde is ingesteld op Waar. Wanneer de Serializer-modus is ingesteld op Serializer voor gegevenscontracten, wordt het type DateTimeOffset uitgesloten van de verwijzingen wanneer deze waarde is ingesteld op Onwaar, zodat er altijd een DateTimeOffset wordt gegenereerd voor oudere frameworkversies.
InputXsdFiles: Met deze instelling wordt de lijst met invoerbestanden opgegeven. Elk bestand moet een geldig XML-schema bevatten.
Taal: Met deze instelling wordt de taal van de gegenereerde contractcode opgegeven. De instelling moet herkenbaar zijn door CodeDomProvider.
NamespaceMappings: met deze instelling worden de toewijzingen van de XSD-doelnaamruimten opgegeven aan CLR-naamruimten. Voor elke toewijzing moet de volgende indeling worden gebruikt:
"Schema Namespace, CLR Namespace"De XML Serializer accepteert slechts één toewijzing in de volgende indeling:
"*, CLR Namespace"OutputDirectory: Met deze instelling geeft u de map op waarin de codebestanden worden gegenereerd.
De instellingen worden gebruikt om servicecontracttypen te genereren op basis van de servicecontractbestanden wanneer het project wordt gebouwd.
Contract-first-ontwikkeling gebruiken
Nadat u het servicecontract aan het project hebt toegevoegd en de build-instellingen hebt bevestigd, bouwt u het project door op F6 te drukken. De typen die in het servicecontract zijn gedefinieerd, zijn vervolgens beschikbaar voor gebruik in het project.
Als u de typen wilt gebruiken die zijn gedefinieerd in het servicecontract, voegt u een verwijzing toe onder ContractTypes de huidige naamruimte:
using MyProjectNamespace.ContractTypes;
De typen die in het servicecontract zijn gedefinieerd, kunnen vervolgens worden omgezet in het project, zoals hieronder wordt weergegeven:
De typen die door het hulpprogramma worden gegenereerd, worden gemaakt in het GeneratedXSDTypes.cs-bestand. Het bestand wordt standaard gemaakt in de <projectmap>/obj/<build configuration>/XSDGeneratedCode/directory. Het voorbeeldschema aan het begin van dit artikel wordt als volgt geconverteerd:
//------------------------------------------------------------------------------
// <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,
}
}
Fouten en waarschuwingen
Fouten en waarschuwingen die zijn opgetreden bij het parseren van het XSD-schema, worden weergegeven als buildfouten en waarschuwingen.
Overname van interface
Het is niet mogelijk om interfaceovername te gebruiken met contract-first ontwikkeling; dit is consistent met de manier waarop interfaces zich gedragen in andere bewerkingen. Gebruik twee afzonderlijke eindpunten om een interface te gebruiken die een basisinterface over neemt. Het eerste eindpunt maakt gebruik van het overgenomen contract en het tweede eindpunt implementeert de basisinterface.