System.Text.Encodings.Web 9.0.0-preview.4.24266.19

About

Provides types for encoding and escaping strings for use in JavaScript, HTML, and URLs.

This package is essential for protecting web applications against cross-site scripting (XSS) attacks by safely encoding text, and it offers extensive support for Unicode, allowing fine-grained control over which characters are encoded and which are left unescaped.

Key Features

• Safe encoders for HTML, JavaScript, and URL strings.
• Extensible to support custom encoding scenarios, including the ability to specify Unicode ranges.
• Helps prevent cross-site scripting (XSS) vulnerabilities.
• Flexible Unicode encoding with support for specifying individual or predefined ranges to cover broader sets of characters, including options to avoid escaping specific language character sets.

How to Use

Encoding HTML, JavaScript, and URLs

using System.Text.Encodings.Web;

string unsafeString = "<script>alert('XSS Attack!');</script>";

// HTML encode the string to safely display it on a web page.
string safeHtml = HtmlEncoder.Default.Encode(unsafeString);
Console.WriteLine(safeHtml);
// &lt;script&gt;alert(&#x27;XSS Attack!&#x27;);&lt;/script&gt;

// JavaScript encode the string to safely include it in a JavaScript context.
string safeJavaScript = JavaScriptEncoder.Default.Encode(unsafeString);
Console.WriteLine(safeJavaScript);
// \u003Cscript\u003Ealert(\u0027XSS Attack!\u0027);\u003C/script\u003E

string urlPart = "user input with spaces and & symbols";

// URL encode the string to safely include it in a URL.
string encodedUrlPart = UrlEncoder.Default.Encode(urlPart);
Console.WriteLine(encodedUrlPart);
// user%20input%20with%20spaces%20and%20%26%20symbols

Custom Encoding Scenario with Specific Unicode Ranges

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

TextEncoderSettings customEncoderSettings = new TextEncoderSettings();
customEncoderSettings.AllowCharacters('!', '*', '-', '.', '_', '~'); // RFC 3986 unreserved characters
customEncoderSettings.AllowRange(new UnicodeRange('a', 26));
customEncoderSettings.AllowRange(new UnicodeRange('A', 26));
customEncoderSettings.AllowRange(new UnicodeRange('0', 10));

// Create a URL encoder with the custom settings
UrlEncoder customUrlEncoder = UrlEncoder.Create(customEncoderSettings);

string customUrlPart = "custom data: (@123!)";

// By default, the symbols '(', ')', and '@' are not encoded
string defaultEncoded = UrlEncoder.Default.Encode(customUrlPart);
Console.WriteLine(defaultEncoded);
// custom%20data%3A%20(@123!)

// Now, the symbols '(', ')', and '@' are also encoded
string customEncoded = customUrlEncoder.Encode(customUrlPart);
Console.WriteLine(customEncoded);
// custom%20data%3A%20%28%40123!%29

Serialization with Specific Unicode Character Sets

By default Cyrillic characters are encoded as Unicode escape sequences in JSON.

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

This can be customized by providing a custom JavaScriptEncoder to JsonSerializerOptions:

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

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

More information about this can be found in the How to customize character encoding with System.Text.Json article.

Main Types

The main types provided by this library are:

• System.Text.Encodings.Web.HtmlEncoder
• System.Text.Encodings.Web.JavaScriptEncoder
• System.Text.Encodings.Web.UrlEncoder
• System.Text.Encodings.Web.TextEncoder
• System.Text.Encodings.Web.TextEncoderSettings
• System.Text.Unicode.UnicodeRange
• System.Text.Unicode.UnicodeRanges

Additional Documentation

• API documentation

Feedback & Contributing

System.Text.Encodings.Web is released as open source under the MIT license. Bug reports and contributions are welcome at the GitHub repository.