.NET Framework Class Library
Uri Class

Provides an object representation of a uniform resource identifier (URI) and easy access to the parts of the URI.

Namespace:   System
Assembly:  System (in System.dll)
Syntax
<[%$TOPIC/txt7706a_en-us_VS_110_2_0_0_0_0%]> _
<[%$TOPIC/txt7706a_en-us_VS_110_2_0_0_0_1%](GetType([%$TOPIC/txt7706a_en-us_VS_110_2_0_0_0_2%]))> _
Public Class Uri _
	Implements [%$TOPIC/txt7706a_en-us_VS_110_2_0_0_0_3%]
[[%$TOPIC/txt7706a_en-us_VS_110_2_0_1_0_0%]]
[[%$TOPIC/txt7706a_en-us_VS_110_2_0_1_0_1%](typeof([%$TOPIC/txt7706a_en-us_VS_110_2_0_1_0_2%]))]
public class Uri : [%$TOPIC/txt7706a_en-us_VS_110_2_0_1_0_3%]
[[%$TOPIC/txt7706a_en-us_VS_110_2_0_2_0_0%]]
[[%$TOPIC/txt7706a_en-us_VS_110_2_0_2_0_1%](typeof([%$TOPIC/txt7706a_en-us_VS_110_2_0_2_0_2%]))]
public ref class Uri : [%$TOPIC/txt7706a_en-us_VS_110_2_0_2_0_3%]
[<[%$TOPIC/txt7706a_en-us_VS_110_2_0_3_0_0%]>]
[<[%$TOPIC/txt7706a_en-us_VS_110_2_0_3_0_1%](typeof([%$TOPIC/txt7706a_en-us_VS_110_2_0_3_0_2%]))>]
type Uri =  
    class 
        interface [%$TOPIC/txt7706a_en-us_VS_110_2_0_3_0_3%] 
    end

The Uri type exposes the following members.

Constructors
  NameDescription
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps Uri(String)Initializes a new instance of the Uri class with the specified URI.
Protected method Uri(SerializationInfo, StreamingContext)Initializes a new instance of the Uri class from the specified instances of the SerializationInfo and StreamingContext classes.
Public method Supported by the XNA Framework Uri(String, Boolean)Obsolete. Initializes a new instance of the Uri class with the specified URI, with explicit control of character escaping.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps Uri(String, UriKind)Initializes a new instance of the Uri class with the specified URI. This constructor allows you to specify if the URI string is a relative URI, absolute URI, or is indeterminate.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps Uri(Uri, String)Initializes a new instance of the Uri class based on the specified base URI and relative URI string.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps Uri(Uri, Uri)Initializes a new instance of the Uri class based on the combination of a specified base Uri instance and a relative Uri instance.
Public method Supported by the XNA Framework Uri(Uri, String, Boolean)Obsolete. Initializes a new instance of the Uri class based on the specified base and relative URIs, with explicit control of character escaping.
Top
Properties
  NameDescription
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps AbsolutePathGets the absolute path of the URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps AbsoluteUriGets the absolute URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps AuthorityGets the Domain Name System (DNS) host name or IP address and the port number for a server.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps DnsSafeHostGets an unescaped host name that is safe to use for DNS resolution.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps FragmentGets the escaped URI fragment.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps HostGets the host component of this instance.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps HostNameTypeGets the type of the host name specified in the URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsAbsoluteUriGets whether the Uri instance is absolute.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsDefaultPortGets whether the port value of the URI is the default for this scheme.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsFileGets a value indicating whether the specified Uri is a file URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsLoopbackGets whether the specified Uri references the local host.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsUncGets whether the specified Uri is a universal naming convention (UNC) path.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps LocalPathGets a local operating-system representation of a file name.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps OriginalStringGets the original URI string that was passed to the Uri constructor.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps PathAndQueryGets the AbsolutePath and Query properties separated by a question mark (?).
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps PortGets the port number of this URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps QueryGets any query information included in the specified URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps SchemeGets the scheme name for this URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps SegmentsGets an array containing the path segments that make up the specified URI.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps UserEscapedIndicates that the URI string was completely escaped before the Uri instance was created.
Public property Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps UserInfoGets the user name, password, or other user-specific information associated with the specified URI.
Top
Methods
  NameDescription
