URI schemes
You can use URI (Uniform Resource Identifier) schemes to refer to app files that come from the app's package, data folders, or resources.
ms-appx(-web)
Use the ms-appx and ms-appx-web schemes to refer to app files that come from the app's package (see App packages and deployment). Such files are typically static images, data, code, and layout files. The ms-appx-web scheme references these same files, but in the web compartment. See How to load file resources for common usage.
Scheme name
The URI scheme name is the string "ms-appx"
ms-appx://
or "ms-appx-web".
ms-appx-web://
The scheme name follows typical URI rules (RFC 3986) for normalization and resource retrieval for schemes. The scheme name is US-ASCII case insensitive and the normalized form of the scheme name is lowercase.
Hierarchical Part
This URI scheme defines its hierarchical part per RFC 3986 as the authority and path components of the URI:
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
Authority
The authority is a US-ASCII case insensitive identifier of the entity that owns the files.
The URI or IRI (Internationalized resource identifier) authority for the ms-appx(-web) scheme is the package identity name (see App packages and deployment) that is defined in the package manifest. It is therefore limited in both the IRI and URI form to the set of characters allowed in a package identity name. The package name is limited to those in the current running app's package dependency graph.
ms-appx://Contoso.MyApp/
ms-appx-web://Contoso.MyApp/
If any other characters are given in the authority, then retrieval and comparison fail.
The value for the authority, when the given authority is blank, is the currently running app's package:
ms-appx:///
ms-appx-web:///
The normal form for the authority is the package identity name in lowercase, according to US-ASCII case insensitivity. For example,
document.location // Returns ms-appx://contoso.myapp/default.html
Thus, during retrieval of the resource, the authority can be lowercase or uppercase, but either way it refers to the same resource.
User Info and Port
The ms-appx scheme, unlike other popular schemes, does not define a user info or port component. Since "@" and ":" are not allowed as valid authority values, lookup will fail if they are included. Each of the following fails:
// Examples of schemes that fail:
ms-appx://[email protected]/default.html
ms-appx://john:[email protected]/default.html
ms-appx://contoso.myapp:8080/default.html
ms-appx://john:[email protected]:8080/default.html
Path
The path component matches the generic RFC 3986 syntax and supports non-ASCII characters in IRIs.
The path component defines the logical or physical file path of a file. That file is in a folder associated with the installed location of the app package, for an app specified by the authority.
The path component may define a logical, rather than physical, resource. In this case the actual resource returned during retrieval is determined by using content negotiation at runtime. This determination is based on the current state of the system, to identify the most appropriate resource. If the path component instead refers to a physical file path and not a logical one, the physical file asset is retrieved without any content negotiation.
For example, the app's languages, the system's display settings, and the user's contrast settings may be taken into account when determining the actual resource value to be retrieved:
ms-appx://contoso.myapp/images/logo.png
The above may actually retrieve a file within the Contoso.myapp package named
images/fr-FR/logo.scale-100_contrast-white.png
You may refer directly to the physical image as well if necessary:
<img src="/images/fr-FR/logo.scale-100_contrast-white.png" />
See How to load file resources for an introduction to commonly used values.
The path component of ms-appx(-web) is, like generic URIs, case sensitive. However, when the underlying file system by which the resource is accessed is case insensitive, such as for NTFS, the retrieval of the resource is done case-insensitively.
The normalized form of the URI maintains case and percent-decodes RFC 3986 unreserved characters.
The characters "?", "#", "/", "*", and '”' (the double-quote character) must be percent-encoded in a path to represent data such as a file or folder names. All percent-encoded characters are decoded before retrieval. Thus to retrieve a file named Hello#World.html, use
ms-appx:///Hello%23World.html
Query
Query parameters are ignored during retrieval of resources. The normalized form of query parameters maintains case. Query parameters are not ignored during comparison.
Developers of particular components layered above this URI parsing may choose to use the query parameters as they see fit. For example, the app host may retrieve a particular HTML file while ignoring the query parameters. But, the code running in the page may still use the query parameters as state to render something specific on the page.
Fragment
The fragment component is ignored by the scheme-specific processing of URIs. During resource retrieval and comparison, the fragment component has no bearing. However, layers above specific implementation may interpret the fragment to retrieve a secondary resource.
For example, the app host may process ms-appx URIs, where a navigation goes to a ms-appx: URI and scrolls to an anchor point identified by the fragment, but the specific URLMon implementation of ms-appx: is responsible only for retrieving the HTML page, ignoring the fragment.
Comparison
Comparison occurs byte for byte after normalization of all IRI components.
ms-appdata
Use the ms-appdata scheme to refer to app files that come from the app's local, roaming, and temporary data folders. See How to load file resources for common usage, and Accessing app data with the Windows Runtime for more on app data.
Scheme name
The URI scheme name is the string "ms-appdata".
ms-appdata://
The URI scheme follows typical IRI rules for normalization and resource retrieval for schemes. The scheme name is US-ASCII case insensitive, and the normalized form of the scheme name is lowercase.
Hierarchical Part
This URI scheme defines its hierarchical part per RFC 3986 as the authority and path components of the URI:
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
Authority
The authority for the ms-appdata URI is the package identity name (see App packages and deployment) defined in the package manifest. The package name is limited to the current running app's package.
ms-appdata://Contoso.MyApp/
If any other characters are given in the authority, then retrieval and comparison fail.
The value for the authority, when the given authority is blank, is the currently running app's package:
ms-appdata:///
The normal form for the authority is the package identity name in lowercase, according to US-ASCII case insensitivity.
User Info and Port
The ms-appdata scheme, unlike other popular schemes, does not define a user info or port component. Since "@" and ":" are not allowed as valid authority values, lookup will fail if they are included. Each of the following fails:
// Examples of schemes that fail:
ms-appdata://[email protected]/local/data.xml
ms-appdata://john:[email protected]/local/data.xml
ms-appdata://contoso.myapp:8080/local/data.xml
ms-appdata://john:[email protected]:8080/local/data.xml
Path
Within the Windows.Storage.ApplicationData location are three reserved folders for local, roaming, and temporary state storage. The ms-appdata scheme allows access to files and folders in those locations. The first segment of the path component must specify the particular folder in the following fashion. Thus the "path-empty" form of "hier-part" is not legal.
Local folder:
ms-appdata:///local/
Temporary folder:
ms-appdata:///temp/
Roaming folder:
ms-appdata:///roaming/
The path component of ms-appdata is, like generic URIs, case sensitive. However, when the underlying file system by which the resource is accessed is case insensitive, such as for NTFS, the retrieval of the resource is done case-insensitively.
The normalized form of the URI maintains case and percent-decodes RFC 3986 unreserved characters.
The characters "?", "#", "/", "*", and '”' (the double-quote character) must be percent-encoded in a path to represent data such as a file or folder names. All percent-encoded characters are decoded before retrieval. Thus to retrieve a file named Hello#World.xml, use
ms-appdata:///Hello%23World.xml
Retrieval of the resource and identification of the top level path segment are handled after normalization of dots (".././b/c"). Therefore, URIs cannot dot themselves out of one of the reserved folders. Thus, the following URI s not allowed:
ms-appdata:///local/../hello/logo.png
but this URI is allowed:
ms-appdata:///local/../roaming/logo.png
Query
Query parameters are ignored during retrieval of resources. The normalized form of the query parameters maintains case. Query parameters are not ignored during comparison.
Developers of particular components layered above this URI parsing may choose to use the query parameters as they see fit. For example, the app host may retrieve a particular image while ignoring the query parameters, but the code running in the page may use the query parameters as state to render something specific on the page.
Fragment
The fragment component is ignored by the scheme-specific processing of URIs. During resource retrieval and comparison, the fragment component has no bearing. However, layers above specific implementation may interpret the fragment to retrieve a secondary resource.
ms-resource
Use the ms-resource scheme to refer to app resources, which are typically string resources. This scheme is typically used in conjunction with the Windows.ApplicationModel.Resources, Windows.ApplicationModel.Resources.Core, or WinJS.Resources APIs to do lookup of resources in PRI files (see Resource Management System). See How to load string resources for common usage patterns.
Scheme name
The URI scheme name is the string "ms-resource".
ms-resource://
The URI scheme follows typical URI rules for normalization and resource retrieval for schemes. The scheme name is US-ASCII case insensitive and the normalized form of the scheme is lowercase.
Hierarchical Part
This URI scheme defines its hierarchical part per RFC 3986 as the authority and path components of the URI:
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
Authority
The authority for the ms-resource URI is the top-level resource map defined in the PRI, which typically corresponds to the package identity name (see App packages and deployment) defined in the package manifest. For Windows Store apps, the resource map name is limited to the names in the current running app's package dependency graph.
ms-resource://Contoso.MyApp/
ms-resource://Microsoft.WinJS.1.0/
If any other characters are given in the authority, retrieval and comparison fail.
The value for the hostname, when the given hostname is blank, is the case sensitive package name of the currently running app:
ms-resource:///
The authority is case sensitive and the normalized form maintains its case. Lookup of a resource, however, does so case-insensitively.
User Info and Port
The ms-resource scheme, unlike other popular schemes, does not define a user info or port component. Since "@" and ":" are not allowed as valid authority values, lookup will fail if they are included. Each of the following fails:
// Examples of schemes that fail:
ms-resource://[email protected]/Resources/String1
ms-resource://john:[email protected]/Resources/String1
ms-resource://contoso.myapp:8080/Resources/String1
ms-resource://john:[email protected]:8080/Resources/String1
Path
The path identifies the hierarchical location of the ResourceMap subtree (see Resource Management System) and the NamedResource within it. Typically, this corresponds to the filename (excluding extension) of the resource file and the name of the resource within it. For example, for a file named resources.resjson that contains
{
"String1" : "Hello World"
}
the following ms-resource URI can be used:
ms-resource:///resources/String1
The path component of ms-resource is, like generic URIs, case sensitive. However, the underlying retrieval does a CompareStringOrdinal with ignoreCase set as true case insensitive retrieval.
The normalized form of the URI maintains case.
The characters "?", "#", "/", "*", and '”' (the double-quote character) must be percent-encoded in a path to represent data such as a file or folder names. All percent-encoded characters are decoded before retrieval. Thus to retrieve a file named Hello#World.xml, use
ms-appdata:///Hello%23World.xml
Query
Query parameters are not ignored during comparison. Query parameters are compared case sensitively. Query parameters are ignored during retrieval of resources.
Developers of particular components layered above this URI parsing may choose to use the query parameters as they see fit.
Fragment
The fragment component is ignored by the scheme-specific processing of URIs. During resource retrieval and comparison, the fragment component has no bearing. However, layers above specific implementation may interpret the fragment to retrieve a secondary resource.
Related topics
RFC 3986: Uniform Resource Identifier (URI): Generic Syntax
Accessing app data with the Windows Runtime
Windows.ApplicationModel.Resources
Windows.ApplicationModel.Resources.Core