system.text.encodings.web

About

<!-- A description of the package and where one can find more documentation -->

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

<!-- The key features of this package -->

• 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

<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->

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 in this library -->

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

<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->

• API documentation

Feedback & Contributing

<!-- How to provide feedback on this package and contribute to it -->

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