Repository navigation
Description
Background and motivation
Uri validates the input and (if needed) converts it into a normalized (canonical) representation.
For example, it will:
- Escape reserved characters (spaces turn into
%20) - Unescape unreserved characters (
%41turns intoA) - Compress dot segments (
/foo/./bar/../turns into/foo/)
It does this based on the recommendations of the Uri RFC.
Some services, however, rely on specific behavior that may be impossible to replicate using .NET's Uri (#52628, #58057).
For example, it is currently not possible to send /foo?A=%42 with HttpClient, as Uri will convert it to /foo?A=B.
I propose adding a UriCreationOptions type and a ctor/TryCreate overload to consume it, serving as the extension point for future Uri customizability.
Uri has support for implicitly converting a file path into a file:// uri.
/foo is a valid Unix absolute file path and support for Unix paths is limited to non-Windows platforms.
This can create confusion in cases like Uri.TryCreate("/foo", UriKind.Absolute) where the behavior depends on the platform.
Given an extension point like UriCreationOptions is available, I propose adding an AllowImplicitFilePaths flag to it.
API Proposal
namespace System
{
// New type
public readonly struct UriCreationOptions
{
public bool AllowImplicitFilePaths { get; init; }
public bool DangerousUseRawPathAndQuery { get; init; }
public UriKind UriKind { get; }
public UriCreationOptions(UriKind uriKind);
}
public partial class Uri
{
// Existing
public Uri(string uriString);
public Uri(string uriString, UriKind uriKind);
// New
public Uri(string uriString, UriCreationOptions creationOptions);
// Existing
public static bool TryCreate(string? uriString, UriKind uriKind, out Uri? result);
// New
public static bool TryCreate(string? uriString, UriCreationOptions creationOptions, out Uri? result);
}
}Alternative names for DangerousUseRawPathAndQuery:
DangerousUseRawTargetDangerousDisableCanonicalization
Behavior of DangerousUseRawPathAndQuery is such that we try not to be opinionated as much as possible:
- Validation of the
Path/Queryis skipped, we assume they already are in the “perfect format” - We will not escape reserved characters (e.g. spaces won't be turned into
%20) - We will not unescape unreserved characters (e.g.
%41won't be turned intoA) - We will not compress dot segments (
/../or/./will be kept) - Fragment is always empty –
#and anything following it is attributed to thePathorQuery- Not doing so would disallow sending the
#literal as part ofPathAndQuery
- Not doing so would disallow sending the
- Properties like
Path,Query,PathAndQuerywill return the value as-is - We will not ensure
Path/PathAndQuerystart with/, that is left up to the user - Uris with
DangerousUseRawPathAndQuerymay only be equal to Uris with the same flag - The
GetComponentsAPI will ignore theUriFormatargument (valuesUriEscaped,Unescaped,SafeUnescaped) forPath&Querycomponents
API Usage
string uriString = "/foo";
Uri.TryCreate(uriString, new UriCreationOptions { AllowImplicitFilePaths = false }, out var uri); // Falsevar options = new UriCreationOptions { DangerousUseRawPathAndQuery = true };
var uri = new Uri("http://foo/%41", options);
// Server receives /%41 instead of /AAlternative API
-
Instead of a
readonly struct, makeUriCreationOptionsan enum- Prevents us from easily exposing more complex options (e.g. ints, callbacks) in the future
- Forces us into inverting names in some cases (e.g.
AllowImplicitFilePathswould have to beDontAllowImplicitFilePaths) to match correctly defaults - Defers validation – with
UriCreationOptionswe can ensure it's always in a valid state (e.g. validUriKind)
-
Instead of a
DangerousUseRawPathAndQueryflag, expose granular options controlling specific transformations- Example:
UnescapeUnreservedCharacters,CompressDotSegments - Any new scenarios that can't be addressed with existing options are blocked on the decision of the networking team, API review, implementation, and release of a major .NET version
- Complicates the code base & testing - some options may conflict
- Example:
Risks
Setting DangerousUseRawPathAndQuery means no validation/transformation of the input will take place past the authority.
If the input is not already in the correct format, HTTP requests using such a Uri may be malformed.
For example:
- Reserved characters will not be escaped - space characters will not be changed to
%20
Activity
terrajobst commentedon Sep 14, 2021
Video
in, which means we should mark the getter asreadonlyGetComponents()should throwInvaliOperationExceptionUriFormat.Unescapeddoes some transformations, so this also doesn't make sense to allow1 remaining item
karelz commentedon Sep 20, 2021
Part of the API surface was added in 6.0 RC2 to address #52628 and #58057 customer reprots.
Added in 6.0 RC2 and 7.0 PRs:
Remaining parts, not yet implemented:
am11 commentedon Sep 25, 2021
There is one case in RFC 8089, which
Uri.TryCreatefails to accept: https://sharplab.io/#gist:7680fb1f8c7f5c0c0a41334e71f3f137.file:c:/foo.txtis allowed,file:/tmp/foo.txtisn't. Would it be allowed implicitly withAllowImplicitFilePaths?MihaZupan commentedon Sep 25, 2021
AllowImplicitFilePathswould remaintrueby default.If there are other formats we should support, we can discuss it in a separate issue (it would impact the default Uri behavior).
am11 commentedon Sep 25, 2021
I read it as if we are adding a new mode/flag for canonical form to support formats which weren't possible to support before (due to Uri's compatibility concerns). If that's not the case, nvm.
MihaZupan commentedon Jul 18, 2022
Note to self: most of the missing implementation work is done in MihaZupan@fef4435 (not updated after #59173).
WGroenestein commentedon Sep 25, 2024
I might be totally wrong here, but I was not really able to find this (in my eyes) unexpected behavior related to UriKind.Absolute in combination with implicit filepaths (linux) in the docs (msdn). Maybe it would be a great idea to put some giant warning blocks in the docs describing the behavior. And then secondary prioritize the work to have stricter parsing as described above and preferrable deprecate the existing loose parsing (secure by default)
MihaZupan commentedon Sep 16, 2026
I intentionally left out
as not implemented in #133058 as I don't see a real reason to include it for now.