Protected method Supported by the XNA Framework CanonicalizeInfrastructure. Obsolete. Converts the internally stored URI to canonical form.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps CheckHostNameDetermines whether the specified host name is a valid DNS name.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps CheckSchemeNameDetermines whether the specified scheme name is valid.
Protected method Supported by the XNA Framework CheckSecurityInfrastructure. Obsolete. Calling this method has no effect.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps CompareCompares the specified parts of two URIs using the specified comparison rules.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps EqualsCompares two Uri instances for equality. (Overrides ObjectEquals(Object).)
Protected method Supported by the XNA Framework EscapeInfrastructure. Obsolete. Converts any unsafe or reserved characters in the path component to their hexadecimal character representations.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps EscapeDataStringConverts a string to its escaped representation.
Protected method Static member Supported by the XNA Framework EscapeStringObsolete. Converts a string to its escaped representation.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps EscapeUriStringConverts a URI string to its escaped representation.
Protected method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps FinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public method Static member Supported by the XNA Framework FromHexGets the decimal value of a hexadecimal digit.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps GetComponentsGets the specified components of the current instance using the specified escaping for special characters.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps GetHashCodeGets the hash code for the URI. (Overrides ObjectGetHashCode.)
Public method Supported by the XNA Framework GetLeftPartGets the specified portion of a Uri instance.
Protected method GetObjectDataReturns the data needed to serialize the current instance.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps GetTypeGets the Type of the current instance. (Inherited from Object.)
Public method Static member Supported by the XNA Framework HexEscapeConverts a specified character into its hexadecimal equivalent.
Public method Static member Supported by the XNA Framework HexUnescapeConverts a specified hexadecimal representation of a character to the character.
Protected method Supported by the XNA Framework IsBadFileSystemCharacterInfrastructure. Obsolete. Gets whether a character is invalid in a file system name.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsBaseOfDetermines whether the current Uri instance is a base of the specified Uri instance.
Protected method Static member Supported by the XNA Framework IsExcludedCharacterInfrastructure. Obsolete. Gets whether the specified character should be escaped.
Public method Static member Supported by the XNA Framework IsHexDigitDetermines whether a specified character is a valid hexadecimal digit.
Public method Static member Supported by the XNA Framework IsHexEncodingDetermines whether a character in a string is hexadecimal encoded.
Protected method Supported by the XNA Framework IsReservedCharacterInfrastructure. Obsolete. Gets whether the specified character is a reserved character.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsWellFormedOriginalStringIndicates whether the string used to construct this Uri was well-formed and is not required to be further escaped.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps IsWellFormedUriStringIndicates whether the string is well-formed by attempting to construct a URI with the string and ensures that the string does not require further escaping.
Public method Supported by the XNA Framework MakeRelativeObsolete. Determines the difference between two Uri instances.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps MakeRelativeUriDetermines the difference between two Uri instances.
Protected method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps MemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected method Supported by the XNA Framework ParseInfrastructure. Obsolete. Parses the URI of the current instance to ensure it contains all the parts required for a valid URI.
Public method Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps ToStringGets a canonical string representation for the specified Uri instance. (Overrides ObjectToString.)
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps TryCreate(String, UriKind, Uri)Creates a new Uri using the specified String instance and a UriKind.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps TryCreate(Uri, String, Uri)Creates a new Uri using the specified base and relative String instances.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps TryCreate(Uri, Uri, Uri)Creates a new Uri using the specified base and relative Uri instances.
Protected method Supported by the XNA Framework UnescapeInfrastructure. Obsolete. Converts the specified string by replacing any escape sequences with their unescaped representation.
Public method Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps UnescapeDataStringConverts a string to its unescaped representation.
Top
Operators
  NameDescription
Public operator Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps EqualityDetermines whether two Uri instances have the same value.
Public operator Static member Supported by the XNA Framework Supported by Portable Class Library Supported in .NET for Windows Store apps InequalityDetermines whether two Uri instances do not have the same value.
Top
Fields
  NameDescription
Public field Static member Supported by the XNA Framework SchemeDelimiterSpecifies the characters that separate the communication protocol scheme from the address portion of the URI. This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeFileSpecifies that the URI is a pointer to a file. This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeFtpSpecifies that the URI is accessed through the File Transfer Protocol (FTP). This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeGopherSpecifies that the URI is accessed through the Gopher protocol. This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeHttpSpecifies that the URI is accessed through the Hypertext Transfer Protocol (HTTP). This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeHttpsSpecifies that the URI is accessed through the Secure Hypertext Transfer Protocol (HTTPS). This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeMailtoSpecifies that the URI is an e-mail address and is accessed through the Simple Mail Transport Protocol (SMTP). This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeNetPipeSpecifies that the URI is accessed through the NetPipe scheme used by Windows Communication Foundation (WCF). This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeNetTcpSpecifies that the URI is accessed through the NetTcp scheme used by Windows Communication Foundation (WCF). This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeNewsSpecifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.
Public field Static member Supported by the XNA Framework UriSchemeNntpSpecifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.
Top
Explicit Interface Implementations
  NameDescription
