[Uri] Uri.EscapeUriString should be deprecated

[lostmsu]

Please, see the relevant StackOveflow thread.

From my understanding of the issue, there is no valid and/or safe use case for EscapeUriString. Either one wants to escape a URI component, in which case they should call EscapeDataString, or they construct URI incorrectly in the first place.

[karelz]

@MihaZupan can you please look into this one to validate the conclusions above?

[MihaZupan]

From the linked thread (emphasis mine):

You should always construct your URLs and query strings by gathering the key-value pairs and percent-encoding and then concatenating them with the necessary separators. You can use Uri.EscapeDataString for this purpose, but not Uri.EscapeUriString, since it doesn't escape reserved characters, as mentioned above.

Only if you cannot do that, e.g. when dealing with user-provided URIs, does it make sense to use Uri.EscapeUriString as a last resort. But the previously mentioned caveats apply – if the user-provided URI is ambiguous, the results may not be desirable.

I believe this is a valid use-case. I am not aware of a direct/better alternative for such a scenario, so I don't think the method can be deprecated. The documentation for it could, however, be updated to note its intended usage - if there are other valid usage scenarios for it I would love to know.

[lostmsu]

@MihaZupan so what is a concrete example, in which case EscapeUriString is required over EscapeDataString?

[MihaZupan]

The two methods have different use-cases.

For example, if you are escaping a query key or value, you should use EscapeDataString.

string uri = "https://foo.bar/?someKey=" + Uri.EscapeDataString(someValue);

But, if you are trying to escape a whole uri, you should not use EscapeDataString as it will encode too much

string userProvidedUri = "http://foo.bar/a b";

string escapeData = Uri.EscapeDataString(userProvidedUri);
// http%3A%2F%2Ffoo.bar%2Fa%20b

string escapeUri = Uri.EscapeUriString(userProvidedUri);
// http://foo.bar/a%20b

That said, I am having trouble finding a uri example where using EscapeUriString is necesarry before passing the string to the ctor.

[lostmsu]

That's exactly the point.

if you are trying to escape a whole uri

If you need to escape a whole URI, what kind of escaping you need to do depends on what are you escaping for.

I suspect (and it might have been mentioned in the original post), that the whole URI might had a need to be escaped for certain browsers which did not support spaces or, for example, instant messengers, which would confuse a space in plain text as a URI's end. But this escaping is highly specific to a concrete browser/IM/other software use case. And EscapeUriString can not be a universal tool: there is no specific standard it adheres to.

What's a real problem though, is that its presence makes it confusing to pick from EscapeDataString and EscapeUriString, as the docs have trouble explaining the difference (in fact, at the moment the docs for the two look semantically identical, sort of proving the point).

https://docs.microsoft.com/en-us/dotnet/api/system.uri.escapeuristring
https://docs.microsoft.com/en-us/dotnet/api/system.uri.escapedatastring

It even has this line "Use the EscapeUriString method to prepare an unescaped URI string to be a parameter to the Uri constructor." And with your example it is clear, that it is outdated, as new Uri("http://foo.bar/a b") works perfectly fine.

[lostmsu]

To further illustrate the problem, just look at this: https://github.com/search?q=EscapeUriString&type=Code

I struggled to find any code example there, in which EscapeUriString would not lead to incorrect input processing under some circumstances discussed in SO thread.

[karelz]

Triage: We should likely make it part of Roslyn Analyzers. @MihaZupan can you please summarize our approach and recommendation.
Overall we don't believe most people are using it correctly.

[lostmsu]

@karelz I think Roslyn Analyzers is insufficient, as they are rarely used. It should at very least be marked with [Obsolete].

Here's another link, that might convince you: https://github.com/search?q=org%3Amicrosoft+EscapeUriString&type=Code

I see one in Microsoft/Docker.DotNet

[karelz]

@lostmsu we have plans to add default Roslyn Analyzers. The rule would be default if 99% cases are incorrectly used. If it is more than that, we may have to make the rule off by default.
Bringing false positives to devs is troublesome -- no matter if it is Obsolete or Analyzer. Analyzers have the nice property of ability to be updated and fine-tuned if necessary.

[karelz]

@aik-jahoda please add the Obsolete attribute, @MihaZupan will help with writing the right docs later.

[aik-jahoda]

Obsoletion status

tracking comment to see status of all necessary steps

• Obsolete Uri.EscapeUriString #41501 - Runtime obsoletion
• .NET 6 preview 3 API updates dotnet-api-docs#6612
• Add SYSLIBXXXX diagnostic details docs#24090
• Redirect https://aka.ms/dotnet-warnings/SYSLIB0013 link to: https://docs.microsoft.com/en-gb/dotnet/fundamentals/syslib-diagnostics/syslib0013

[karelz]

Moving to 6.0 -- we won't backport it to 5.0 this late in the game.

[karelz]

@MihaZupan That said, I am having trouble finding a uri example where using EscapeUriString is necesarry before passing the string to the ctor.

Just found a corner case where it differs:

Console.WriteLine(new Uri("http://my/%20").AbsoluteUri);                      // Output: http://my/%20
Console.WriteLine(new Uri(Uri.EscapeUriString("http://my/%20")).AbsoluteUri); // Output: http://my/%2520

Console.WriteLine(new Uri("http://my/%23").AbsoluteUri);                      // Output: http://my/%23
Console.WriteLine(new Uri(Uri.EscapeUriString("http://my/%23")).AbsoluteUri); // Output: http://my/%2523

[jeffhandley]

@karelz I'm moving this to 7.0 (along with some other obsoletions). Feel free to pull this back into 6.0 if you were still planning to do this for RC1.

[karelz]

@jeffhandley given that this is missing just docs, I think it makes sense to have it in 6.0. I expect that docs will happen post RC1 fork ...

[jeffhandley]

Ah; cool. I overlooked that aspect. Thanks.

[MihaZupan]

The documentation effort seems to be complete here, I linked the relevant PRs where changes happened in #31387 (comment). Closing.

@MihaZupan That said, I am having trouble finding a uri example where using EscapeUriString is necesarry before passing the string to the ctor.

Just found a corner case where it differs:
"http://my/%20" vs EscapeUriString("http://my/%20")

The output may differ, but the Uri ctor will accept the value regardless. Escaping the % to %25 is most likely an unintended consequence of using EscapeUriString for the user.