Nombres de contratos de datos

Artículo
02/27/2011

A veces un cliente y un servicio no comparten los mismos tipos. Aún pueden pasar datos entre sí con tal de que los contratos de datos sean equivalentes en ambos lados. Equivalencia del contrato de datos se basa en el contrato de datos y los nombres de miembros de datos y, por consiguiente, se proporciona un mecanismo para asignar tipos y miembros a esos nombres. En este tema se explican las reglas para nombrar contratos de datos, así como el comportamiento predeterminado de la infraestructura de Windows Communication Foundation (WCF) al crear los nombres.

Reglas básicas

Entre las reglas básicas con respecto a los nombres de los contratos de datos se incluyen:

Un nombre de contrato de datos completo se compone de un espacio de nombres y de un nombre.
Los miembros de datos solo tienen nombres, pero no espacios de nombres.
Al procesar los contratos de datos, la infraestructura de WCF distingue entre mayúsculas y minúsculas tanto en los espacios de nombres como en los nombres de contratos de datos y miembros de datos.

Espacios de nombres de contratos de datos

Un espacio de nombres de contrato de datos toma la forma de un Identificador uniforme de recursos (URI). El URI puede ser absoluto o relativo. De forma predeterminada, se asigna un espacio de nombres que procede del espacio de nombres de Common Language Runtime (CLR) de ese tipo a los contratos de datos de un tipo determinado.

De forma predeterminada, cualquier espacio de nombres CLR (con el formato Clr.Namespace) se asigna al espacio de nombres "http://schemas.datacontract.org/2004/07/Clr.Namespace". Para invalidar este valor predeterminado, aplique el atributo ContractNamespaceAttribute al ensamblado o módulo completo. De manera alternativa, para controlar el espacio de nombres del contrato de datos de cada tipo, establezca la propiedad Namespace del DataContractAttribute.

Nota:
El espacio de nombres "Http://schemas.microsoft.com/2003/10/Serialization” está reservado y no se puede utilizar como un espacio de nombres de contrato de datos.

Nota:
No puede invalidar el espacio de nombres predeterminado en tipos de contratos de datos que contengan declaraciones delegate.

Nombres de contratos de datos

El nombre predeterminado de un contrato de datos de un tipo determinado es el nombre de ese tipo. Para invalidar el valor predeterminado, establezca la propiedad Name del DataContractAttribute en un nombre alternativo. Más adelante, en este tema, se describen las reglas especiales de los tipos genéricos, en la sección "Nombres de contratos de datos para tipos genéricos".

Nombres de miembros de datos

El nombre predeterminado de un miembro de datos de un campo o propiedad determinado es el nombre de ese campo o propiedad. Para invalidar el valor predeterminado, establezca la propiedad Name del DataMemberAttribute en un valor alternativo.

Ejemplos

El siguiente ejemplo muestra cómo puede invalidar el comportamiento de denominación predeterminado de contratos de datos y miembros de datos.

' 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

// 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.
    }
}

Nombres de contratos de datos para tipos genéricos

Existen reglas especiales para determinar los nombres de contratos de datos para tipos genéricos. Estas reglas ayudan a evitar las coincidencias de nombres de contratos de datos entre dos genéricos cerrados del mismo tipo genérico.

De forma predeterminada, el nombre del contrato de datos de un tipo genérico es el nombre del tipo, seguido por la cadena "Of", seguido por los nombres de contratos de datos de los parámetros genéricos, seguido por un hash calculado mediante los espacios de nombres de contrato de datos de los parámetros genéricos. Un hash es el resultado de una función matemática que actúa como una "huella" que identifica identifica de manera única una parte de datos. Cuando todos los parámetros genéricos son de tipo primitivo, se omite el hash.

Por ejemplo, vea los tipos del ejemplo siguiente.

<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

[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.
}

En este ejemplo, el tipo Drawing<Square,RegularRedBrush> tiene el nombre de contrato de datos "DrawingOfSquareRedBrush5HWGAU6h", donde "5HWGAU6h" es un hash de los espacios de nombres "urn:default" y "urn:shapes". El tipo Drawing<Square,SpecialRedBrush> tiene el nombre de contrato de datos "DrawingOfSquareRedBrushjpB5LgQ_S", donde "jpB5LgQ_S" es un hash de los espacios de nombres "urn:shapes" y "urn:special". Tenga en cuenta que, si no se utiliza el hash, los dos nombres son idénticos y se produce un conflicto de nombres.

Personalización de los nombres de contratos de datos para tipos genéricos

A veces, los nombres de contrato de datos generados para tipos genéricos, como se describió previamente, son inaceptables. Por ejemplo, puede conocer de antemano que no se encontrará con nombres coincidentes y puede que desee eliminar el hash. En este caso, puede utilizar la propiedad Name del atributo DataContractAttribute para especificar una manera diferente de generar los nombres. Puede utilizar números dentro de llaves dentro de la propiedad Name para hacer referencia a los nombres de contratos de datos de los parámetros genéricos. (0 hace referencia al primer parámetro, 1 hace referencia al segundo, etc.). Puede utilizar una almohadilla (#) dentro de llaves para hacer referencia al hash. Puede utilizar cada una de estas referencias varias veces o ninguna.

Por ejemplo, el tipo genérico Drawing anterior podría haberse declarado como se muestra en el ejemplo siguiente.

<DataContract(Name:="Drawing_using_{1}_brush_and_{0}_shape")> _
Public Class Drawing(Of Shape, Brush)
    ' Code not shown.
End Class

[DataContract(Name = "Drawing_using_{1}_brush_and_{0}_shape")]
public class Drawing<Shape, Brush>
{
    // Code not shown.
}

En este caso, el tipo Drawing<Square,RegularRedBrush> tiene del el nombre de contrato de datos "Drawing_using_RedBrush_brush_and_Square_shape". Tenga en cuenta que porque hay un "{#}" en la propiedad Name, el hash no forma parte del nombre y por esto el tipo es susceptible a las coincidencias de nombres; por ejemplo, el tipo Drawing<Square,SpecialRedBrush> tendría exactamente el mismo nombre de contrato de datos.

Vea también

Referencia

DataContractAttribute
DataMemberAttribute
ContractNamespaceAttribute

Conceptos

Utilización de contratos de datos
Equivalencia del contrato de datos
Nombres de contratos de datos
Versiones de contratos de datos

Compartir a través de

Nombres de contratos de datos

Reglas básicas

Espacios de nombres de contratos de datos

Nombres de contratos de datos

Nombres de miembros de datos

Ejemplos

Nombres de contratos de datos para tipos genéricos

Personalización de los nombres de contratos de datos para tipos genéricos

Vea también

Referencia

Conceptos

Recursos adicionales