133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
## 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
|
|
|
|
```csharp
|
|
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);
|
|
// <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 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](https://learn.microsoft.com/dotnet/api/system.text.encodings.web)
|
|
|
|
## 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](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).
|