Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / C#

Utf8JsonWriter — scrittura sequenziale di JSON in UTF-8

Utf8JsonWriter di System.Text.Json consente di scrivere manualmente JSON come byte UTF-8 in uno Stream o in un IBufferWriter<byte>. Controlli l’ordine delle proprietà e la struttura del documento, mentre il writer gestisce la sintassi JSON e l’escape delle stringhe.

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

Sintassi

using var writer = new Utf8JsonWriter(destination, new JsonWriterOptions { Indented = false });
writer.WriteStartObject();
writer.WriteString("name", "Ada");
writer.WriteEndObject();
writer.Flush();

Utf8JsonWriter, nello spazio dei nomi System.Text.Json, è un meccanismo di basso livello per scrivere JSON in sequenza come byte UTF-8 in uno Stream o in un IBufferWriter<byte>. Invece di serializzare automaticamente un intero oggetto, ne scrivi esplicitamente proprietà e valori. È utile per creare serializzatori personalizzati, ma non è un albero di documenti modificabile.

Le chiamate WriteStartObject() e WriteEndObject() delimitano un oggetto. WriteString("name", "Ada") scrive una coppia nome-valore, mentre WriteStringValue("csharp") scrive solo un valore, ad esempio un elemento di un array. WriteStartArray("tags") avvia una proprietà array, che viene chiusa con WriteEndArray(). I metodi che scrivono stringhe gestiscono l’escape necessario: non creare JSON concatenando testo.

Per impostazione predefinita, l’output è compatto e la convalida della struttura è attiva; una sequenza di operazioni non valida può causare una InvalidOperationException. JsonWriterOptions permette di configurare, tra le altre, le opzioni Indented e SkipValidation. Disattivando la convalida, la responsabilità della correttezza strutturale passa al codice chiamante.

Prima di leggere il risultato, chiama Flush() per trasferire alla destinazione i byte in attesa. Questo non sostituisce la chiusura di oggetti e array con i metodi appropriati. Usa using per rilasciare il writer. Nell’esempio, Encoding.UTF8.GetString(...) converte i byte scritti in testo solo per visualizzarli. Le API usate sono disponibili in .NET 10 e non richiedono funzionalità del linguaggio in versione preview.

Esempi

using System;
using System.IO;
using System.Text;
using System.Text.Json;

using var stream = new MemoryStream();
using var writer = new Utf8JsonWriter(stream);

writer.WriteStartObject();
writer.WriteString("name", "Ada");
writer.WriteNumber("score", 42);
writer.WriteStartArray("tags");
writer.WriteStringValue("csharp");
writer.WriteStringValue("json");
writer.WriteEndArray();
writer.WriteEndObject();
writer.Flush();

Console.WriteLine(Encoding.UTF8.GetString(stream.ToArray()));

Risultato

{"name":"Ada","score":42,"tags":["csharp","json"]}

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti