Skip to content

[API Proposal]: UriCreationOptions #59099

Closed

Description

@MihaZupan

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 (%41 turns into A)
  • 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:

  • DangerousUseRawTarget
  • DangerousDisableCanonicalization

Behavior of DangerousUseRawPathAndQuery is such that we try not to be opinionated as much as possible:

  • Validation of the Path/Query is 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. %41 won't be turned into A)
  • We will not compress dot segments (/../ or /./ will be kept)
  • Fragment is always empty – # and anything following it is attributed to the Path or Query
    • Not doing so would disallow sending the # literal as part of PathAndQuery
  • Properties like Path, Query, PathAndQuery will return the value as-is
  • We will not ensure Path/PathAndQuery start with /, that is left up to the user
  • Uris with DangerousUseRawPathAndQuery may only be equal to Uris with the same flag
  • The GetComponents API will ignore the UriFormat argument (values UriEscaped, Unescaped, SafeUnescaped) for Path & Query components

API Usage

string uriString = "/foo";

Uri.TryCreate(uriString, new UriCreationOptions { AllowImplicitFilePaths = false }, out var uri); // False
var options = new UriCreationOptions { DangerousUseRawPathAndQuery = true };
var uri = new Uri("http://foo/%41", options);

// Server receives /%41 instead of /A

Alternative API

  • Instead of a readonly struct, make UriCreationOptions an 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. AllowImplicitFilePaths would have to be DontAllowImplicitFilePaths) to match correctly defaults
    • Defers validation – with UriCreationOptions we can ensure it's always in a valid state (e.g. valid UriKind)
  • Instead of a DangerousUseRawPathAndQuery flag, 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

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

  1. added
    api-suggestionEarly API idea and discussion, it is NOT ready for implementation
    on Sep 14, 2021
  2. ghost added
    untriagedNew issue has not been triaged by the area owner
    on Sep 14, 2021
  3. added
    api-ready-for-reviewAPI is ready for review, it is NOT ready for implementation
    and removed
    api-suggestionEarly API idea and discussion, it is NOT ready for implementation
    untriagedNew issue has not been triaged by the area owner
    on Sep 14, 2021
  4. added this to the 7.0.0 milestone on Sep 14, 2021
  5. added
    blockingMarks issues that we want to fast track in order to unblock other important work
    on Sep 14, 2021
  6. terrajobst commented on Sep 14, 2021

    @terrajobst
    Contributor

    Video

    • The struct should be a mutable struct
      • We should pass it in via in, which means we should mark the getter as readonly
    • GetComponents() should throw InvaliOperationException
      • Note: even UriFormat.Unescaped does some transformations, so this also doesn't make sense to allow
    namespace System
    {
        public struct UriCreationOptions
        {
            public UriKind UriKind { readonly get; set; }
            public bool AllowImplicitFilePaths { readonly get; set; }
            public bool DangerousDisablePathAndQueryCanonicalization { readonly get; set; }
        }
    
        public partial class Uri
        {
            // Existing
            // public Uri(string uriString);
            // public Uri(string uriString, UriKind uriKind);
            public Uri(string uriString, in UriCreationOptions creationOptions);
            
            // Existing
            // public static bool TryCreate(string? uriString, UriKind uriKind, out Uri? result);
            public static bool TryCreate(string? uriString, in UriCreationOptions creationOptions, out Uri? result);
        }
    }
  7. added
    api-approvedAPI was approved in API review, it can be implemented
    and removed
    api-ready-for-reviewAPI is ready for review, it is NOT ready for implementation
    on Sep 14, 2021
  8. 1 remaining item

  9. karelz commented on Sep 20, 2021

    @karelz
    Member

    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:

    public struct UriCreationOptions
    {
        public bool DangerousDisablePathAndQueryCanonicalization { readonly get; set; }
    }
    
    public partial class Uri
    {
        // Existing
        // public Uri(string uriString);
        // public Uri(string uriString, UriKind uriKind);
        public Uri(string uriString, in UriCreationOptions creationOptions);
    
        // Existing
        // public static bool TryCreate(string? uriString, UriKind uriKind, out Uri? result);
        public static bool TryCreate(string? uriString, in UriCreationOptions creationOptions, out Uri? result);
    }

    Remaining parts, not yet implemented:

    public struct UriCreationOptions
    {
        public UriKind UriKind { readonly get; set; }
        public bool AllowImplicitFilePaths { readonly get; set; }
    }
  10. am11 commented on Sep 25, 2021

    @am11
    Member

    Uri has support for implicitly converting a file path into a file:// uri.

    There is one case in RFC 8089, which Uri.TryCreate fails to accept: https://sharplab.io/#gist:7680fb1f8c7f5c0c0a41334e71f3f137. file:c:/foo.txt is allowed, file:/tmp/foo.txt isn't. Would it be allowed implicitly with AllowImplicitFilePaths?

  11. MihaZupan commented on Sep 25, 2021

    @MihaZupan
    MemberAuthor

    AllowImplicitFilePaths would remain true by default.
    If there are other formats we should support, we can discuss it in a separate issue (it would impact the default Uri behavior).

  12. am11 commented on Sep 25, 2021

    @am11
    Member

    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.

  13. MihaZupan commented on Jul 18, 2022

    @MihaZupan
    MemberAuthor

    Note to self: most of the missing implementation work is done in MihaZupan@fef4435 (not updated after #59173).

  14. modified the milestones: 7.0.0, Future on Jul 18, 2022
  15. removed their assignment
    on Jul 18, 2022
  16. WGroenestein commented on Sep 25, 2024

    @WGroenestein

    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)

  17. self-assigned this
    on Jan 28, 2026
  18. added
    in-prThere is an active PR which will close this issue when it is merged
    on Sep 2, 2026
  19. MihaZupan commented on Sep 16, 2026

    @MihaZupan
    MemberAuthor

    I intentionally left out

    public UriKind UriKind { readonly get; set; }

    as not implemented in #133058 as I don't see a real reason to include it for now.

  20. locked and limited conversation to collaborators on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

api-approvedAPI was approved in API review, it can be implementedarea-System.Netin-prThere is an active PR which will close this issue when it is merged

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions