Serialización JSON independiente mediante DataContractJsonSerializer

JSON (notación de objetos JavaScript) es un formato de datos diseñado específicamente para que lo use el código JavaScript que se ejecuta en páginas web dentro del explorador. Es el formato de datos predeterminado usado por ASP.NET servicios de AJAX creados en Windows Communication Foundation (WCF).

Este formato también se puede usar al crear servicios de AJAX sin integrar con ASP.NET; en este caso, XML es el valor predeterminado, pero se puede elegir JSON.

Por último, si necesita compatibilidad con JSON pero no crea un servicio AJAX, DataContractJsonSerializer permite serializar directamente objetos .NET en datos JSON y deserializar dichos datos en instancias de tipos .NET. Para obtener una descripción de cómo hacerlo, consulte Cómo: Serializar y deserializar datos JSON.

Al trabajar con JSON, se admiten los mismos tipos de .NET, con algunas excepciones, igual que los que admite DataContractSerializer. Para obtener una lista de los tipos admitidos, vea Tipos admitidos por el serializador de contratos de datos. Esto incluye la mayoría de los tipos primitivos, la mayoría de los tipos de matriz y colección, así como tipos complejos que usan DataContractAttribute y DataMemberAttribute.

Asignación de tipos de .NET a tipos JSON

En la tabla siguiente se muestra la correspondencia entre los tipos de .NET y los tipos JSON/JavaScript cuando se asignan mediante procedimientos de serialización y deserialización.

Enumeraciones y JSON

Los valores de los miembros enumerados se tratan como números en JSON, lo que difiere de su tratamiento en los contratos de datos, donde se incluyen como nombres de los miembros. Para obtener más información sobre el tratamiento del contrato de datos, vea Tipos de enumeración en contratos de datos.

• Por ejemplo, si tiene public enum Color {red, green, blue, yellow, pink}, al serializar yellow, se genera el número 3 y no la cadena "amarillo".

• Todos los miembros enum son serializables. Los EnumMemberAttribute atributos y NonSerializedAttribute se omiten si se usan.

• Es posible deserializar un valor inexistente enum ; por ejemplo, el valor 87 se puede deserializar en la enumeración Color anterior aunque no haya definido ningún nombre de color correspondiente.

• Una marca enum no es especial y se trata igual que cualquier otra enum.

Fechas y horas y JSON

El formato JSON no admite fechas y horas directamente. Sin embargo, se usan con mucha frecuencia y ASP.NET AJAX proporciona compatibilidad especial para estos tipos. Al usar proxies de AJAX en ASP.NET, el tipo DateTime en .NET se corresponde totalmente con el tipo DateTime en JavaScript.

• Cuando no se usa ASP.NET, un DateTime tipo se representa en JSON como una cadena con un formato especial que se describe en la sección Información avanzada de este tema.

• DateTimeOffset se representa en JSON como un tipo complejo: {"DateTime":d ateTime,"OffsetMinutes":offsetMinutes}. El offsetMinutes elemento es el desplazamiento de la hora local respecto a la hora media de Greenwich (GMT), ahora también conocida como hora universal coordinada (UTC), asociada con la ubicación del evento de interés. El dateTime miembro representa el momento en que se produjo el evento de interés (nuevamente, se convierte en un DateTime en JavaScript cuando se utiliza ASP.NET AJAX y en una cadena cuando no se usa). En la serialización, el miembro dateTime siempre se serializa en GMT. Por lo tanto, si se describen las 3:00 a.m. hora de Nueva York, dateTime tiene un componente horario de 8:00 a.m. y offsetMinutes son 300 (menos 300 minutos o 5 horas con respecto a GMT).

  Nota:

  DateTime y DateTimeOffset los objetos, cuando se serializan en JSON, solo conservan la información a la precisión de milisegundos. Los valores de submilisegundos (micro/nanosegundos) se pierden durante la serialización.

Tipos XML y JSON

Los tipos XML se convierten en cadenas JSON.

• Por ejemplo, si un miembro de datos "q" del tipo XElement contiene <abc/>, el json es {"q":"<abc/>"}.

