Uri Uri Uri Uri Class

Definition

Defines an object that represents a Uniform Resource Identifier (URI) value and parses it into components. The Uri object is used by many other Windows Runtime APIs that are not necessarily confined to web browser scenarios.

.NET When programming with .NET, this type is hidden and developers should use System.Uri. See Remarks.

public sealed class Uripublic sealed class UriPublic NotInheritable Class Uripublic sealed class Uri
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Important

When programming with .NET, this class is hidden and developers should use the System.Uri class, which uses RFC 3987 rules to encode and decode Uniform Resource Identifier (URI). The Uri class doesn't percent-encode non-ASCII characters in Uniform Resource Identifier (URI) where the scheme refers to a Windows file path (like ms-appx:). Uri also interprets percent-encoding using the user's current codepage.

The available members of System.Uri are similar but different than the members of Uri, and some of the basic behaviors described in this topic are different. For more info on the encoding differences and what members are available, see System.Uri (particularly the Remarks).

Here is a breakdown of the parts of an example Uniform Resource Identifier (URI):

scheme://username:password @host:port/path.extension ?query #fragment

For example:

http://msdn.microsoft.com/en-us/library/windows/apps/windows.foundation.uri.aspx?cs-save-lang=1&cs-lang=cpp#code-snippet-1

In this example:

  • scheme is http
  • host is msdn.microsoft.com
  • domain is microsoft.com (a subset of host)
  • extension is aspx
  • query is cs-save-lang=1&cs-lang=cpp
  • fragment is code-snippet-1
Note

username:password@ preceding the host are mainly relevant for File Transfer Protocol (FTP) Uniform Resource Identifier (URI). File Transfer Protocol (FTP) URIs have limited support in Windows Runtime; see "Transferring data in the background" (HTML or XAML).

Important

Not all possible schemes are usable by a Windows Runtime app. Notably, the file: scheme is blocked. It's possible to create a Uri object that uses schemes that a Windows Runtime app won't support, and you're blocked when you try to apply that Uri as an input value for an API call, not when creating the object.

URI schemes that are specific to a Windows Runtime app

Windows Runtime has several schemes that are unique to a Windows Runtime app, and these refer to assets that are part of the app. Generally, these schemes are what you can use instead of the file: scheme, to refer to packaged files and other assets that you've included as part of your app package, or assets that are otherwise associated with an installed app:+ ms-appx: references the app’s locally-packaged files.

  • ms-appx-web: also references the app’s locally-packaged files but loads them in a web context. This is often necessary if you are accessing assets for use by WebView, or writing HTML/JavaScript apps and requesting from an HTML page. For more info see URI schemes or How to reference content (HTML).
  • ms-appdata: refers to app files that come from the app's local, roaming, and temporary data folders. For more info see URI schemes or Store and retrieve settings and other app data.
  • ms-resource: refers to app resources in the Resource Management System. For more info, see "How to load string resources" (HTML or XAML). Each of these schemes ignores many of the component parts of a Uniform Resource Identifier (URI) that are intended for other schemes (for example, Query and Fragment ). Also, certain components are explicitly disallowed and cause the Uri value using these schemes to be treated as an invalid input (for example UserName and Password values in an ms-appx: Uri scheme will invalidate a Uri ). For more info, see URI schemes.

