Alat Contract-First
Kontrak layanan sering kali perlu dibuat dari layanan yang ada. Dalam .NET Framework 4.5 dan yang lebih baru, kelas kontrak data dapat dibuat secara otomatis dari layanan yang ada menggunakan alat contract-first. Untuk menggunakan alat kontrak-pertama, file definisi skema XML (XSD) harus diunduh secara lokal; alat ini tidak dapat mengimpor kontrak data jarak jauh melalui HTTP.
Alat kontrak-pertama diintegrasikan ke dalam Visual Studio 2012 sebagai tugas build. File kode yang dihasilkan oleh tugas build dibuat setiap kali proyek dibangun, sehingga proyek dapat dengan mudah mengadopsi perubahan dalam kontrak layanan yang mendasar.
Jenis skema yang dapat diimpor oleh alat contract-first meliputi berikut ini:
<xsd:complexType>
<xsd:simpleType>
</xsd:simpleType>
</xsd:complexType>
Jenis sederhana tidak akan dihasilkan jika mereka primitif seperti Int16 atau String; jenis kompleks tidak akan dihasilkan jika mereka berjenis Collection. Jenis juga tidak akan dihasilkan jika merupakan bagian dari yang lain xsd:complexType. Dalam semua kasus ini, jenis akan dirujuk ke jenis yang ada dalam proyek sebagai gantinya.
Menambahkan kontrak data ke proyek
Sebelum alat kontrak-pertama dapat digunakan, kontrak layanan (XSD) harus ditambahkan ke proyek. Untuk tujuan gambaran umum ini, kontrak berikut akan digunakan untuk mengilustrasikan fungsi kontrak-pertama. Definisi layanan ini adalah subset kecil dari kontrak layanan yang digunakan oleh API pencarian 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>
Untuk menambahkan kontrak layanan di atas ke proyek, klik kanan proyek dan pilih Tambahkan Baru.... Pilih Definisi Skema dari panel WCF dialog Template, dan beri nama file baru SampleContract.xsd. Salin dan tempel kode di atas ke dalam tampilan kode file baru.
Mengonfigurasi opsi contract-first
Opsi kontrak-pertama dapat dikonfigurasi di menu Properti proyek WCF. Untuk mengaktifkan pengembangan kontrak-pertama, pilih kotak centang Aktifkan XSD sebagai Bahasa Definisi Jenis di halaman WCF jendela properti proyek.
Untuk mengonfigurasi properti tingkat lanjut, klik tombol Tingkat Lanjut.
Pengaturan tingkat lanjut berikut dapat dikonfigurasi untuk pembuatan kode dari kontrak. Pengaturan hanya dapat dikonfigurasi untuk semua file dalam proyek; pengaturan tidak dapat dikonfigurasi untuk file individual saat ini.
Mode Serializer: Pengaturan ini menentukan serializer mana yang digunakan untuk membaca file kontrak layanan. Saat Serializer XML dipilih, opsi Jenis Koleksi dan Jenis Penggunaan Kembali dinonaktifkan. Opsi ini hanya berlaku untuk Serializer Kontrak Data.
Jenis Penggunaan Kembali: Pengaturan ini menentukan pustaka mana yang digunakan untuk penggunaan kembali jenis. Pengaturan ini hanya berlaku jika Mode Serializer diatur ke Serializer Kontrak Data.
Jenis Koleksi: Pengaturan ini menentukan jenis yang sepenuhnya memenuhi syarat atau memenuhi syarat perakitan yang akan digunakan untuk jenis data pengumpulan. Pengaturan ini hanya berlaku jika Mode Serializer diatur ke Serializer Kontrak Data.
Jenis Kamus: Pengaturan ini menentukan jenis yang sepenuhnya memenuhi syarat atau memenuhi syarat rakitan yang akan digunakan untuk jenis data kamus.
EnableDataBinding: Pengaturan ini menentukan apakah akan mengimplementasikan INotifyPropertyChanged antarmuka pada semua jenis data untuk menerapkan pengikatan data.
ExcludedTypes:Pengaturan ini menentukan daftar jenis yang sepenuhnya memenuhi syarat atau memenuhi syarat rakitan yang akan dikecualikan dari rakitan yang direferensikan. Pengaturan ini hanya berlaku jika Mode Serializer diatur ke Serializer Kontrak Data.
GenerateInternalTypes: Pengaturan ini menentukan apakah akan menghasilkan kelas yang ditandai sebagai internal. Pengaturan ini hanya berlaku jika Mode Serializer diatur ke Serializer Kontrak Data.
GenerateSerializableTypes: Pengaturan ini menentukan apakah akan menghasilkan kelas dengan SerializableAttribute atribut. Pengaturan ini hanya berlaku jika Mode Serializer diatur ke Serializer Kontrak Data.
ImportXMLTypes: Pengaturan ini menentukan apakah akan mengonfigurasi serializer kontrak data untuk menerapkan SerializableAttribute atribut ke kelas tanpa DataContractAttribute atribut. Pengaturan ini hanya berlaku jika Mode Serializer diatur ke Serializer Kontrak Data.
SupportFx35TypedDataSets: Pengaturan ini menentukan apakah akan menyediakan fungsionalitas tambahan untuk himpunan data jenis yang dibuat untuk .NET Framework 3.5. Ketika Mode Serializer diatur ke Xml Serializer, TypedDataSetSchemaImporterExtensionFx35 ekstensi akan ditambahkan ke pengimpor skema XML saat nilai ini diatur ke True. Ketika Mode Serializer diatur ke Serializer Kontrak Data, jenis DateTimeOffset akan dikecualikan dari Referensi ketika nilai ini diatur ke False, sehingga selalu dihasilkan untuk versi kerangka kerja yang DateTimeOffset lebih lama.
InputXsdFiles: Pengaturan ini menentukan daftar file input. Setiap file harus berisi skema XML yang valid.
Bahasa: Pengaturan ini menentukan bahasa kode kontrak yang dihasilkan. Pengaturan harus dapat dikenali oleh CodeDomProvider.
NamespaceMappings: Pengaturan ini menentukan pemetaan dari Namespace Layanan Target XSD ke namespace CLR. Setiap pemetaan harus menggunakan format berikut:
"Schema Namespace, CLR Namespace"Serializer XML hanya menerima satu pemetaan dalam format berikut:
"*, CLR Namespace"OutputDirectory: Pengaturan ini menentukan direktori tempat file kode akan dibuat.
Pengaturan akan digunakan untuk menghasilkan jenis kontrak layanan dari file kontrak layanan ketika proyek dibangun.
Menggunakan pengembangan kontrak-pertama
Setelah menambahkan kontrak layanan ke proyek dan mengonfirmasi pengaturan build, bangun proyek dengan menekan F6. Jenis yang ditentukan dalam kontrak layanan kemudian akan tersedia untuk digunakan dalam proyek.
Untuk menggunakan jenis yang ditentukan dalam kontrak layanan, tambahkan referensi ke ContractTypes di bawah namespace layanan saat ini:
using MyProjectNamespace.ContractTypes;
Jenis yang ditentukan dalam kontrak layanan kemudian akan dapat diselesaikan dalam proyek, seperti yang ditunjukkan di bawah ini:
Jenis yang dihasilkan oleh alat dibuat dalam file GeneratedXSDTypes.cs. File dibuat di <direktori> proyek/obj/<build configuration>/XSDGeneratedCode/ direktori secara default. Skema sampel di awal artikel ini dikonversi sebagai berikut:
//------------------------------------------------------------------------------
// <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,
}
}
Kesalahan dan peringatan
Kesalahan dan peringatan yang ditemui dalam mengurai skema XSD akan muncul sebagai kesalahan dan peringatan build.
Pewarisan Antarmuka
Tidak dimungkinkan untuk menggunakan pewarisan antarmuka dengan pengembangan kontrak-pertama; ini konsisten dengan cara antarmuka berperilaku dalam operasi lain. Untuk menggunakan antarmuka yang mewarisi antarmuka dasar, gunakan dua titik akhir terpisah. Titik akhir pertama menggunakan kontrak yang diwariskan, dan titik akhir kedua mengimplementasikan antarmuka dasar.