• Hay algunas reglas especiales que especifican cómo se encapsula el código XML. Para obtener más información, consulte la sección Información avanzada más adelante en este artículo.

• Si usa ASP.NET AJAX y no desea usar cadenas en JavaScript, pero quiere que el DOM XML en su lugar establezca la ResponseFormat propiedad en XML en WebGetAttribute o la ResponseFormat propiedad en XML en WebInvokeAttribute.

Colecciones, diccionarios y matrices

Todas las colecciones, diccionarios y matrices se representan en JSON como matrices.

• Cualquier personalización que use CollectionDataContractAttribute se omite en la representación JSON.

• Los diccionarios no son una manera de trabajar directamente con JSON. Puede que no se admita "Diccionario<cadena,objeto>" de la misma manera que en WCF, como se espera con otras tecnologías de JSON. Por ejemplo, si "abc" está asignado a "xyz" y "def" se asigna a 42 en un diccionario, la representación JSON no es {"abc":"xyz","def":42} pero es [{"Key":"abc","Value":"xyz"},{"Key":"def","Value":42}] en su lugar.

• Si desea trabajar directamente con JSON (acceso a claves y valores dinámicamente, sin definir previamente un contrato rígido), tiene varias opciones:

  • Considere la posibilidad de usar el ejemplo de serialización JSON de tipo débil (AJAX).

  • Considere la posibilidad de usar los ISerializable constructores de interfaz y deserialización: estos dos mecanismos permiten acceder a pares clave-valor JSON en la serialización y deserialización, respectivamente, pero no funcionan en escenarios de confianza parcial.

  • Considere la posibilidad de trabajar con la asignación entre JSON y XML en lugar de usar un serializador.

  • El polimorfismo en el contexto de la serialización hace referencia a la capacidad de serializar un tipo derivado donde se espera su tipo base. Hay reglas específicas de JSON al usar colecciones polimórficamente, cuando, por ejemplo, se asigna una colección a un Object. Este problema se describe más detalladamente en la sección Información avanzada más adelante en este artículo.

Detalles adicionales

Orden de los miembros de datos

El orden de los miembros de datos no es importante al usar JSON. En concreto, incluso si Order se establece, los datos JSON todavía se pueden deserializar en cualquier orden.

Tipos JSON

El tipo JSON no tiene que coincidir con la tabla anterior en la deserialización. Por ejemplo, un Int normalmente se asigna a un número JSON, pero también se puede deserializar correctamente desde una cadena JSON siempre que esa cadena contenga un número válido. Es decir, {"q":42} y {"q":"42"} son válidos si hay un Int miembro de datos denominado "q".

Polimorfismo

La serialización polimórfica es la capacidad de serializar un tipo derivado donde se espera su tipo base. Esto es compatible con la serialización de JSON por WCF comparable a la forma en que se admite la serialización XML. Por ejemplo, puede serializar MyDerivedType donde se espera MyBaseType, o serializar Int donde se espera Object.

La información de tipo puede perderse al deserializar un tipo derivado si se espera un tipo base, salvo que esté deserializando un tipo complejo. Por ejemplo, si Uri se serializa donde Object se espera, da como resultado una cadena JSON. Si esta cadena se deserializa de nuevo en Object, se devuelve un objeto .NET String. El deserializador no sabe que la cadena era inicialmente de tipo Uri. Por lo general, cuando se espera Object, todas las cadenas JSON se deserializan como cadenas de .NET y todas las matrices JSON que se usan para serializar colecciones, diccionarios y matrices de .NET se deserializan como .NET Array de tipo Object, independientemente del tipo original real. Un booleano JSON se asigna a un Boolean .NET. Sin embargo, cuando se espera un Object, los números JSON se deserializan como .NET Int32Decimal o Double, donde se selecciona automáticamente el tipo más adecuado.

Al deserializar en un tipo de interfaz, DataContractJsonSerializer deserializa como si el tipo declarado fuese un objeto.

Cuando se trabaja con sus propios tipos base y derivados, normalmente se requiere el uso de KnownTypeAttribute, ServiceKnownTypeAttribute o un mecanismo equivalente. Por ejemplo, si tiene una operación que tiene un Animal valor de retorno y realmente devuelve una instancia de Cat (derivada de Animal), debe aplicar KnownTypeAttribute al tipo Animal o ServiceKnownTypeAttribute a la operación y especificar el tipo Cat en estos atributos. Para obtener más información, vea Tipos conocidos del contrato de datos.

