Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Types and Literals

The Uri class

Reference for System.Uri in C#: parsing absolute and relative URIs, components, UriBuilder, escaping, combining paths and query strings.

Uri models a Uniform Resource Identifier, such as a web address. It parses the text once and exposes the parts: scheme, host, port, path, query and fragment. It also normalizes some details (lowercase scheme and host, default ports) and rejects text that is not a valid URI.

Use Uri instead of string manipulation whenever you read or build URLs: the pieces are separated correctly and characters are escaped properly. UriBuilder helps modify a URI, and HttpClient accepts Uri directly.

C#
var uri = new Uri("https://example.com:8443/docs/page?id=7#top");
Console.WriteLine(uri.Host);

Try it

C# Taking a URI apart

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Relative references and building

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public class Uri : ISerializable, ISpanFormattable
public Uri(string uriString)
public Uri(string uriString, UriKind uriKind)
public Uri(Uri baseUri, string relativeUri)
public static bool TryCreate(string? uriString, UriKind uriKind, out Uri? result)
Member Description
Scheme, Host, Port, Authority Parts of an absolute URI; Port returns the scheme default when none is written.
AbsolutePath, PathAndQuery, Query, Fragment Path-related parts; Query and Fragment include their ? and #.
Segments The path split into pieces, each keeping its trailing slash.
IsAbsoluteUri Whether the URI is complete.
AbsoluteUri, OriginalString, ToString() Normalized and original text.
UriKind Absolute, Relative or RelativeOrAbsolute.
Uri.EscapeDataString, UnescapeDataString Percent-encoding for a single component.
MakeRelativeUri(Uri) A relative reference from this URI to another.

Errors: the constructors throw UriFormatException for invalid text and ArgumentNullException for null. TryCreate returns false instead.

Usage notes

  • Absolute URIs need a scheme. "example.com/page" is not a valid absolute URI. Many bugs come from forgetting https://.
  • Prefer TryCreate for user input; it avoids exceptions.
  • Many members throw on relative URIs. Host, Query and others throw InvalidOperationException when IsAbsoluteUri is false.
  • Normalization. The scheme and host become lowercase; default ports (80, 443) are not shown. ToString() also decodes escapes such as %20 for display, so use AbsoluteUri when you need the escaped, transmittable text, and OriginalString for what was written.
  • Escape components, not whole URLs. Use EscapeDataString for query values and path pieces. Calling it on a whole URL escapes the : and /.
  • Query strings. Uri does not split the query into pairs. System.Web.HttpUtility.ParseQueryString and ASP.NET Core's QueryHelpers do that, and UriBuilder with EscapeDataString builds them.
  • Trailing slash matters when combining. new Uri(baseUri, "x") replaces the last segment of the base unless the base ends with /.
  • Equality ignores the fragment by default and compares the normalized form.
  • File and other schemes. file://, mailto: and urn: URIs parse too, but have different component rules.