Partilhar via

System.Text.Json verifica conflitos com nomes de propriedades

Em certos contextos, como polimorfismo e preservação de referências, System.Text.Json reservam nomes específicos de propriedades (por exemplo, $type, $id, e $ref) para emitir metadados. Alguns nomes de propriedades, como o TypeDiscriminatorPropertyName , também podem ser configurados com nomes personalizados. Anteriormente, o serializador não realizava validação para saber se estes nomes de propriedades entravam em conflito com contratos definidos pelo utilizador, o que podia resultar em propriedades duplicadas e produzir JSON ambíguo ou que não conseguia fazer ida e volta. A partir do .NET 10, o System.Text.Json permite validação para prevenir tais configurações e fornece aviso precoce aos utilizadores.

Versão introduzida

.NET 10

Comportamento anterior

Anteriormente, o código seguinte produzia um objeto JSON inválido com propriedades duplicadas Type e falhou em desserializar com um JsonException:

using System.Text.Json;
using System.Text.Json.Serialization;

string json = JsonSerializer.Serialize<Animal>(new Dog());
Console.WriteLine(json); // {"Type":"dog","Type":"Dog"}
JsonSerializer.Deserialize<Animal>(json); // JsonException: Deserialized object contains a duplicate 'Type' metadata property.

[JsonPolymorphic(TypeDiscriminatorPropertyName = "Type")]
[JsonDerivedType(typeof(Dog), "dog")]
public abstract class Animal
{
    public abstract string Type { get; }
}

public class Dog : Animal
{
    public override string Type => "Dog";
}

Novo comportamento

A partir do .NET 10, qualquer tentativa de serializar esse mesmo tipo resulta num erro de validação precoce:

InvalidOperationException: O tipo 'Dog' contém a propriedade 'Type' que conflita com o nome de uma propriedade de metadados existente. Considere renomeá-lo ou ignorá-lo com JsonIgnoreAttribute.

Este erro de validação ocorre quando o serializador é criado pela primeira vez ou quando a serialização é tentada pela primeira vez, proporcionando a deteção precoce de contratos de serialização inválidos.

Tipo de mudança disruptiva

Esta alteração é de natureza comportamental .

Motivo da mudança

Esta alteração proporciona uma prevenção precoce de contratos de serialização inválidos. Ao validar os nomes das propriedades antecipadamente, o serializador previne cenários em que propriedades duplicadas sejam emitidas, resultando em JSON inválido que não consegue fazer o round-trip corretamente. Isto ajuda os programadores a identificar e corrigir problemas de configuração durante o desenvolvimento, em vez de os descobrir em tempo de execução durante a desserialização.

Para obter mais informações, consulte:

Evite usar nomes de propriedades que entrem em conflito com propriedades de metadados específicas do System.Text.Json (como $type, $id, e $ref). Se for absolutamente necessário manter essa propriedade na classe, aplique uma anotação JsonIgnoreAttribute na propriedade em conflito.

APIs afetadas

  • Last updated on