Para obtener más información sobre cómo funciona la serialización polimórfica y una explicación de algunas de las limitaciones que se deben respetar al usarlo, consulte la sección Información avanzada más adelante en este artículo.

Versionamiento

Las características de control de versiones del contrato de datos, incluida la IExtensibleDataObject interfaz, son totalmente compatibles con JSON. Además, en la mayoría de los casos es posible deserializar un tipo en un formato (por ejemplo, XML) y luego serializarlo en otro formato (por ejemplo, JSON) y conservar los datos en IExtensibleDataObject. Para obtener más información, consulte Forward-Compatible Contratos de datos. Recuerde que JSON no está ordenado, por lo que se pierde cualquier información de orden. Además, JSON no admite varios pares clave-valor con el mismo nombre de clave. Por último, todas las operaciones de IExtensibleDataObject son intrínsecamente polimórficas, que es su tipo derivado se asignan a Object, el tipo base para todos los tipos.

JSON en URLs

Al usar endpoints de AJAX de ASP.NET con el verbo HTTP GET (usando el atributo WebGetAttribute), los parámetros entrantes aparecen en la URL de la solicitud, en lugar de en el cuerpo del mensaje. JSON se admite incluso en la dirección URL de solicitud, por lo que si tiene una operación que toma un Int denominado "número" y un Person tipo complejo denominado "p", la dirección URL puede parecerse a la siguiente dirección URL.

http://example.com/myservice.svc/MyOperation?number=7&p={"name":"John","age":42}

Si está utilizando un control de Administrador de scripts de ASP.NET AJAX y un proxy para llamar al servicio, este URL es generado automáticamente por el proxy y no se ve. No se permite utilizar JSON en direcciones URL en puntos de conexión que no son de ASP.NET AJAX.

Información avanzada

Compatible con ISerializable

Tipos compatibles y no compatibles con ISerializable

En general, los tipos que implementan la ISerializable interfaz son totalmente compatibles al serializar o deserializar JSON. Sin embargo, algunos de estos tipos (incluidos algunos tipos de .NET Framework) se implementan de tal manera que los aspectos de serialización específicos de JSON hacen que no se deserialicen correctamente:

• Con ISerializable, el tipo de los miembros de datos individuales nunca se conocen por anticipado. Esto conduce a una situación polimórfica similar a la deserialización de tipos en un objeto . Como se mencionó antes, esto puede provocar la pérdida de información de tipo en JSON. Por ejemplo, un tipo que serializa un enum en su implementación de ISerializable e intenta volver a deserializar correctamente en un enum (sin las conversiones adecuadas) tiene errores, porque una enum se serializa usando números en JSON y los números JSON se deserializan en tipos numéricos .NET integrados (Int32, decimal o doble). Por tanto, el hecho de que el número usado sea un valor enum se pierde.

• Un ISerializable tipo que depende de un orden determinado de deserialización en su constructor de deserialización también puede no deserializar algunos datos JSON, ya que la mayoría de los serializadores JSON no garantizan ningún orden específico.

Tipos de fábrica

Aunque la IObjectReference interfaz se admite en JSON en general, no se admiten los tipos que requieran la característica "tipo de fábrica" (devolviendo una instancia de un tipo diferente del GetRealObject(StreamingContext) tipo que implementa la interfaz).

Formato de conexión DateTime

DateTime Los valores aparecen como cadenas JSON en forma de "/Date(700000+0500)/", donde el primer número (700000 en el ejemplo proporcionado) es el número de milisegundos en la zona horaria GMT, hora normal (sin horario de verano) desde medianoche, 1 de enero de 1970. El número puede ser negativo para representar horas anteriores. La parte del ejemplo que contiene "+0500" es opcional e indica que la hora es de tipo Local, es decir, debe convertirse a la zona horaria local en la deserialización. Si está ausente, el tiempo se deserializa como Utc. El número real ("0500" en este ejemplo) y su signo (+ o -) se omiten.

