diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 545e946cadccf..2b66588907eaa 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 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..99bf1830872d5 --- /dev/null +++ b/docs/core/compatibility/networking/10.0/uri-length-limits-removed.md @@ -0,0 +1,61 @@ +--- +title: "Breaking change: URI length limits removed" +description: "Learn about the .NET 10 breaking change in networking where URI length limits of around 65K characters have been removed." +ms.date: 08/11/2025 +ai-usage: ai-assisted +--- + +# `Uri` length limits removed + +Methods that create instances (constructors and factory methods) have historically limited the length of the URI string to around 65,000 characters (exact limits varied slightly depending on the input format). These limits have been lifted such that there is practically no upper bound on how long `Uri` instances can be. + +## Version introduced + +.NET 10 Preview 7 + +## Previous behavior + +Previously, it wasn't possible to create a instance whose length exceeded around 65,000 characters. Code like the following example 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 + +Starting in .NET 10, 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 can't (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. The limits are generally much lower than 's previous 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. + +The 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. can 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 most users, there is no action required. + +If you rely on to impose 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 enforce 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 members that return information about the instance, such as: + - + - + - diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 5d759fa5537af..d56281e341f75 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -88,6 +88,8 @@ items: href: networking/10.0/ssl-certificate-revocation-check-default.md - name: Streaming HTTP responses enabled by default in browser HTTP clients href: networking/10.0/default-http-streaming.md + - name: "'Uri' length limits removed" + href: networking/10.0/uri-length-limits-removed.md - name: SDK and MSBuild items: - name: .NET CLI `--interactive` defaults to `true` in user scenarios