Explicit interface implemetation Private method ISerializableGetObjectDataReturns the data needed to serialize the current instance.
Top
Remarks

A URI is a compact representation of a resource available to your application on the intranet or Internet. The Uri class defines the properties and methods for handling URIs, including parsing, comparing, and combining. The Uri class properties are read-only; to create a modifiable object, use the UriBuilder class.

Relative URIs (for example, "/new/index.htm") must be expanded with respect to a base URI so that they are absolute. The MakeRelative method is provided to convert absolute URIs to relative URIs when necessary.

The Uri constructors do not escape URI strings if the string is a well-formed URI including a scheme identifier.

The Uri properties return a canonical data representation in escaped encoding, with all characters with Unicode values greater than 127 replaced with their hexadecimal equivalents. To put the URI in canonical form, the Uri constructor performs the following steps:

  • Converts the URI scheme to lowercase.

  • Converts the host name to lowercase.

  • If the host name is an IPv6 address, the canonical IPv6 address is used. ScopeId and other optional IPv6 data are removed.

  • Removes default and empty port numbers.

  • Canonicalizes the path for hierarchical URIs by compacting sequences such as /./, /../, //, including escaped representations. Note that there are some schemes for which escaped representations are not compacted.

  • For hierarchical URIs, if the host is not terminated with a forward slash (/), one is added.

  • By default, any reserved characters in the URI are escaped in accordance with RFC 2396. This behavior changes if International Resource Identifiers or International Domain Name parsing is enabled in which case reserved characters in the URI are escaped in accordance with RFC 3986 and RFC 3987.

As part of canonicalization in the constructor for some schemes, escaped representations are compacted. The schemes for which URI will compact escaped sequences include the following: file, http, https, net.pipe, and net.tcp. For all other schemes, escaped sequences are not compacted. For example: if you percent encode the two dots ".." as "%2E%2E" then the URI constructor will compact this sequence for some schemes. For example, the following code sample shows a URI constructor for the http scheme.

    Uri uri = new Uri("http://myUrl/%2E%2E/%2E%2E");
    Console.WriteLine(uri.AbsoluteUri);
    Console.WriteLine(uri.PathAndQuery);

When this code is executed, it returns the following output with the escaped sequence compacted.

http://myUrl/
/

The following code example shows a URI constructor for the ftp scheme:

    Uri uri = new Uri("ftp://myUrl/%2E%2E/%2E%2E");
    Console.WriteLine(uri.AbsoluteUri);
    Console.WriteLine(uri.PathAndQuery);

When this code is executed, it returns the following output with the escaped sequence not compacted.

ftp://myUrl/%2E%2E/%2E%2E
/%2E%2E/%2E%2E

You can transform the contents of the Uri class from an escape encoded URI reference to a readable URI reference by using the ToString method. Note that some reserved characters might still be escaped in the output of the ToString method. This is to support unambiguous reconstruction of a URI from the value returned by ToString.

