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.
var uri = new Uri("https://example.com:8443/docs/page?id=7#top"); Console.WriteLine(uri.Host);
Try it
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.
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
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 forgettinghttps://. - Prefer
TryCreatefor user input; it avoids exceptions. - Many members throw on relative URIs.
Host,Queryand others throwInvalidOperationExceptionwhenIsAbsoluteUriisfalse. - Normalization. The scheme and host become lowercase; default ports (80, 443) are not shown.
ToString()also decodes escapes such as%20for display, so useAbsoluteUriwhen you need the escaped, transmittable text, andOriginalStringfor what was written. - Escape components, not whole URLs. Use
EscapeDataStringfor query values and path pieces. Calling it on a whole URL escapes the:and/. - Query strings.
Uridoes not split the query into pairs.System.Web.HttpUtility.ParseQueryStringand ASP.NET Core'sQueryHelpersdo that, andUriBuilderwithEscapeDataStringbuilds 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:andurn:URIs parse too, but have different component rules.
Related
- Guid
- Version
- String.Split()
- Tutorial: HttpClient, Files and paths