Reflexão x geração de código-fonte em System.Text.Json

Este artigo explica as diferenças entre a reflexão e a geração de código-fonte no que diz respeito à serialização do System.Text.Json. Também fornece diretrizes sobre como escolher a melhor abordagem para a sua conjuntura.

Coleção de metadados

Para serializar ou desserializar um tipo, JsonSerializer precisa de informações sobre como acessar os membros do tipo. JsonSerializer precisa das seguintes informações:

• Como acessar getters e campos de propriedade para serialização.
• Como acessar um construtor, setters de propriedades e campos para desserialização.
• Informações sobre quais atributos foram usados para customizar a serialização ou desserialização.
• Configuração de runtime de JsonSerializerOptions.

Essas informações são chamadas de metadados.

Reflexão

Por padrão, JsonSerializer coleta metadados em runtime usando reflexão. Sempre que JsonSerializer tiver que serializar ou desserializar um tipo pela primeira vez, ele coleta e armazena em cache esses metadados. O processo de coleta de metadados leva tempo e usa memória.

Geração de código-fonte

Como alternativa, System.Text.Json pode usar o recurso de geração de origem C# para melhorar o desempenho, reduzir o uso de memória privada e facilitar o corte do assembly, o que reduz o tamanho do aplicativo. Além disso, determinadas APIs de reflexão não podem ser usadas em aplicativos nativos de AOT e, portanto, você precisa usar geração de código-fonte para esses aplicativos.

A geração de código-fonte pode ser usada em dois modos:

• Modo baseado em metadados

  Durante a compilação, o System.Text.Json coleta as informações necessárias para a serialização e gera arquivos de código-fonte que preenchem os metadados de contrato JSON para os tipos solicitados.

• Modo de otimização de serialização (caminho rápido)

  Os recursos de JsonSerializer que personalizam a saída da serialização, como políticas de nomenclatura e preservação de referências, implicam uma sobrecarga de desempenho. No modo serialização-otimização, o System.Text.Json gera um código de serialização otimizado que usa o Utf8JsonWriter diretamente. Esse código otimizado ou via rápida aumenta a taxa de transferência da serialização.

  A desserialização via caminho rápido não está disponível no momento. Para obter mais informações, confira problema #55043 dotnet/runtime.

A geração de código-fonte para o System.Text.Json requer o C# versão 9.0 ou posterior.

Note

O suporte a uniões discriminadas em F# funciona apenas no modo de reflexão. Ele requer código dinâmico e metadados de reflexão não removidos. Você não pode usá-lo com geração de código-fonte nem com Native AOT. Para obter mais informações, consulte uniões discriminadas em F#.

Comparação de recursos

Escolha os modos de reflexão ou geração de código-fonte com base nos seguintes benefícios que cada um oferece:

Benefício	Reflexão	Geração de código-fonte (Modo baseado em metadados)	Geração de código-fonte (Modo serialização-otimização)
Mais simples para codificar.	✔️	❌	❌
Mais fácil de depurar.	❌	✔️	✔️
Oferece suporte a [JsonInclude] em membros não públicos.	✔️	✔️*	✔️*
Suporta todas as personalizações de serialização disponíveis.	✔️	❌ †	❌ †
Reduz o tempo de inicialização.	❌	✔️	✔️
Reduz o uso de memória privada.	❌	✔️	✔️
Elimina a reflexão em tempo de execução.	❌	✔️	✔️
Facilita a redução segura do tamanho do aplicativo.	❌	✔️	✔️
Aumenta a taxa de transferência de serialização.	❌	❌	✔️

* A partir do .NET 11, a geração de código-fonte dá suporte aos membros protected, private e internal que você marcar explicitamente com [JsonInclude]. Ele também oferece suporte a acessores private, internal e protected em propriedades que você marca com [JsonInclude]. A geração de origem baseada em metadados dá suporte a construtores inacessíveis que você marca com [JsonConstructor]. Os setters gerados são executados apenas para propriedades que contêm apenas inite que aparecem no JSON; portanto, as propriedades omitidas mantêm seus valores de inicialização. No .NET 10 e em versões anteriores, a geração de código-fonte não dá suporte a membros ou acessores private ou protected, nem a construtores inacessíveis. O contexto gerado pode acessar membros e acessadores de internal somente quando eles compartilham um assembly. Para obter mais informações, consulte membros não públicos e construtores. † Usar a API de personalização do contrato para modificar contratos gerados pelo código-fonte.