|
| 1 | +--- |
| 2 | +title: "Breaking change: URI length limits removed" |
| 3 | +description: "Learn about the .NET 10 breaking change in networking where URI length limits of around 65K characters have been removed." |
| 4 | +ms.date: 08/11/2025 |
| 5 | +ai-usage: ai-assisted |
| 6 | +--- |
| 7 | + |
| 8 | +# `Uri` length limits removed |
| 9 | + |
| 10 | +Methods that create <xref:System.Uri> instances (constructors and <xref:System.Uri.TryCreate*> 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. |
| 11 | + |
| 12 | +## Version introduced |
| 13 | + |
| 14 | +.NET 10 Preview 7 |
| 15 | + |
| 16 | +## Previous behavior |
| 17 | + |
| 18 | +Previously, it wasn't possible to create a <xref:System.Uri> instance whose length exceeded around 65,000 characters. Code like the following example threw a <xref:System.UriFormatException> with the message "Invalid URI: The Uri string is too long." |
| 19 | + |
| 20 | +```csharp |
| 21 | +new Uri($"https://host/{new string('a', 100_000)}") |
| 22 | +``` |
| 23 | + |
| 24 | +## New behavior |
| 25 | + |
| 26 | +Starting in .NET 10, <xref:System.Uri> instances containing large amounts of data can now be created. For example: |
| 27 | + |
| 28 | +```csharp |
| 29 | +string largeQuery = ...; |
| 30 | +return new Uri($"https://someService/?query={Uri.EscapeDataString(largeQuery)}"); |
| 31 | +``` |
| 32 | + |
| 33 | +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 <xref:System.Uri> to represent a 10 GB file. |
| 34 | + |
| 35 | +## Type of breaking change |
| 36 | + |
| 37 | +This change is a [behavioral change](../../categories.md#behavioral-change). |
| 38 | + |
| 39 | +## Reason for change |
| 40 | + |
| 41 | +Most HTTP servers enforce strict length restrictions on URLs they are willing to accept in requests. The limits are generally much lower than <xref:System.Uri>'s previous limits. However, since <xref:System.Uri> 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 <xref:System.Uri> throughout API contracts. |
| 42 | + |
| 43 | +The main scenarios for large <xref:System.Uri> are: |
| 44 | + |
| 45 | +- `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. <xref:System.Uri> can now be used to represent data URIs containing larger files. |
| 46 | +- Large query strings. <xref:System.Uri> 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. |
| 47 | + |
| 48 | +## Recommended action |
| 49 | + |
| 50 | +For most users, there is no action required. |
| 51 | + |
| 52 | +If you rely on <xref:System.Uri> 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 <xref:System.Uri> 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 <xref:System.Uri> had done previously. |
| 53 | + |
| 54 | +## Affected APIs |
| 55 | + |
| 56 | +- <xref:System.Uri.%23ctor*> |
| 57 | +- <xref:System.Uri.TryCreate*?displayProperty=fullName> |
| 58 | +- All <xref:System.Uri> members that return information about the <xref:System.Uri> instance, such as: |
| 59 | + - <xref:System.Uri.AbsolutePath?displayProperty=fullName> |
| 60 | + - <xref:System.Uri.AbsoluteUri?displayProperty=fullName> |
| 61 | + - <xref:System.Uri.PathAndQuery?displayProperty=fullName> |
0 commit comments