## 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 ```csharp using System.Text.Encodings.Web; string unsafeString = ""; // HTML encode the string to safely display it on a web page. string safeHtml = HtmlEncoder.Default.Encode(unsafeString); Console.WriteLine(safeHtml); // <script>alert('XSS Attack!');</script> // 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 ```csharp 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. ```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`: ```csharp JsonSerializerOptions options = new JsonSerializerOptions { Encoder = JavaScriptEncoder.Create(UnicodeRanges.BasicLatin, UnicodeRanges.Cyrillic), WriteIndented = true }; jsonString = JsonSerializer.Serialize(weatherForecast, options1); ``` ```json { "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](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/character-encoding) 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](https://learn.microsoft.com/dotnet/api/system.text.encodings.web) ## Feedback & Contributing System.Text.Encodings.Web is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).