dotnet / dotnet/dotnet-api-docs
Missing warning note on HttpUtility.UrlEncode()?
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
### Type of issue
Missing information
### Description
I needed to escape some values to insert in a URI query string. I found the following methods (maybe there are more?):
- `HttpUtility.UrlEncode()` (no warning note but I think there should be one (see below), [link](https://learn.microsoft.com/en-us/dotnet/api/system.web.httputility.urlencode?view=net-10.0))
- `HttpUtility.UrlPathEncode()` (**DO NOT USE** (but not deprecated), [link](https://learn.microsoft.com/en-us/dotnet/api/system.web.httputility.urlpathencode?view=net-10.0))
- `WebUtility.UrlEncode()` (note about non-standard behavior, [link](https://learn.microsoft.com/en-us/dotnet/api/system.net.webutility.urlencode?view=net-10.0#system-net-webutility-urlencode(system-string)))
- `Uri.EscapeDataString()` (the only standard-compliant one?, [link](https://learn.microsoft.com/en-us/dotnet/api/system.uri.escapedatastring?view=net-10.0))
- `Uri.EscapeUriString()` (**OBSOLETE**, [link](https://learn.microsoft.com/en-us/dotnet/api/system.uri.escapeuristring?view=net-10.0))
- `Uri.EscapeString()` (**OBSOLETE**, [link](https://learn.microsoft.com/en-us/dotnet/api/system.uri.escapestring?view=net-10.0))
The most standard-conforming methods seems to be `Uri.EscapeDataString()`. At first, I used `HttpUtility.UrlEncode()` but the API I was talking to was not happy at all with the `+` used to replace the spaces since it interpreted the `+` literally.
I think a warning similar to the one found on https://learn.microsoft.com/en-us/dotnet/api/system.net.webutility.urlencode?view=net-10.0#system-net-webutility-urlencode(system-string) should be added on the following methods:
- `HttpUtility.UrlEncode()`
- `HttpUtility.UrlPathEncode()`
Also, I think that this kind of warning should be moved to the *Definition* section to be immediately visible, since it could easily be missed otherwise. I would also not be unhappy to see this note promoted to a red *Caution* banner with a stronger recommendation against I don't know if that conforms to the usual practices in Microsoft documentation though.
### Page URL
https://learn.microsoft.com/en-us/dotnet/api/system.web.httputility.urlencode?view=net-10.0
### Content source URL
https://github.com/dotnet/dotnet-api-docs-temp/blob/live/xml/System.Web/HttpUtility.xml
### Document Version Independent Id
2c52784d-6560-1db6-26b2-26af04e04ce8
### Platform Id
ac6466f5-64ce-6f49-7050-11b172476182
### Article author
@dotnet-bot
Contributor guide
Research direction
Open xml/System.Web/HttpUtility.xml from the content source URL and locate the HttpUtility.UrlEncode() and UrlPathEncode() entries. Compare their existing notes with the WebUtility.UrlEncode() documentation linked in the issue, then add the requested warning and verify that it is visible in the appropriate definition or caution section.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100