diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 545e946cadccf..3a12f2f7d5bcf 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -85,6 +85,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [HTTP/3 support disabled by default with PublishTrimmed](networking/10.0/http3-disabled-with-publishtrimmed.md) | Source incompatible | Preview 6 | | [HttpClient/SslStream default certificate revocation check mode changed to Online](networking/10.0/ssl-certificate-revocation-check-default.md) | Behavioral change | Preview 6 | | [Streaming HTTP responses enabled by default in browser HTTP clients](networking/10.0/default-http-streaming.md) | Behavioral change | Preview 3 | +| [Uri length limits have been removed](networking/10.0/uri-length-limits-removed.md) | Behavioral change | Preview 7 | ## SDK and MSBuild diff --git a/docs/core/compatibility/networking/10.0/uri-length-limits-removed.md b/docs/core/compatibility/networking/10.0/uri-length-limits-removed.md new file mode 100644 index 0000000000000..58229ea2e4bda --- /dev/null +++ b/docs/core/compatibility/networking/10.0/uri-length-limits-removed.md @@ -0,0 +1,58 @@ +--- +title: "Breaking change: Uri length limits have been removed" +description: "Learn about the .NET 10 breaking change in networking where Uri length limits of around 65k characters have been removed." +ms.date: 12/13/2024 +ai-usage: ai-assisted +--- + +# Uri length limits have been removed + +Methods that create instances (constructors and `TryCreate` factory methods) have historically limited the length of the Uri string to around 65k characters (exact limits varied slightly depending on the input format). As of .NET 10 preview 7, these limits have been lifted such that there is practically no upper bound on how long `Uri`s can be. + +## Version introduced + +.NET 10 Preview 7 + +## Previous behavior + +It was previously not possible to create a instance whose length exceeded around 65k characters. Code like the following example previously threw a with the message "Invalid URI: The Uri string is too long." + +```csharp +new Uri($"https://host/{new string('a', 100_000)}") +``` + +## New behavior + + instances containing large amounts of data can now be created. For example: + +```csharp +string largeQuery = ...; +return new Uri($"https://someService/?query={Uri.EscapeDataString(largeQuery)}"); +``` + +The removed restrictions mainly apply to paths, queries, and fragments as the most practical components to carry large amounts of data. Components such as the scheme and host might still enforce some length limits. Practical limitations as you approach the length limits of `string` also apply, so you may not (nor should you) use to represent a 10 GB file. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Most HTTP servers enforce strict length restrictions on URLs they are willing to accept in requests, generally much lower than 's existing limits. However, since is the de facto exchange type in .NET for Uri-like information, the previous limits limited its use in some scenarios without good workarounds aside from removing the use of throughout API contracts. + +Main scenarios for large are: + +- `data:` uris, which contain arbitrary binary blobs encoded in Base64. These might be transmitted outside of the HTTP request line, for example, they might be part of the request body, and can therefore be arbitrarily large. might now be used to represent data Uris containing larger files. +- Large query strings. is often used as an exchange type between systems even if it will never be sent as part of an HTTP request. User request information is often encoded as part of the query string, so the new behavior enables such scenarios even as the amount of data grows. + +## Recommended action + +For the majority of users, there is no action required. + +If you are relying on imposing such length restrictions as part of your input validation, you must now perform length checking yourself, preferably as a step before you construct the instance. As most HTTP servers are enforcing much stricter length limits in practice, very long inputs were already likely to result in failures when sent as part of an HTTP request. You might find that your scenario would benefit from performing even stricter length validation than had done previously. + +## Affected APIs + +- All constructors +- All overloads +- By extension also all members that return information about the instance, such as , , , and others