Al serializar las horas DateTime, Local y Unspecified se escriben con un desplazamiento y Utc se escribe sin él.

El ASP.NET código JavaScript del cliente de AJAX convierte automáticamente estas cadenas en instancias de JavaScript DateTime . Si hay otras cadenas que tienen un formato similar que no son de tipo DateTime en .NET, también se convierten.

La conversión solo tiene lugar si los caracteres "/" llevan caracteres de escape (es decir, el código JSON tiene el aspecto "\/Date(700000+0500)\/") y, por este motivo, el codificador JSON de WCF (habilitado por WebHttpBinding) siempre aplica caracteres de escape al carácter "/".

XML en cadenas JSON

XmlElement

XmlElement se serializa tal como está, sin envoltura. Por ejemplo, el miembro de datos "x" de tipo XmlElement que contiene <abc/> se representa de la siguiente manera:

{"x":"<abc/>"}

Matrices de XmlNode

Array Los objetos de tipo XmlNode se encapsulan en un elemento denominado ArrayOfXmlNode en el espacio de nombres del contrato de datos estándar para el tipo. Si "x" es una matriz que contiene el nodo de atributo "N" en el espacio de nombres "ns" que contiene "value" y un nodo de elemento vacío "M", la representación es la siguiente.

{"x":"<ArrayOfXmlNode xmlns=\"http://schemas.datacontract.org/2004/07/System.Xml\" a:N=\"value\" xmlns:a=\"ns\"><M/></ArrayOfXmlNode>"}

No se admiten los atributos del espacio de nombres vacío al principio de las matrices XmlNode (antes de otros elementos).

Tipos IXmlSerializable incluidos XElement y DataSet

ISerializable tipos se subdividen en "tipos de contenido", "tipos de conjuntos de datos" y "tipos de elementos". Para obtener definiciones de estos tipos, vea XML y ADO.NET Tipos en contratos de datos.

Los tipos "Content" y "DataSet" se serializan de forma similar a los Array objetos de XmlNode descritos en la sección anterior. Se ajustan en un elemento cuyo nombre y espacio de nombres se corresponde al nombre y espacio de nombres del contrato de datos del tipo en cuestión.

Los tipos "Element", como XElement, se serializan tal y como se ha hecho con XmlElement, descrito anteriormente en este artículo.

Polimorfismo

Conservación de la información de tipo

Como se indicó anteriormente, el polimorfismo se admite en JSON con algunas limitaciones. JavaScript es un lenguaje débilmente tipado y la identidad de tipo normalmente no es un problema. Sin embargo, cuando se usa JSON para comunicarse entre un sistema fuertemente tipado (.NET) y un sistema débilmente tipado (JavaScript), resulta útil conservar la identidad de tipo. Por ejemplo, los tipos con nombres de contrato de datos "Cuadrado" y "Círculo" derivan de un tipo con un nombre de contrato de datos "Forma". Si "Circle" se envía desde .NET a JavaScript y posteriormente se devuelve a un método de .NET que espera "Shape", es útil que el lado de .NET sepa que el objeto en cuestión era originalmente un "Círculo", de lo contrario, se puede perder cualquier información específica del tipo derivado (por ejemplo, el miembro de datos "radius" en "Circle").

Para conservar la identidad de tipo, al serializar tipos complejos en JSON se puede agregar una "sugerencia de tipo" y el deserializador reconoce la sugerencia y actúa correctamente. La "sugerencia de tipo" es un par clave-valor JSON con el nombre de clave de "__type" (dos caracteres de subrayado seguidos de la palabra "tipo"). El valor es una cadena JSON del formato "DataContractName:DataContractNamespace" (cualquier cosa hasta el primer signo de dos puntos es el nombre). Con el ejemplo anterior, se puede serializar "Circle" como se indica a continuación.

{"__type":"Circle:http://example.com/myNamespace","x":50,"y":70,"radius":10}

La indicación de tipo es muy similar al estándar de instancia de esquema XML xsi:type, que se usa al serializar o deserializar XML.

Están prohibidos los miembros de datos con el nombre "__type" debido a posibles conflictos con la sugerencia de tipo.

