Nama Kontrak Data
Terkadang klien dan layanan tidak berbagi jenis yang sama. Mereka masih dapat mengirimkan data satu sama lain selama kontrak data setara di kedua sisi. Kesetaraan Kontrak Data didasarkan pada kontrak data dan nama anggota data, dan oleh karena itu mekanisme disediakan untuk memetakan jenis dan anggota ke nama tersebut. Topik ini menjelaskan aturan penamaan kontrak data serta perilaku default infrastruktur Windows Communication Foundation (WCF) saat membuat nama.
Aturan Dasar
Aturan dasar mengenai penamaan kontrak data meliputi:
Nama kontrak data yang sepenuhnya memenuhi syarat terdiri dari namespace layanan dan nama.
Anggota data hanya memiliki nama, tetapi tidak ada namespace layanan.
Saat memroses kontrak data, infrastruktur WCF peka huruf besar/kecil terhadap namespace layanan dan nama kontrak data dan anggota data.
Namespace Layanan Kontrak Data
Namespace layanan kontrak data mengambil bentuk Pengidentifikasi Sumber Daya Seragam (URI). URI dapat bersifat absolut atau relatif. Secara default, kontrak data untuk jenis tertentu ditetapkan namespace layanan yang berasal dari namespace layanan runtime bahasa umum (CLR) dari jenis tersebut.
Secara default, namespace layanan CLR yang diberikan (dalam format Clr.Namespace) dipetakan ke namespace layanan http://schemas.datacontract.org/2004/07/Clr.Namespace. Untuk mengambil alih default ini, terapkan atribut ContractNamespaceAttribute ke seluruh modul atau rakitan. Atau, untuk mengontrol namespace layanan kontrak data untuk setiap jenis, atur properti Namespace dari DataContractAttribute.
Catatan
Namespace layanan http://schemas.microsoft.com/2003/10/Serialization dicadangkan dan tidak dapat digunakan sebagai namespace layanan kontrak data.
Catatan
Anda tidak dapat mengambil alih namespace layanan default dalam jenis kontrak data yang berisi deklarasi delegate.
Nama Kontrak Data
Nama default kontrak data untuk jenis tertentu adalah nama jenis tersebut. Untuk mengambil alih default, atur properti Name dari DataContractAttribute ke nama alternatif. Aturan khusus untuk jenis generik dijelaskan dalam "Nama Kontrak Data untuk Jenis Generik" nanti dalam topik ini.
Nama Anggota Data
Nama default anggota data untuk bidang atau properti tertentu adalah nama bidang atau properti tersebut. Untuk mengambil alih default, atur properti Name dari DataMemberAttribute ke nilai alternatif.
Contoh
Contoh berikut menunjukkan bagaimana Anda bisa mengambil alih perilaku penamaan default kontrak data dan anggota data.
// This overrides the standard namespace mapping for all contracts
// in Contoso.CRM.
[assembly: ContractNamespace("http://schemas.example.com/crm",
ClrNamespace = "Contoso.CRM")]
namespace Contoso.CRM
{
// The namespace is overridden to become:
// http://schemas.example.com/crm.
// But the name is the default "Customer".
[DataContract]
public class Customer
{
// Code not shown.
}
}
namespace Contoso.OrderProc
{
[DataContract]
public class PurchaseOrder
{
// This data member is named "Amount" by default.
[DataMember]
public double Amount;
// The default is overridden to become "Address".
[DataMember(Name = "Address")]
public string Ship_to;
}
// The namespace is the default value:
// http://schemas.datacontract.org/2004/07/Contoso.OrderProc
// The name is "PurchaseOrder" instead of "MyInvoice".
[DataContract(Name = "PurchaseOrder")]
public class MyInvoice
{
// Code not shown.
}
// The contract name is "Payment" instead of "MyPayment"
// and the Namespace is "http://schemas.example.com" instead
// of the default.
[DataContract(Name = "Payment",
Namespace = "http://schemas.example.com")]
public class MyPayment
{
// Code not shown.
}
}
' This overrides the standard namespace mapping for all contracts
' in Contoso.CRM.
<Assembly: ContractNamespace("http://schemas.example.com/crm", _
ClrNamespace:="Contoso.CRM")>
Namespace Contoso.CRM
' The namespace is overridden to become:
' http://schemas.example.com/crm.
' But the name is the default "Customer".
<DataContract()> _
Public Class Customer
' Code not shown.
End Class
End Namespace
Namespace Contoso.OrderProc
<DataContract()> _
Public Class PurchaseOrder
' This data member is named "Amount" by default.
<DataMember()> _
Public Amount As Double
' The default is overridden to become "Address".
<DataMember(Name:="Address")> _
Public Ship_to As String
End Class
' The namespace is the default value:
' http://schemas.datacontract.org/2004/07/Contoso.OrderProc
' The name is "PurchaseOrder" instead of "MyInvoice".
<DataContract(Name:="PurchaseOrder")> _
Public Class MyInvoice
' Code not shown.
End Class
' The contract name is "Payment" instead of "MyPayment"
' and the Namespace is "http://schemas.example.com" instead
' of the default.
<DataContract(Name:="Payment", [Namespace]:="http://schemas.example.com")> _
Public Class MyPayment
' Code not shown.
End Class
End Namespace
Nama Kontrak Data untuk Jenis Generik
Aturan khusus ada untuk menentukan nama kontrak data untuk jenis generik. Aturan ini membantu menghindari benturan nama kontrak data antara dua generik tertutup dari jenis generik yang sama.
Secara default, nama kontrak data untuk jenis generik adalah nama jenis, diikuti dengan string "Dari", diikuti dengan nama kontrak data parameter generik, diikuti dengan hash yang dikomputasi menggunakan namespace layanan kontrak data dari parameter generik. Hash adalah hasil dari fungsi matematika yang bertindak sebagai "sidik jari" yang secara unik mengidentifikasi sepotong data. Ketika semua parameter generik adalah jenis primitif, hash dihilangkan.
Misalnya, lihat jenis dalam contoh berikut.
[DataContract]
public class Drawing<Shape, Brush>
{
// Code not shown.
}
[DataContract(Namespace = "urn:shapes")]
public class Square
{
// Code not shown.
}
[DataContract(Name = "RedBrush", Namespace = "urn:default")]
public class RegularRedBrush
{
// Code not shown.
}
[DataContract(Name = "RedBrush", Namespace = "urn:special")]
public class SpecialRedBrush
{
// Code not shown.
}
<DataContract()> _
Public Class Drawing(Of Shape, Brush)
<DataContract([Namespace]:="urn:shapes")> _
Public Class Square
' Code not shown.
End Class
<DataContract(Name:="RedBrush", [Namespace]:="urn:default")> _
Public Class RegularRedBrush
' Code not shown.
End Class
<DataContract(Name:="RedBrush", [Namespace]:="urn:special")> _
Public Class SpecialRedBrush
' Code not shown.
End Class
End Class
Dalam contoh ini, jenis Drawing<Square,RegularRedBrush> memiliki nama kontrak data "DrawingOfSquareRedBrush5HWGAU6h", tempat "5HWGAU6h" adalah hash namespace layanan "urn:shapes" dan "urn:default". Jenis Drawing<Square,SpecialRedBrush> ini memiliki nama kontrak data "DrawingOfSquareRedBrushjpB5LgQ_S", tempat "jpB5LgQ_S" adalah hash dari namespace layanan "urn:shapes" dan "urn:special". Perhatikan bahwa jika hash tidak digunakan, kedua nama tersebut identik, dan dengan demikian terjadi benturan nama.
Menyesuaikan nama kontrak data untuk jenis generik
Terkadang, nama kontrak data yang dihasilkan untuk jenis generik, seperti yang dijelaskan sebelumnya, tidak dapat diterima. Misalnya, Anda mungkin tahu terlebih dahulu bahwa Anda tidak akan mengalami benturan nama dan mungkin ingin menghapus hash. Dalam hal ini, Anda dapat menggunakan properti DataContractAttribute.Name untuk menentukan cara yang berbeda untuk menghasilkan nama. Anda dapat menggunakan angka dalam kurung kurawal di dalam properti Name untuk mengacu ke nama kontrak data dari parameter generik. (0 mengacu pada parameter pertama, 1 mengacu pada yang kedua, dan seterusnya.) Anda dapat menggunakan tanda angka (#) di dalam kurung kurawal untuk mengacu ke hash. Anda dapat menggunakan masing-masing referensi ini beberapa kali atau tidak sama sekali.
Misalnya, jenis generik Drawing sebelumnya dapat dinyatakan seperti yang ditunjukkan dalam contoh berikut.
[DataContract(Name = "Drawing_using_{1}_brush_and_{0}_shape")]
public class Drawing<Shape, Brush>
{
// Code not shown.
}
<DataContract(Name:="Drawing_using_{1}_brush_and_{0}_shape")> _
Public Class Drawing(Of Shape, Brush)
' Code not shown.
End Class
Dalam hal ini, jenis Drawing<Square,RegularRedBrush>nya memiliki nama kontrak data "Drawing_using_RedBrush_brush_and_Square_shape". Perhatikan bahwa karena ada "{#}" di properti Name, hash bukan bagian dari nama, dan dengan demikian jenis tersebut rentan terhadap penamaan benturan; misalnya, jenis Drawing<Square,SpecialRedBrush> tersebut akan memiliki nama kontrak data yang sama persis.