Serialización JSON

La característica de serialización JSON convierte objetos a y del formato JSON. Esto puede ser útil cuando interactué con servicios web, o simplemente para empacar y desempacar datos a un formato de texto fácil.

Para información acerca de la clase JsonUtility, por favor ver la página de ScriptRef de Unity JsonUtility.

Su simple uso

La caraterística de serialización JSON está construida alrededor de una noción de un JSON ‘estructurado’, que significa que usted describe que variables serán almacenadas en sus datos JSON al crear una clase o estructura. Por ejemplo:

[Serializable]
public class MyClass
{
    public int level;
    public float timeElapsed;
    public string playerName;
}

Esto define una clase plana de C# que contiene tres variables - level, timeElapsed, y playerName- y la marca como Serializable, que es necesario para que trabaje con el serializador JSON. Usted luego puede crear una instancia de esto así:

MyClass myObject = new MyClass();
myObject.level = 1;
myObject.timeElapsed = 47.5f;
myObject.playerName = "Dr Charles Francis";

Y serializarlo a formato JSON utilizando JsonUtility.ToJson:

string json = JsonUtility.ToJson(myObject);

Esto resultaría en la variable json conteniendo el string:

{"level":1,"timeElapsed":47.5,"playerName":"Dr Charles Francis"}

Para convertir el JSON devuelta a un objeto, utilice JsonUtility.FromJson:

myObject = JsonUtility.FromJson<MyClass>(json);

Esto va a crear una nueva instancia de MyClass y va a configurar los valores el este utilizando los datos JSON. Si los datos JSON contiene valores que no mapean a campos en MyClass entonces esos valores serán simplemente ignorados, y si a los datos JSON le están faltando valores para los campos en MyClass, entonces esos campos serán dejados en sus valores construidos en el objeto devuelto.

El serializador JSON actualmente no soporta trabajar con JSON ‘sin estructura’ (i.e. navegar y editar el JSON como un árbol arbitrario de valores-key en pares). Si used necesita hacer esto, usted debería mirar una librería JSON que contenga más características.

Sobre-escribiendo objetos con JSON

También es posible tomar datos JSON y serializarlos ‘sobre’ un objeto que esté ya creado, sobre-escribiendo cualquier dato que esté ya presente:

JsonUtility.FromJsonOverwrite(json, myObject);

Cualquier campo en el objeto para el cual el JSON no contiene un valor será dejado sin cambiar. Este método le permite a usted mantener asignaciones a un mínimo al re-utilizar objetos que usted ha creado previamente, y también para ‘patch’ objetos al deliberadamente sobre-escribirlos con JSON que solo contiene un pequeño sub-conjunto de campos.

Tenga en cuenta que la API de JSON Serializer soporta las sub-clases MonoBehaviour y ScriptableObject al igual que structs/clases planas. Sin embargo, cuando de-serialice JSON a sub-clases de MonoBehaviour o ScriptableObject, usted debe utilizar FromJsonOverwrite; FromJson no es soportado y lanzará una excepción.

Tipos Soportados

El API soporta cualquier sub clase MonoBehaviour ScriptableObject, o clase/struct plana con el atributo [Serializable]. El objeto que usted pasa es alimentado al serializador de Unity estándar para procesar, por lo que las mismas reglas y limitaciones aplican como sucede en el Inspector; solamente los campos son serializados, y tipos como Dictionary<> no son soportados.

Pasar otros tipos directamente a la API, por ejemplo tipos primitivos o arreglos, actualmente no se soporta. Por ahora usted necesitará envolver esos tipos en una class o struct o algo parecido.

En el Editor solamente, hay una API paralela - EditorJsonUtility - que le permite a usted serializar cualquier tipo derivado de UnityEngine.Objectambos para y desde JSON. Esto producirá JSON que contiene el mismo dato que la representación YAML del objeto.

Rendimiento

Pruebas benchmark han mostrado JsonUtility en ser significativamente más rápido que soluciones JSON .NET popular (con un poco más de características que algunos de ellos).

Uso de memoria GC está a un mínimo:

• ToJson() asigna memoria GC solamente para el string devuelto.
• FromJson() asigna memoria GC solamente para el objeto devuelto, al igual que otros sub-objetos necesitados (e.g si usted de-serialica un objeto que contiene un arreglo, entonces la memoria GC será asignada para ese arreglo).
• FromJsonOverwrite() asigna memoria GC solamente como sea necesario para campos escritos (por ejemplo strings y arreglos9. Si todos los campos siendo sobre-escritos por el JSON son escritos con un valor, esto no va a asignar memoria GC.

Utilizar el API JsonUtility de un hilo en el fondo es permitido Como con cualquier código multi-hilo, usted debería tener cuidado en no acceder o alterar un objeto en un hilo mientras este está siendo serializado/de-serializado en otro.

Controlando el output de ToJson()

ToJson soporta la impresión bonita del output del JSON. Está apagado por defecto pero usted lo puede prender pasando true como el segundo parámetro.

Los campos pueden ser omitidos desde el output utilizando el atributo [NonSerialized] .

Utilizando FromJson() cuando el tipo no es conocido con tiempo

De-serialice el JSON en una clase o struct que contiene campos ‘comunes’, y luego utilice los valores de esos campos para que trabajen qué tipo usted quiere. Luego de-serialice una segunda vez a ese tipo.