In most cases, you use these schemes with three slashes (example: ms-appx:///page.html), which references the root of the current app, using the current app as authority. Usages with two slashes are possible, but might require specifying the authority name explicitly. Usages with two slashes can refer to a package dependency as the authority, or can refer to relative locations within the app. For more info, see URI schemes.

Absolute and relative URIs

At a code level, the Windows Runtime does not support relative Uniform Resource Identifier (URI). All Uri objects you create must represent an absolute Uniform Resource Identifier (URI). The schemes listed in the previous section are actually absolute Uniform Resource Identifier (URI), because the host and authority are implicit for each scheme and the remainder of the path is evaluated under that authority.

Launching an app by URI scheme

The Uniform Resource Identifier (URI) scheme of a Uri value can be used to launch other apps that are associated with that particular scheme. For more info, see "How to launch the default app for a URI" (HTML or XAML).

Examples

This example creates a Uri object that represents a Uniform Resource Identifier (URI) that's using the http protocol to access a website.

// The URI string
var uriToLaunch = "http://www.bing.com";

// Create a Uri object from the URI string
var uri = new Windows.Foundation.Uri(uriToLaunch);
// The URI string
var uriToLaunch = L"http://www.bing.com";

// Create a Uri object from the URI string
auto uri = ref new Windows::Foundation::Uri(uriToLaunch);

This example creates a Uri that uses the ms-appx protocol to access an image file in the app package.

// The URI string
var uriImage = "ms-appx:///images/SecondaryTileDefault-sdk.png";

// Create a Uri object from the URI string
var uri = new Windows.Foundation.Uri(uriImage);
// The URI string
var uriImage = "ms-appx:///images/SecondaryTileDefault-sdk.png";

// Create a Uri object from the URI string
auto uri = ref new Windows::Foundation::Uri(uriImage);

This example creates a Uri that uses the ms-appdata protocol to access a file in local app data store for your app.

// The URI string
var uriFile = "ms-appdata:///local/file.ext";

// Create a Uri object from the URI string
var uri = new Windows.Foundation.Uri(uriFile);
// The URI string
var uriFile = "ms-appdata:///local/file.ext";

// Create a Uri object from the URI string
auto uri = ref new Windows::Foundation::Uri(uriFile);

Constructors

Uri(String) Uri(String) Uri(String) Uri(String)

Initializes a new Uri object from the specified Uniform Resource Identifier (URI) string. Initializing the Uri also parses the string and populates the Uri properties that represent Uniform Resource Identifier (URI) components.

public Uri(String uri)public New(String uri)Public Sub New(uri As String)public Uri(String uri)
Parameters
uri
System.String System.String System.String System.String

The string from which the new Uri object is created.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Uri(String, String) Uri(String, String) Uri(String, String) Uri(String, String)

Initializes a new Uri by combining a base Uniform Resource Identifier (URI) and a relative Uniform Resource Identifier (URI). Initializing the Uri also parses the combined string and populates the Uri properties that represent Uniform Resource Identifier (URI) components.

public Uri(String baseUri, String relativeUri)public New(String baseUri, String relativeUri)Public Sub New(baseUri As String, relativeUri As String)public Uri(String baseUri, String relativeUri)
Parameters
baseUri
System.String System.String System.String System.String

The base Uniform Resource Identifier (URI).

relativeUri
System.String System.String System.String System.String

The relative Uniform Resource Identifier (URI).

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Properties

AbsoluteCanonicalUri AbsoluteCanonicalUri AbsoluteCanonicalUri AbsoluteCanonicalUri

Gets a fully canonical RFC-compliant representation of the current URI.

public string AbsoluteCanonicalUri { get; }public string AbsoluteCanonicalUri { get; }Public ReadOnly Property AbsoluteCanonicalUri As stringpublic string AbsoluteCanonicalUri { get; }
Value
string string string string

The canonical URI.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The canonical URI has all non-US ASCII characters represented as percent-encoded UTF-8 and as Punycode in the hostname.

Use the DisplayIri property instead if you want to decode this string so that it can be presented.

AbsoluteUri AbsoluteUri AbsoluteUri AbsoluteUri

Gets the entire, non-canonical URI (It is non-canonical because it might actually be an IRI, per the Uri encoding behavior; see Remarks.).

public string AbsoluteUri { get; }public string AbsoluteUri { get; }Public ReadOnly Property AbsoluteUri As stringpublic string AbsoluteUri { get; }
Value
string string string string

The entire, non-canonical URI.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This property is not always strictly a URI, per either RFC 3986 or RFC 3987. If you want a strict Uniform Resource Identifier (URI), use the AbsoluteCanonicalUri value instead.

DisplayIri DisplayIri DisplayIri DisplayIri

Gets the decoded unicode characters that make up the current URI.

public string DisplayIri { get; }public string DisplayIri { get; }Public ReadOnly Property DisplayIri As stringpublic string DisplayIri { get; }
Value
string string string string

The decoded unicode characters, when possible. Unsafe values are renamed as percent-encoded UTF-8. Characters in the hostname are decoded if they were encoded usingPunycode.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The DisplayIri property is an attempted decode of the string as seen in the AbsoluteCanonicalUri property. You might use this string for display to the user, where showing the encodings would be distracting and would make link text that parallels the Uniform Resource Identifier (URI) difficult to read as text. Unsafe values (values that can't be decoded under the user's codepage) are kept as percent-encoded UTF-8.

DisplayUri DisplayUri DisplayUri DisplayUri

Gets a representation of the Uniform Resource Identifier (URI) that can be used for display purposes.

public string DisplayUri { get; }public string DisplayUri { get; }Public ReadOnly Property DisplayUri As stringpublic string DisplayUri { get; }
Value
string string string string

The Uniform Resource Identifier (URI) for display.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Domain Domain Domain Domain

Gets the domain name component, including top-level domain, from a Uniform Resource Identifier (URI).

public string Domain { get; }public string Domain { get; }Public ReadOnly Property Domain As stringpublic string Domain { get; }
Value
string string string string

The domain name.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

If the domain name is subject to Punycode encoding as shown in AbsoluteCanonicalUri, the Domain property shows the decoded value, not the Punycode encoded value.

Extension Extension Extension Extension

Gets the file name extension of the resource that is referenced in the Uri.

public string Extension { get; }public string Extension { get; }Public ReadOnly Property Extension As stringpublic string Extension { get; }
Value
string string string string

The file name extension. The dot (.) is not part of the extension.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Fragment Fragment Fragment Fragment

Gets the text following a fragment marker (#), including the fragment marker itself.

public string Fragment { get; }public string Fragment { get; }Public ReadOnly Property Fragment As stringpublic string Fragment { get; }
Value
string string string string

The text that represents the fragment.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Host Host Host Host

Gets the fully qualified domain name.

public string Host { get; }public string Host { get; }Public ReadOnly Property Host As stringpublic string Host { get; }
Value
string string string string

The fully qualified domain name.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

If the domain name is subject to Punycode encoding as shown in AbsoluteCanonicalUri, the Host property shows the decoded value, not the Punycode encoded value.

Password Password Password Password

Gets the password component of the Uniform Resource Identifier (URI) as stored in this Uri instance.

public string Password { get; }public string Password { get; }Public ReadOnly Property Password As stringpublic string Password { get; }
Value
string string string string

The password.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Note

username:password@ preceding the host part of a URI are mainly relevant for File Transfer Protocol (FTP) URIs. File Transfer Protocol (FTP) URIs have limited support in Windows Runtime; see "Transferring data in the background" (HTML or XAML).

Path Path Path Path

Gets the path and resource name component of the Uniform Resource Identifier (URI) as stored in this Uri instance.

public string Path { get; }public string Path { get; }Public ReadOnly Property Path As stringpublic string Path { get; }
Value
string string string string

The path, including the resource name, and including the extension. Does not include query or fragment.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Port Port Port Port

Gets the port number component of the Uniform Resource Identifier (URI) as stored in this Uri instance

public int Port { get; }public int Port { get; }Public ReadOnly Property Port As intpublic int Port { get; }
Value
int int int int

The port number.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This property reports the implicit defaults for schemes, such as 80 for http:.

Query Query Query Query

Gets the query string component of the Uniform Resource Identifier (URI) as stored in this Uri instance.

public string Query { get; }public string Query { get; }Public ReadOnly Property Query As stringpublic string Query { get; }
Value
string string string string

The query string.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Query reports the query portion of the Uniform Resource Identifier (URI), and the subdelimiters (& characters) and key-value separators (=) are all reported as-is in that string. QueryParsed parses this string and creates a map of key-value pairs. This map is returned as a WwwFormUrlDecoder object.

QueryParsed QueryParsed QueryParsed QueryParsed

Gets a parsed Uniform Resource Identifier (URI) query string.

public WwwFormUrlDecoder QueryParsed { get; }public WwwFormUrlDecoder QueryParsed { get; }Public ReadOnly Property QueryParsed As WwwFormUrlDecoderpublic WwwFormUrlDecoder QueryParsed { get; }
Value
WwwFormUrlDecoder WwwFormUrlDecoder WwwFormUrlDecoder WwwFormUrlDecoder

The parsed query, as a new WwwFormUrlDecoder object. This is a read-only list of all name-value pairs (the form entries) as found in the query string after parsing.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Query reports the query portion of the Uniform Resource Identifier (URI), and the subdelimiters (& characters) and key-value separators (=) are all reported as-is in that string. QueryParsed parses this string and creates a read-only list (vector) of name-value pairs. This is returned as a WwwFormUrlDecoder object.

RawUri RawUri RawUri RawUri

Gets the entire original Uniform Resource Identifier (URI) string as used to construct this Uri object, before parsing, and without any encoding applied.

public string RawUri { get; }public string RawUri { get; }Public ReadOnly Property RawUri As stringpublic string RawUri { get; }
Value
string string string string

The raw Uniform Resource Identifier (URI) string.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

SchemeName SchemeName SchemeName SchemeName

Gets the protocol scheme name component of the Uniform Resource Identifier (URI) as stored in this Uri instance

public string SchemeName { get; }public string SchemeName { get; }Public ReadOnly Property SchemeName As stringpublic string SchemeName { get; }
Value
string string string string

The protocol scheme name.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Suspicious Suspicious Suspicious Suspicious

Gets a value that indicates whether parsing determined that the Uniform Resource Identifier (URI) is not well-formed.

public bool Suspicious { get; }public bool Suspicious { get; }Public ReadOnly Property Suspicious As boolpublic bool Suspicious { get; }
Value
bool bool bool bool

true if the Uniform Resource Identifier (URI) is flagged as suspicious; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

UserName UserName UserName UserName

Gets the user name component of the Uniform Resource Identifier (URI) as stored in this Uri instance.

public string UserName { get; }public string UserName { get; }Public ReadOnly Property UserName As stringpublic string UserName { get; }
Value
string string string string

The user name.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Note

username:password@ preceding the host part of a URI are mainly relevant for File Transfer Protocol (FTP) Uniform Resource Identifier (URI). File Transfer Protocol (FTP) Uniform Resource Identifier (URI) have limited support in Windows Runtime; see "Transferring data in the background" (HTML or XAML).

Methods

CombineUri(String) CombineUri(String) CombineUri(String) CombineUri(String)

Adds the specified Uniform Resource Identifier (URI) to the current Uri.

public Uri CombineUri(String relativeUri)public Uri CombineUri(String relativeUri)Public Function CombineUri(relativeUri As String) As Uripublic Uri CombineUri(String relativeUri)
Parameters
relativeUri
System.String System.String System.String System.String

A relative Uniform Resource Identifier (URI) specified as a string. This relative path is evaluated using the host/authority of the Uri instance where this method is called.

Returns

The combined Uri value.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Equals(Uri) Equals(Uri) Equals(Uri) Equals(Uri)

Determines whether the specified Uri object is equal to the current Uri object.

public bool Equals(Uri pUri)public bool Equals(Uri pUri)Public Function Equals(pUri As Uri) As boolpublic bool Equals(Uri pUri)
Parameters
pUri
Uri Uri Uri Uri

The Uri object to be compared.

Returns
bool bool bool bool

true if the two Uri values are the same; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Equality comparison is based on the logical content (the property values).

EscapeComponent(String) EscapeComponent(String) EscapeComponent(String) EscapeComponent(String)

Converts a Uniform Resource Identifier (URI) string to its escaped representation.

public static string EscapeComponent(String toEscape)public static string EscapeComponent(String toEscape)Public Static Function EscapeComponent(toEscape As String) As stringpublic static string EscapeComponent(String toEscape)
Parameters
toEscape
System.String System.String System.String System.String

The string to convert.

Returns
string string string string

The escaped representation of toEscape.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Use EscapeComponent(String) as a utility to escape any Uniform Resource Identifier (URI) component that requires escaping in order to construct a valid Uri object. For example, if your app is using a user-provided string and adding it to a query that is sent to a service, you may need to escape that string in the Uniform Resource Identifier (URI) because the string might contain characters that are invalid in a Uniform Resource Identifier (URI). This includes characters as simple as spaces; even input that seems to be pure ASCII may still need encoding to be valid as a component of a Uniform Resource Identifier (URI).

You can append the string you get from EscapeComponent(String) onto other strings before calling the @Windows.Foundation.Uri.#ctor(System.String). You'll want to encode each component separately, because you do not want to escape the characters that are significant to how the @Windows.Foundation.Uri.#ctor(System.String) parses the string into components, such as the "/" between host and path or the "?" between path and query.

EscapeComponent(String) might also be useful for other scenarios where a Uniform Resource Identifier (URI)-escaped string is needed for an HTTP request scenario, such as using APIs in the Windows.Web.Http namespace.

ToString() ToString() ToString() ToString()

Gets a canonical string representation for the current Uri.

public string ToString()public string ToString()Public Function ToString() As stringpublic string ToString()
Returns
string string string string

The unescaped canonical representation of the current Uri. All characters are unescaped, except #, ?, and %.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This ToString implementation is for the IStringable interface as implemented by the Uri class. IStringable is supported starting with Windows 8.1 and is also available in Windows Phone 8.1. The IStringable definition of ToString implementation is not literally an override of Platform::Object and its base API, but it does replace the ToString behavior.

For Windows 8 and Windows Phone 8, Uri does not implement IStringable (it's not available). So the ToString method of Uri remains the one that's implemented by Platform::Object or JavaScript "object" support for Windows Runtime. The apparent difference in origin of the ToString API is only visible for Visual C++ component extensions (C++/CX) and JavaScript, and you should consider it as an implementation detail that doesn't matter as far as how you use ToString in either case.

UnescapeComponent(String) UnescapeComponent(String) UnescapeComponent(String) UnescapeComponent(String)

Converts the specified string by replacing any escape sequences with their unescaped representation.

public static string UnescapeComponent(String toUnescape)public static string UnescapeComponent(String toUnescape)Public Static Function UnescapeComponent(toUnescape As String) As stringpublic static string UnescapeComponent(String toUnescape)
Parameters
toUnescape
System.String System.String System.String System.String

The string to convert.

Returns
string string string string

The unescaped representation of stringToUnescape.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Use UnescapeComponent(String) as a utility if you want a user-readable string of just a component, for example just the Path value, unescaped.