Namen van gegevenscontract
Soms delen een client en een service niet dezelfde typen. Ze kunnen nog steeds gegevens aan elkaar doorgeven zolang de gegevenscontracten aan beide zijden gelijkwaardig zijn. Equivalentie van gegevenscontract is gebaseerd op namen van gegevenscontracten en gegevensleden, en daarom wordt een mechanisme geboden om typen en leden toe te wijzen aan deze namen. In dit onderwerp worden de regels voor het benoemen van gegevenscontracten en het standaardgedrag van de WCF-infrastructuur (Windows Communication Foundation) uitgelegd bij het maken van namen.
Basisregels
Basisregels met betrekking tot naamgevingsgegevenscontracten zijn onder andere:
Een volledig gekwalificeerde naam van een gegevenscontract bestaat uit een naamruimte en een naam.
Gegevensleden hebben alleen namen, maar geen naamruimten.
Bij het verwerken van gegevenscontracten is de WCF-infrastructuur hoofdlettergevoelig voor zowel de naamruimten als de namen van gegevenscontracten en gegevensleden.
Naamruimten van gegevenscontract
Een gegevenscontractnaamruimte heeft de vorm van een Uniform Resource Identifier (URI). De URI kan absoluut of relatief zijn. Standaard wordt aan gegevenscontracten voor een bepaald type een naamruimte toegewezen die afkomstig is van de CLR-naamruimte (Common Language Runtime) van dat type.
Standaard wordt een opgegeven CLR-naamruimte (in de indeling Clr.Namespace) toegewezen aan de naamruimte http://schemas.datacontract.org/2004/07/Clr.Namespace. Als u deze standaardwaarde wilt overschrijven, past u het ContractNamespaceAttribute kenmerk toe op de hele module of assembly. Als u de naamruimte van het gegevenscontract voor elk type wilt beheren, stelt u de Namespace eigenschap van het DataContractAttributetype in.
Notitie
De http://schemas.microsoft.com/2003/10/Serialization naamruimte is gereserveerd en kan niet worden gebruikt als gegevenscontractnaamruimte.
Notitie
U kunt de standaardnaamruimte niet overschrijven in gegevenscontracttypen die declaraties bevatten delegate .
Namen van gegevenscontract
De standaardnaam van een gegevenscontract voor een bepaald type is de naam van dat type. Als u de standaardwaarde wilt overschrijven, stelt u de eigenschap van de NameDataContractAttribute eigenschap in op een alternatieve naam. Verderop in dit onderwerp worden speciale regels voor algemene typen beschreven in 'Gegevenscontractnamen voor algemene typen'.
Namen van gegevensleden
De standaardnaam van een gegevenslid voor een bepaald veld of een bepaalde eigenschap is de naam van dat veld of die eigenschap. Als u de standaardwaarde wilt overschrijven, stelt u de Name eigenschap van de DataMemberAttribute eigenschap in op een alternatieve waarde.
Voorbeelden
In het volgende voorbeeld ziet u hoe u het standaardnaamgedrag van gegevenscontracten en gegevensleden kunt overschrijven.
// 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
Namen van gegevenscontracten voor algemene typen
Er bestaan speciale regels voor het bepalen van gegevenscontractnamen voor algemene typen. Deze regels helpen voorkomen dat gegevenscontractnaamconflicten tussen twee gesloten generieken van hetzelfde algemene type voorkomen.
De naam van het gegevenscontract voor een algemeen type is standaard de naam van het type, gevolgd door de tekenreeks 'Van', gevolgd door de namen van het gegevenscontract van de algemene parameters, gevolgd door een hash die wordt berekend met behulp van de naamruimten van het gegevenscontract van de algemene parameters. Een hash is het resultaat van een wiskundige functie die fungeert als een 'vingerafdruk' die een uniek stukje gegevens identificeert. Wanneer alle algemene parameters primitieve typen zijn, wordt de hash weggelaten.
Zie bijvoorbeeld de typen in het volgende voorbeeld.
[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
In dit voorbeeld heeft het type Drawing<Square,RegularRedBrush> de naam van het gegevenscontract 'DrawingOfSquareRedBrush5HWGAU6h', waarbij '5HWGAU6h' een hash is van de naamruimten 'urn:shapes' en 'urn:default'. Het type Drawing<Square,SpecialRedBrush> heeft de naam van het gegevenscontract 'DrawingOfSquareRedBrushjpB5LgQ_S', waarbij 'jpB5LgQ_S' een hash is van de 'urn:shapes' en de 'urn:special'-naamruimten. Houd er rekening mee dat als de hash niet wordt gebruikt, de twee namen identiek zijn en dus een naamconflict optreedt.
Namen van gegevenscontracts aanpassen voor algemene typen
Soms zijn de gegevenscontractnamen die zijn gegenereerd voor algemene typen, zoals eerder beschreven, onaanvaardbaar. U weet bijvoorbeeld van tevoren dat u geen naamconflicten zult tegenkomen en de hash mogelijk wilt verwijderen. In dit geval kunt u de DataContractAttribute.Name eigenschap gebruiken om een andere manier op te geven om namen te genereren. U kunt getallen in accolades in de Name eigenschap gebruiken om te verwijzen naar namen van gegevenscontractnamen van de algemene parameters. (0 verwijst naar de eerste parameter, 1 verwijst naar de tweede, enzovoort.) U kunt een cijferteken (#) in accolades gebruiken om te verwijzen naar de hash. U kunt elk van deze verwijzingen meerdere keren of helemaal niet gebruiken.
Het voorgaande algemene Drawing type kan bijvoorbeeld zijn gedeclareerd zoals weergegeven in het volgende voorbeeld.
[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
In dit geval heeft het type Drawing<Square,RegularRedBrush> de naam van het gegevenscontract 'Drawing_using_RedBrush_brush_and_Square_shape'. Omdat de eigenschap {#} Name bevat, maakt de hash geen deel uit van de naam en is het type dus vatbaar voor naamconflicten. Het type Drawing<Square,SpecialRedBrush> heeft bijvoorbeeld precies dezelfde naamcontractnaam.