Reducción del tamaño de sugerencias de tipo

Para reducir el tamaño de los mensajes JSON, el prefijo predeterminado del espacio de nombres del contrato de datos (http://schemas.datacontract.org/2004/07/) se reemplaza por el carácter "#". (Para que este reemplazo sea reversible, se usa una regla de escape: si el espacio de nombres comienza con los caracteres "#" o "\", se anexan con un carácter "\" adicional). Por tanto, si "Circle" es un tipo en el espacio de nombres de .NET "MyApp.Shapes", su espacio de nombres de contrato de datos predeterminado es http://schemas.datacontract.org/2004/07/MyApp. Las formas y la representación JSON son las siguientes.

{"__type":"Circle:#MyApp.Shapes","x":50,"y":70,"radius":10}

Tanto los nombres truncados (#MyApp.Shapes) como los nombres completos (http://schemas.datacontract.org/2004/07/MyApp.Shapes) se entienden en la deserialización.

Posición de indicación de tipo en objetos JSON

Tenga en cuenta que la sugerencia de tipo debe aparecer primero en la representación JSON. Este es el único caso en el que el orden de los pares clave-valor es importante en el procesamiento JSON. Por ejemplo, lo siguiente no es una manera válida de especificar la sugerencia de tipo.

{"x":50,"y":70,"radius":10,"__type":"Circle:#MyApp.Shapes"}

Tanto el DataContractJsonSerializer que usa WCF como las páginas de cliente de ASP.NET AJAX siempre emiten primero la sugerencia de tipo.

Las sugerencias de tipo solo se aplican a tipos complejos

No hay ninguna manera de emitir una sugerencia de tipo para tipos no complejos. Por ejemplo, si una operación tiene un Object tipo de valor devuelto pero devuelve un círculo, la representación JSON puede ser como se muestra anteriormente y se conserva la información de tipo. Sin embargo, si se devuelve URI, la representación JSON es una cadena y el hecho de que la cadena usada para representar un URI se pierde. Esto se aplica no solo a tipos primitivos, sino también a colecciones y matrices.

Cuando se emiten sugerencias de tipo

Las sugerencias de tipo pueden aumentar significativamente el tamaño del mensaje (una manera de mitigar esto es usar espacios de nombres para contratos de datos más cortos si es posible). Por consiguiente, rigen las siguientes reglas si se emiten sugerencias de tipo:

• Al usar ASP.NET AJAX, siempre se emiten sugerencias de tipo siempre que sea posible, incluso si no hay ninguna asignación base o derivada, por ejemplo, incluso si se asigna un círculo a un círculo. (Esto es necesario para habilitar completamente el proceso de llamadas desde el entorno JSON de tipo débil al entorno .NET fuertemente tipado sin pérdida inesperada de información).

• Al usar servicios de AJAX sin integración de ASP.NET, las sugerencias de tipo solo se emiten cuando existe una asignación base/derivada, es decir, se emiten cuando un Círculo se asigna a Forma o Object, pero no cuando se asigna a Círculo. Esto proporciona la información mínima necesaria para implementar correctamente un cliente de JavaScript, lo que mejora el rendimiento, pero no protege contra la pérdida de información de tipos en clientes diseñados incorrectamente. Evite las asignaciones base o derivadas por completo en el servidor si desea evitar tratar este problema en el cliente.

• Cuando se usa el DataContractSerializer tipo , el alwaysEmitTypeInformation parámetro constructor permite elegir entre los dos modos anteriores, con el valor predeterminado "false" (solo emite sugerencias de tipo cuando sea necesario).

Nombres de miembros de datos duplicados

La información del tipo derivado está presente en el mismo objeto JSON junto con la información de tipo base y puede producirse en cualquier orden. Por ejemplo, Shape puede representarse de la siguiente manera.

{"__type":"Shape:#MyApp.Shapes","x":50,"y":70}

Mientras que Circle puede representarse de la siguiente manera.

{"__type":"Circle:#MyApp.Shapes","x":50, "radius":10,"y":70}

Si el tipo base Shape también contenía un miembro de datos denominado "radius", esto provoca una colisión en la serialización (porque los objetos JSON no pueden tener nombres de clave repetidos) y deserialización (porque no está claro si "radius" hace referencia a Shape.radius o Circle.radius). Por lo tanto, aunque el concepto de "ocultación de propiedades" (miembros de datos del mismo nombre en clases basadas y derivadas) generalmente no se recomienda en las clases de contrato de datos, en realidad está prohibido en el caso de JSON.

Polimorfismo y tipos IXmlSerializable

IXmlSerializable Los tipos pueden asignarse polimórficamente entre sí siempre y cuando se cumplan los requisitos de tipos conocidos, según las reglas de contrato de datos habituales. Sin embargo, al serializar un tipo IXmlSerializable en lugar de Object, se pierde la información de tipo porque el resultado es una cadena JSON.

Polimorfismo y ciertos tipos de interfaz

Se prohíbe serializar un tipo de colección o un tipo que implemente IXmlSerializable donde no se espera un tipo de no colección IXmlSerializable (excepto para Object). Por ejemplo, una interfaz personalizada denominada IMyInterface y un tipo MyType que implementan tanto IEnumerable<T> de tipo int como IMyInterface. Está prohibido devolver MyType de una operación cuyo tipo de valor devuelto es IMyInterface. Esto se debe a que MyType debe serializarse como una matriz JSON y requiere una sugerencia de tipo y, como ya hemos indicado, no se puede incluir una sugerencia de tipo con matrices, solo con tipos complejos.

Tipos conocidos y configuración

Todos los mecanismos de tipos conocidos usados por DataContractSerializer también se admiten de la misma manera en DataContractJsonSerializer. Ambos serializadores leen el mismo elemento de configuración, <dataContractSerializer> en <system.runtime.serialization>, para detectar los tipos conocidos agregados a través de un archivo de configuración.

Colecciones asignadas al objeto

Las colecciones asignadas a Object se serializan como si fueran colecciones que implementan IEnumerable<T>: una matriz JSON con cada entrada que tenga una sugerencia de tipo si es un tipo complejo. Por ejemplo, un List<T> de tipo Shape asignado a Object tiene un aspecto similar al siguiente.

[{"__type":"Shape:#MyApp.Shapes","x":50,"y":70},
{"__type":"Shape:#MyApp.Shapes","x":58,"y":73},
{"__type":"Shape:#MyApp.Shapes","x":41,"y":32}]

Cuando se deserializa de nuevo en Object:

• Shape debe estar en la lista Tipos conocidos. Tener List<T> del tipo Shape en tipos conocidos no tiene ningún efecto. Tenga en cuenta que no es necesario agregar Shape a tipos conocidos en la serialización en este caso: esto se hace automáticamente.

• La colección se deserializa como un Array de tipo Object que contiene instancias de Shape.

Colecciones derivadas asignadas a colecciones base

Cuando se asigna una colección derivada a una colección base, la colección normalmente se serializa como si fuera una colección del tipo base. Sin embargo, si el tipo de elemento de la colección derivada no se puede asignar al tipo de elemento de la colección base, se produce una excepción.

Sugerencias de tipo y diccionarios

Cuando se asigna un diccionario a Object, cada entrada de Clave y Valor del diccionario se trata como si se hubiera asignado a Object y obtiene una sugerencia de tipo.

Al serializar los tipos de diccionario, el objeto JSON que contiene los miembros "Key" y "Value" no se ve afectado por la alwaysEmitTypeInformation configuración y solo contiene una sugerencia de tipo cuando las reglas de recopilación anteriores lo requieren.

Nombres de clave JSON válidos

El serializador XML codifica los nombres de clave que no son nombres XML válidos. Por ejemplo, un miembro de datos con el nombre "123" tendría un nombre codificado como "_x0031__x0032__x0033_" porque "123" es un nombre de elemento XML no válido (comienza con un dígito). Una situación similar puede surgir con algunos juegos de caracteres internacionales no válidos en nombres XML. Para obtener una explicación de este efecto de XML en el procesamiento JSON, consulte Asignación entre JSON y XML.

Consulte también

• Compatibilidad con JSON y otros formatos de transferencia de datos