Some URIs include a fragment identifier or a query or both. A fragment identifier is any text that follows a number sign (#), not including the number sign; the fragment text is stored in the Fragment property. Query information is any text that follows a question mark (?) in the URI; the query text is stored in the Query property.

In the .NET Framework version 1.1, if the string specified to a constructor contains an unknown scheme and "c:\", the Uri class inserts "//" after the colon. For example, the URI xyz:c:\abc is converted to xyz://c:/abc. In the .NET Framework version 2.0, this behavior has been removed, and the example string is converted to xyz:c:/abc.

NoteNote

The URI class supports the use of IP addresses in both quad-notation for IPv4 protocol and colon-hexadecimal for IPv6 protocol. Remember to enclose the IPv6 address in square brackets, as in http://[::1].

International Resource Identifier Support

Web addresses are typically expressed using uniform resource identifiers that consist of a very restricted set of characters:

  • Upper and lower case ASCII letters from the English alphabet.

  • Digits from 0 to 9.

  • A small number of other ASCII symbols.

The specifications for URIs are documented in RFC 2396, RFC 2732, RFC 3986, and RFC 3987 published by the Internet Engineering Task Force (IETF).

With the growth of the Internet, there is a growing need to identify resources using languages other than English. Identifiers which facilitate this need and allow non-ASCII characters (characters in the Unicode/ISO 10646 character set) are known as International Resource Identifiers (IRIs). The specifications for IRIs are documented in RFC 3987 published by IETF. Using IRIs allows a URL to contain Unicode characters.

The existing Uri class has been extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide IRI support based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework.

To enable support for IRI, the following change is required:

  • Specify whether you want Internationalized Domain Name (IDN) parsing applied to the domain name and whether IRI parsing rules should be applied. This can be done in the machine.config or in the app.config file. For example, add the following:

    <configuration>
      <uri>
      <idn enabled="All" />
      <iriParsing enabled="true" />
      </uri>
    </configuration>

Enabling IDN will convert all Unicode labels in a domain name to their Punycode equivalents. Punycode names contain only ASCII characters and always start with the xn-- prefix. The reason for this is to support existing DNS servers on the Internet, since most DNS servers only support ASCII characters (see RFC 3940).

Enabling IRI and IDN affects the value of the UriDnsSafeHost property. Enabling IRI and IDN can also change the behavior of the Equals, OriginalString, GetComponents, and IsWellFormedOriginalString methods.

There are three possible values for IDN depending on the DNS servers that are used:

  • idn enabled = All

    This value will convert any Unicode domain names to their Punycode equivalents (IDN names).

  • idn enabled = AllExceptIntranet

    This value will convert all Unicode domain names not on the local Intranet to use the Punycode equivalents (IDN names). In this case to handle international names on the local Intranet, the DNS servers that are used for the Intranet should support Unicode name resolution.

  • idn enabled = None

    This value will not convert any Unicode domain names to use Punycode. This is the default value which is consistent with the .NET Framework 2.0 behaviour.

Enabling IRI parsing (iriParsing enabled = true) will do normalization and character checking according to the latest IRI rules in RFC 3986 and RFC 3987. The default value is false and will do normalization and character checking according to RFC 2396 and RFC 2732 (for IPv6 literals).

IRI and IDN processing in the Uri class can also be controlled using the System.ConfigurationIriParsingElement, System.ConfigurationIdnElement, and System.ConfigurationUriSection configuration setting classes. The System.ConfigurationIriParsingElement setting enables or disables IRI processing in the Uri class. The System.ConfigurationIdnElement setting enables or disables IDN processing in the Uri class. The System.ConfigurationIriParsingElement setting also indirectly controls IDN. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used.

The configuration setting for the System.ConfigurationIriParsingElement and System.ConfigurationIdnElement will be read once when the first SystemUri class is constructed. Changes to configuration settings after that time are ignored.

The SystemGenericUriParser class has also been extended to allow creating a customizable parser that supports IRI and IDN. The behavior of a SystemGenericUriParser object is specified by passing a bitwise combination of the values available in the SystemGenericUriParserOptions enumeration to the SystemGenericUriParser constructor. The GenericUriParserOptionsIriParsing type indicates the parser supports the parsing rules specified in RFC 3987 for International Resource Identifiers (IRI). Whether IRI is used is dictated by the configuration values previously discussed.

The GenericUriParserOptionsIdn type indicates the parser supports Internationalized Domain Name (IDN) parsing (IDN) of host names. Whether IDN is used is dictated by the configuration values previously discussed.

Performance Considerations

If you use a Web.config file that contains URIs to initialize your application, additional time is required to process the URIs if their scheme identifiers are nonstandard. In such a case, initialize the affected parts of your application when the URIs are needed, not at start time.

Notes to Callers

Because of security concerns, your application should use caution when accepting Uri instances from untrusted sources and with dontEscape set to true.You can check a URI string for validity by calling the IsWellFormedOriginalString method.

Examples

The following example creates an instance of the Uri class and uses it to create a WebRequest instance.

Dim siteUri As New Uri("http://www.contoso.com/")

Dim wr As WebRequest = WebRequest.Create(siteUri)
Uri siteUri = new Uri("http://www.contoso.com/");

WebRequest wr = WebRequest.Create(siteUri);
Uri^ siteUri = gcnew Uri( "http://www.contoso.com/" );
WebRequest^ wr = WebRequest::Create( siteUri );
Version Information

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone 8, Silverlight 8.1
Platforms

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.