URL Encoder / Decoder

URL encoding in ASP.NET Core: the methods I actually use

The first time I needed to build a redirect URL dynamically in ASP.NET Core, I used string concatenation and got a 400 error from the OAuth provider because the callback URI wasn't encoded. The fix was one method call, but knowing which one matters — .NET has three different URL encoding methods that behave differently, and using the wrong one is a reliable source of hard-to-reproduce bugs in production.

Three URL encoding methods in .NET — and when to use each

The .NET BCL provides URL encoding through multiple types, each with different semantics:

• Uri.EscapeDataString(value) — encodes a value for use as a query parameter value or path segment. This is what you want in almost every case when building URLs. It follows RFC 3986: encodes everything except unreserved characters (A–Z, a–z, 0–9, - _ . ~). This is the correct choice for encoding values you're embedding into a URL.
• Uri.EscapeUriString(uri) — encodes a full URI, preserving structural characters like /, ?, #, and =. Use this only when you have a complete URI with structure already in place and want to encode non-ASCII characters in it. Do not use this to encode individual values — it will leave & and = unencoded.
• WebUtility.UrlEncode(value) — uses HTML form encoding (application/x-www-form-urlencoded): encodes spaces as + instead of %20. Use this when generating form POST body strings. Do not use it for query strings in URLs intended for OAuth or REST APIs that expect RFC 3986 percent-encoding.

// Building a URL with a query parameter — the right way
string searchTerm = "C# async/await";
string encodedTerm = Uri.EscapeDataString(searchTerm); // "C%23%20async%2Fawait"
string url = $"https://api.example.com/search?q={encodedTerm}";

// Building an OAuth redirect_uri parameter — the redirect URL must itself be encoded
string callbackUrl = "https://myapp.example.com/callback?source=oauth";
string redirectUri = Uri.EscapeDataString(callbackUrl);
string oauthUrl = $"https://idp.example.com/authorize?redirect_uri={redirectUri}&client_id=abc";

// Decoding a percent-encoded string from a request header or log
string encoded = "hello%20world%2Ftest%3Fq%3D1";
string decoded = Uri.UnescapeDataString(encoded); // "hello world/test?q=1"

// Reading a query parameter value in ASP.NET Core minimal API
// — framework already handles decoding, no manual decode needed
app.MapGet("/search", (string q) => Results.Ok(q)); // q arrives already decoded

Which characters must be encoded (RFC 3986)

%20 vs + for spaces

Standard percent-encoding (RFC 3986) uses %20 for spaces and is correct in all parts of a URL. The + convention for spaces comes from HTML form encoding (application/x-www-form-urlencoded) and is only valid in form POST bodies and certain legacy query string parsers. OAuth providers, REST APIs, and ASP.NET Core's query string parsing all handle both, but %20 is safer for values you embed in URLs you're building.

How to URL encode or decode a string online

1. Paste your string into the input — either a raw value to encode or a percent-encoded string to decode.
2. Click Encode to percent-encode special characters, or Decode to reverse it.
3. Copy the result from the output panel.

Five real .NET use cases

1. Encoding an OAuth redirect_uri parameter. The callback URL contains :, /, and ? — all of which are reserved characters. Use Uri.EscapeDataString(callbackUrl) to encode the entire URL before appending it as a query parameter value to the authorization endpoint URL.
2. Building a search API URL with user-provided input in ASP.NET Core. User input can contain &, #, and spaces — all of which would break the query string structure. Always encode user-provided values with Uri.EscapeDataString before interpolating them into URLs.
3. Decoding a percent-encoded value from a server log or error report. Production logs often show raw percent-encoded URLs. Paste the encoded value here to read the original string without writing a one-off script.
4. Encoding a file path segment that contains spaces or special characters for an Azure Blob Storage URL. Azure Blob Storage URLs require percent-encoded container and blob names. Use Uri.EscapeDataString on each path segment individually, not on the full URL.
5. Building a QueryString for an HttpClient request manually. QueryString.Create(IEnumerable<KeyValuePair<string, string?>>) in ASP.NET Core handles encoding automatically. If building by hand, use Uri.EscapeDataString on both keys and values.

Frequently asked questions

Should I encode the whole URL or just the parameters? Encode only the values of query parameters and path segments that contain user data. The structural parts of the URL (scheme, host, path separators, ?, &, = between key and value) must remain unencoded. Encoding the full URL turns https://example.com/search?q=test into an unresolvable string.

What is the difference between Uri.EscapeDataString and WebUtility.UrlEncode in .NET? Uri.EscapeDataString encodes spaces as %20 and follows RFC 3986. WebUtility.UrlEncode encodes spaces as + and follows HTML form encoding. For query parameters in REST API calls and OAuth flows, use Uri.EscapeDataString. For generating HTML form data, WebUtility.UrlEncode is correct.

Does ASP.NET Core automatically decode URL-encoded query parameters? Yes. When your controller or minimal API endpoint receives a string parameter from the query string, ASP.NET Core's model binding has already decoded it. You only need to decode manually if you're reading raw query strings from HttpContext.Request.QueryString.Value.