Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C#

JsonException — erros de dados JSON

JsonException de System.Text.Json indica JSON inválido, um limite de aninhamento excedido ou um valor incompatível com o tipo de destino. Também disponibiliza informações de diagnóstico que ajudam a localizar o problema nos dados de entrada.

Versão: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Sintaxe

catch (JsonException ex) { /* handle invalid JSON data */ }
throw new JsonException("Invalid JSON value.");

JsonException é uma classe de exceção do espaço de nomes System.Text.Json que herda de Exception. Está disponível no .NET 10; não é uma nova funcionalidade da linguagem C#. Indica sintaxe JSON inválida, uma profundidade máxima excedida ou dados incompatíveis com o tipo de destino. Por isso, uma sintaxe JSON válida não garante uma desserialização bem-sucedida.

Path indica a localização do problema na estrutura JSON. LineNumber e BytePositionInLine começam em zero e são do tipo long?, pelo que podem não ter um valor. BytePositionInLine conta bytes UTF-8, não caracteres. Message descreve o erro; nos testes, é preferível não comparar a mensagem completa gerada pela biblioteca.

Num conversor personalizado, utilize throw new JsonException("Invalid JSON value."); para rejeitar um valor não aceitável. Durante a desserialização, o serializador pode preencher Path, LineNumber e BytePositionInLine, mesmo quando é fornecida uma mensagem própria. Se o conversor lançar a exceção durante a escrita de JSON, o serializador pode preencher Path e deixar LineNumber e BytePositionInLine sem valor. O construtor que aceita uma mensagem e uma exceção interna permite preservar a causa subjacente.

Capture JsonException em torno de uma operação de leitura cuja falha consiga tratar; não a ignore sem tomar medidas. No exemplo, "oops" é uma cadeia JSON válida, mas é incompatível com a propriedade Age do tipo int. O programa apresenta uma mensagem fixa e o caminho $.Age, em vez de uma descrição do erro dependente do ambiente.

Exemplos

using System;
using System.Text.Json;

internal static class Program
{
    private static void Main()
    {
        const string json = "{\"Age\":\"oops\"}";

        try
        {
            JsonSerializer.Deserialize<Person>(json);
            Console.WriteLine("Accepted");
        }
        catch (JsonException ex)
        {
            Console.WriteLine("Rejected JSON value");
            Console.WriteLine($"Path: {ex.Path}");
        }
    }
}

public sealed class Person
{
    public int Age { get; set; }
}

Resultado

Rejected JSON value
Path: $.Age

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes