dotnet / dotnet/dotnet-api-docs

Missing warning note on HttpUtility.UrlEncode()?

Open Beginner friendly
#12,813 3 comments 0 reactions 0 assignees View on GitHub
area-System.Net untriaged
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.