Tekencodering aanpassen met System.Text.Json

Artikel
08/23/2023

De serializer escapet standaard alle niet-ASCII-tekens. Dat wil gezegd, deze vervangt ze door \uxxxx de xxxx Unicode-code van het teken. Als de Summary eigenschap in de volgende JSON bijvoorbeeld is ingesteld op Cyrillisch жарко, wordt het WeatherForecast object geserialiseerd zoals wordt weergegeven in dit voorbeeld:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "\u0436\u0430\u0440\u043A\u043E"
}

Taaltekensets serialiseren

Als u de tekenset(en) van een of meer talen wilt serialiseren zonder te ontsnappen, geeft u Unicode-bereiken op bij het maken van een exemplaar van System.Text.Encodings.Web.JavaScriptEncoder, zoals wordt weergegeven in het volgende voorbeeld:

using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;

Imports System.Text.Encodings.Web
Imports System.Text.Json
Imports System.Text.Unicode

var options1 = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.Create(UnicodeRanges.BasicLatin, UnicodeRanges.Cyrillic),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options1);

options = New JsonSerializerOptions With {
    .Encoder = JavaScriptEncoder.Create(UnicodeRanges.BasicLatin, UnicodeRanges.Cyrillic),
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast1, options)

Deze code escapet niet uit Cyrillische of Griekse tekens. Als de Summary eigenschap is ingesteld op Cyrillisch жарко, wordt het WeatherForecast object geserialiseerd zoals wordt weergegeven in dit voorbeeld:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "жарко"
}

De encoder wordt standaard geïnitialiseerd met het BasicLatin bereik.

Als u alle taalsets wilt serialiseren zonder te ontsnappen, gebruikt u UnicodeRanges.All.

Specifieke tekens serialiseren

Een alternatief is om afzonderlijke tekens op te geven die u wilt toestaan zonder te worden ontsnapt. In het volgende voorbeeld worden alleen de eerste twee tekens van жарко:

using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;

Imports System.Text.Encodings.Web
Imports System.Text.Json
Imports System.Text.Unicode

var encoderSettings = new TextEncoderSettings();
encoderSettings.AllowCharacters('\u0436', '\u0430');
encoderSettings.AllowRange(UnicodeRanges.BasicLatin);
var options2 = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.Create(encoderSettings),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options2);

Dim encoderSettings As TextEncoderSettings = New TextEncoderSettings
encoderSettings.AllowCharacters(ChrW(&H436), ChrW(&H430))
encoderSettings.AllowRange(UnicodeRanges.BasicLatin)
options = New JsonSerializerOptions With {
    .Encoder = JavaScriptEncoder.Create(encoderSettings),
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast1, options)

Hier volgt een voorbeeld van JSON dat is geproduceerd door de voorgaande code:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "жа\u0440\u043A\u043E"
}

Lijsten blokkeren

In de voorgaande secties ziet u hoe u lijsten met codepunten of bereiken kunt opgeven die u niet wilt laten ontsnappen. Er zijn echter algemene en encoderspecifieke bloklijsten die bepaalde codepunten in uw acceptatielijst kunnen overschrijven. Codepunten in een bloklijst worden altijd ontsnapt, zelfs als ze zijn opgenomen in uw acceptatielijst.

Algemene bloklijst

De algemene bloklijst bevat zaken zoals tekens voor privégebruik, besturingstekens, niet-gedefinieerde codepunten en bepaalde Unicode-categorieën, zoals de categorie Space_Separator, met uitzondering U+0020 SPACEvan . Wordt bijvoorbeeld U+3000 IDEOGRAPHIC SPACE ontsnapt, zelfs als u het Unicode-bereik CJK-symbolen en interpunctie (U+3000-U+303F) opgeeft als uw acceptatielijst.

De algemene bloklijst is een implementatiedetails die is gewijzigd in elke release van .NET. Neem geen afhankelijkheid van een teken dat lid is van (of geen lid is van) de algemene bloklijst.

Coderingsspecifieke bloklijsten

Voorbeelden van coderingsspecifieke geblokkeerde codepunten zijn onder andere '<' en voor de HTML-encoder, '\' voor de JSON-encoder en '%' voor de URL-encoder'&'. De HTML-encoder escapet bijvoorbeeld altijd uit ampersands ('&'), ook al bevindt het en-teken zich in het BasicLatin bereik en worden alle encoders standaard geïnitialiseerd BasicLatin .

Alle tekens serialiseren

Als u ontsnapping wilt minimaliseren, kunt u deze gebruiken JavaScriptEncoder.UnsafeRelaxedJsonEscaping, zoals wordt weergegeven in het volgende voorbeeld:

using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;

Imports System.Text.Encodings.Web
Imports System.Text.Json
Imports System.Text.Unicode

var options3 = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options3);

options = New JsonSerializerOptions With {
    .Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast1, options)

Let op

In vergelijking met de standaardcoderingsprogramma is de UnsafeRelaxedJsonEscaping encoder meer permissief over het toestaan van tekens om ongezichtig door te geven:

Het escapet geen HTML-gevoelige tekens zoals <, >en &'.
Het biedt geen aanvullende beveiliging tegen XSS- of openbaarmakingsaanvallen voor informatie, zoals aanvallen die kunnen voortvloeien uit de client en server die het niet eens zijn met de charset.

Gebruik de onveilige encoder alleen als bekend is dat de client de resulterende nettolading interpreteert als UTF-8 gecodeerde JSON. U kunt deze bijvoorbeeld gebruiken als de server de antwoordheader Content-Type: application/json; charset=utf-8verzendt. Sta nooit toe dat de onbewerkte UnsafeRelaxedJsonEscaping uitvoer wordt verzonden naar een HTML-pagina of een <script> element.

Share via