Partager via


Uri Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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

Inheritance Hierarchy

System.Object
  System.Uri

Namespace:  System
Assembly:  System (in System.dll)

Syntax

'Declaration
<TypeConverterAttribute(GetType(UriTypeConverter))> _
Public Class Uri
[TypeConverterAttribute(typeof(UriTypeConverter))]
public class Uri

The Uri type exposes the following members.

Constructors

  Name Description
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Uri(String) Initializes a new instance of the Uri class with the specified URI.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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 methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Uri(Uri, String) Initializes a new instance of the Uri class based on the specified base URI and relative URI string.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.

Top

Properties

  Name Description
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 AbsolutePath Gets the absolute path of the URI.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 AbsoluteUri Gets the absolute URI.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 DnsSafeHost Gets an unescaped host name that is safe to use for DNS resolution.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 Fragment Gets the escaped URI fragment.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 Host Gets the host component of this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 IsAbsoluteUri Gets whether the Uri instance is absolute.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 IsUnc Gets whether the specified Uri is a universal naming convention (UNC) path.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 LocalPath Gets a local operating-system representation of a file name.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 OriginalString Gets the original URI string that was passed to the Uri constructor.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 Port Gets the port number of this URI.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 Query Gets any query information included in the specified URI.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 Scheme Gets the scheme name for this URI.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 UserEscaped Indicates that the URI string was completely escaped before the Uri instance was created.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360 UserInfo Gets the user name, password, or other user-specific information associated with the specified URI.

Top

Methods

  Name Description
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 CheckSchemeName Determines whether the specified scheme name is valid.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Compare Compares the specified parts of two URIs using the specified comparison rules.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Equals Compares two Uri instances for equality. (Overrides Object.Equals(Object).)
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 EscapeDataString Converts a string to its escaped representation.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 EscapeUriString Converts a URI string to its escaped representation.
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Finalize Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 FromHex Gets the decimal value of a hexadecimal digit.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetComponents Gets the specified components of the current instance using the specified escaping for special characters.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetHashCode Gets the hash code for the URI. (Overrides Object.GetHashCode().)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetType Gets the Type of the current instance. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 IsBaseOf Determines whether the current Uri instance is a base of the specified Uri instance.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 IsHexDigit Determines whether a specified character is a valid hexadecimal digit.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 IsWellFormedUriString Indicates 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 methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MakeRelativeUri Determines the difference between two Uri instances.
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ToString Gets a canonical string representation for the specified Uri instance. (Overrides Object.ToString().)
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 TryCreate(String, UriKind, Uri%) Creates a new Uri using the specified String instance and a UriKind.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 TryCreate(Uri, String, Uri%) Creates a new Uri using the specified base and relative String instances.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 TryCreate(Uri, Uri, Uri%) Creates a new Uri using the specified base and relative Uri instances.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UnescapeDataString Converts a string to its unescaped representation.

Top

Operators

  Name Description
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Equality Determines whether two Uri instances have the same value.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Inequality Determines whether two Uri instances do not have the same value.

Top

Fields

  Name Description
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 SchemeDelimiter Specifies the characters that separate the communication protocol scheme from the address portion of the URI. This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeFile Specifies that the URI is a pointer to a file. This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeFtp Specifies that the URI is accessed through the File Transfer Protocol (FTP). This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeGopher Specifies that the URI is accessed through the Gopher protocol. This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeHttp Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTP). This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeHttps Specifies that the URI is accessed through the Secure Hypertext Transfer Protocol (HTTPS). This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeMailto Specifies that the URI is an e-mail address and is accessed through the Simple Mail Transport Protocol (SMTP). This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeNetPipe Specifies that the URI is accessed through the NetPipe scheme of the "Indigo" system. This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeNetTcp Specifies that the URI is accessed through the NetTcp scheme of the "Indigo" system. This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeNews Specifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 UriSchemeNntp Specifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.

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 MakeRelativeUri 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.

  • Any reserved characters in the URI are escaped in accordance with RFC 3986.

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.Query);

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.Query);

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.

NoteNote:

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

The constructors for Uri allow a Silverlight application to create a Uri instance for many schemes as described in the Scheme property. However, only Uri instances for the UriSchemeHttp or UriSchemeHttps schemes are supported by the WebClient and HTTP classes in the System.Net namespace.

International Resource Identifier Not Supported

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 and RFC 3986 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 in Silverlight does not currently provide support for IRI or Internationalized Domain Name (IDN) parsing applied to the domain name.

Silverlight applications cannot derive new classes from the Uri class.

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 non-standard. 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.

Examples

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

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

Dim wr As WebRequest = WebRequest.Create(siteUri)

      Uri siteUri = new Uri("https://www.contoso.com/");

      WebRequest wr = WebRequest.Create(siteUri);

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

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.