Skip to main content
Uri class

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.

Syntax


var uri = new Windows.Foundation.Uri(string);
var uri = new Windows.Foundation.Uri(string, string);

public ref class Uri sealed : IStringable

Attributes

[ DualApiPartition()]
[ MarshalingBehavior(Agile)]
[ Threading(Both)]
[ Version(0x06020000)]

Members

The Uri class has these types of members:

Constructors

The Uri class has these constructors.

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

 

Methods

The Uri class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
CombineUri Adds the specified Uniform Resource Identifier (URI) to the current Uri.
Equals Determines whether the specified Uri object is equal to the current Uri object.
EscapeComponent Converts a Uniform Resource Identifier (URI) string to its escaped representation.
ToString Gets a canonical string representation for the current Uri.
UnescapeComponent Converts the specified string by replacing any escape sequences with their unescaped representation.

 

Properties

The Uri class has these properties.

PropertyAccess typeDescription

AbsoluteCanonicalUri

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

AbsoluteUri

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

DisplayIri

Read-onlyGets the decoded unicode characters that make up the current URI.

DisplayUri

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

Domain

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

Extension

Read-onlyGets the file name extension of the resource that is referenced in the Uri.

Fragment

Read-onlyGets the text following a fragment marker (#), including the fragment marker itself.

Host

Read-onlyGets the fully qualified domain name.

Password

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

Path

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

Port

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

Query

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

QueryParsed

Read-onlyGets a parsed Uniform Resource Identifier (URI) query string.

RawUri

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

SchemeName

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

Suspicious

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

UserName

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

 

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 URIs. The Windows.Foundation.Uri class doesn't percent-encode non-ASCII characters in URIs where the scheme refers to a Windows file path (like ms-appx:). Windows.Foundation.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 Windows.Foundation.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 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) URIs. 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:

Each of these schemes ignores many of the component parts of a 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 URIs. All Uri objects you create must represent an absolute URI. The schemes listed in the previous section are actually absolute URIs, 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 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 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);

Requirements ( device family)

Device family

Universal

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.Foundation
Windows::Foundation [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (operating system)

Minimum supported client

Windows 8 [Windows Store apps, desktop apps]

Minimum supported server

Windows Server 2012 [Windows Store apps, desktop apps]

Minimum supported phone

Windows Phone 8

Namespace

Windows.Foundation
Windows::Foundation [C++]

Metadata

Windows.winmd

See also

Object
IStringable
System.Uri
How to reference content (HTML)
How to load file resources (XAML)
Connecting to networks and web services
WwwFormUrlDecoder
createObjectURL (for HTML/JavaScript)
RFC 3986
RFC 3987