URI 方案URI schemes

你可以使用几种 URI(统一资源标识符)方案引用来自应用包、应用的数据文件夹或云的文件。There are several URI (Uniform Resource Identifier) schemes that you can use to refer to files that come from your app's package, your app's data folders, or the cloud. 还可以使用 URI 方案引用从应用的资源文件 (.resw) 加载的字符串。You can also use a URI scheme to refer to strings loaded from your app's Resources Files (.resw). 你可以在代码中、在 XAML 标记中、在应用包清单中或在磁贴和 toast 通知模板中使用这些 URI 方案。You can use these URI schemes in your code, in your XAML markup, in your app package manifest, or in your tile and toast notification templates.

URI 方案的常见功能Common features of the URI schemes

本主题中所述的所有方案均遵循适用于标准化和资源检索的典型的 URI 方案规则。All of the schemes described in this topic follow typical URI scheme rules for normalization and resource retrieval. 请参阅 RFC 3986 获取 URI 的常规语法。See RFC 3986 for the generic syntax of a URI.

所有 URI 方案均按照 RFC 3986 定义作为 URI 颁发机构和路径组件的层次结构部分。All of the URI schemes define the 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

这意味着 URI 基本上有三个组件。What this means is that there are essentially three components to a URI. URI 方案的两个正斜杠后紧跟着名称为颁发机构的组件(可以为空)。Immediately following the two forward slashes of the URI scheme is a component (which can be empty) called the authority. 之后紧跟路径And immediately following that is the path. 以 URI http://www.contoso.com/welcome.png 为例,方案为“http://”,颁发机构为“www.contoso.com”,路径为“/welcome.png”。Taking the URI http://www.contoso.com/welcome.png as an example, the scheme is "http://", the authority is "www.contoso.com", and the path is "/welcome.png". 另一个示例是 URI ms-appx:///logo.png,其中颁发机构组件为空并采用默认值。Another example is the URI ms-appx:///logo.png, where the authority components is empty and takes a default value.

本主题中所述的具体方案的 URI 处理忽略了片段组件。The fragment component is ignored by the scheme-specific processing of the URIs mentioned in this topic. 在资源检索和比较过程中,片段组件没有任何影响。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.

对所有 IRI 组件进行标准化后按字节进行比较。Comparison occurs byte for byte after normalization of all IRI components.

不区分大小写和标准化Case-insensitivity and normalization

本主题中所述的所有 URI 方案均遵循适用于方案标准化和资源检索的典型的 URI 规则 (RFC 3986)。All the URI schemes described in this topic follow typical URI rules (RFC 3986) for normalization and resource retrieval for schemes. 这些 URI 的标准化形式保持大小写,并对 RFC 3986 未保留的字符进行百分比解码。The normalized form of these URIs maintains case and percent-decodes RFC 3986 unreserved characters.

对于本主题所述的所有 URI 方案,方案颁发机构路径按照标准不区分大小写,或者由系统以不区分大小写的方式进行处理。For all the URI schemes described in this topic, scheme, authority, and path are either case-insensitive by standard, or else are processed by the system in a case-insensitive way. 注意该规则的唯一例外是 ms-resource颁发机构区分大小写。Note The only exception to that rule is the authority of ms-resource, which is case-sensitive.

ms-appx 和 ms-appx-webms-appx and ms-appx-web

使用 ms-appxms-appx-web URI 方案引用来自应用包的文件(请参阅打包应用)。Use the ms-appx or the ms-appx-web URI scheme to refer to a file that comes from your app's package (see Packaging apps). 应用包中的文件通常为静态图像、数据、代码和布局文件。Files in your app package are typically static images, data, code, and layout files. ms-appx-web 方案与 ms-appx 访问相同的文件,但是前者在 Web 隔离舱中访问。The ms-appx-web scheme accesses the same files as ms-appx, but in the web compartment. 有关示例和详细信息,请参阅引用 XAML 标记和代码中的图像或其他资产For examples and more info, see Reference an image or other asset from XAML markup and code.

方案名称(ms-appx 和 ms-appx-web)Scheme name (ms-appx and ms-appx-web)

URI 方案名称为字符串“ms-appx”或“ms-appx-web”。The URI scheme name is the string "ms-appx" or "ms-appx-web".

ms-appx://
ms-appx-web://

颁发机构(ms-appx 和 ms-appx-web)Authority (ms-appx and ms-appx-web)

颁发机构为在程序包清单中定义的程序包标识名称。The authority is the package identity name that is defined in the package manifest. 因此在 URI 和 IRI(国际化资源标识符)形式中都限制为在程序包标识名称中允许的字符组。It is therefore limited in both the URI and IRI (Internationalized resource identifier) form to the set of characters allowed in a package identity name. 程序包名称必须是在当前运行的应用的程序包依赖关系图中的其中一个包的名称。The package name must be the name of one of the packages in the current running app's package dependency graph.

ms-appx://Contoso.MyApp/
ms-appx-web://Contoso.MyApp/

如果颁发机构中出现任何其他字符,则检索和比较会失败。If any other character appears in the authority, then retrieval and comparison fail. 颁发机构的默认值是当前运行的应用的程序包。The default value for the authority is the currently running app's package.

ms-appx:///
ms-appx-web:///

用户信息和端口(ms-appx 和 ms-appx-web)User info and port (ms-appx and ms-appx-web)

ms-appx 方案与其他常用的方案不同,它不定义用户信息或端口组件。The ms-appx scheme, unlike other popular schemes, does not define a user info or port component. 由于“@" and ":”不允许作为有效的颁发机构值使用,因此如果将其包括在其中,查找将失败。Since "@" and ":" are not allowed as valid authority values, lookup will fail if they are included. 以下各项均无法正常工作。Each of the following fails.

ms-appx://john@contoso.myapp/default.html
ms-appx://john:password@contoso.myapp/default.html
ms-appx://contoso.myapp:8080/default.html
ms-appx://john:password@contoso.myapp:8080/default.html

路径(ms-appx 和 ms-appx-web)Path (ms-appx and ms-appx-web)

路径组件匹配通用 RFC 3986 语法,并支持 IRI 中的非 ASCII 字符。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 the app specified by the authority.

如果路径引用物理路径和文件名,则检索该物理文件资产。If the path refers to a physical path and file name then that physical file asset is retrieved. 但如果找不到任何此类物理文件,则在运行时使用内容协商确定在检索过程中返回的实际资源。But if no such physical file is found then the actual resource returned during retrieval is determined by using content negotiation at runtime. 这确定基于应用、操作系统和用户设置(如语言、显示比例系数、主题、高对比度和其他运行时上下文)。This determination is based on app, OS, and user settings such as language, display scale factor, theme, high contrast, and other runtime contexts. 例如,确定要检索的实际资源值时,可能会综合考虑应用的语言、系统的显示设置以及用户的高对比度设置。For example, a combination of the app's languages, the system's display settings, and the user's high contrast settings may be taken into account when determining the actual resource value to be retrieved.

ms-appx:///images/logo.png

上述 URI 实际上可能使用以下物理文件名检索当前应用包中的文件。The URI above may actually retrieve a file within the current app's package with the following physical file name.

\Images\fr-FR\logo.scale-100_contrast-white.png

当然,也可以通过直接引用全名的方式检索该相同的物理文件。You could of course also retrieve that same physical file by referring to it directly by its full name.

<Image Source="ms-appx:///images/fr-FR/logo.scale-100_contrast-white.png"/>

ms-appx(-web) 的路径组件同通用 URI 一样区分大小写。The path component of ms-appx(-web) is, like generic URIs, case sensitive. 但是,当访问资源所用的基本文件系统不区分大小写时,例如对于 NTFS,检索资源时将不区分大小写。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.

URI 的标准化形式保持大小写,并对 RFC 3986 未保留的字符进行百分比解码(“%”符号后紧跟两位十六进制表示形式)。The normalized form of the URI maintains case, and percent-decodes (a "%" symbol followed by the two-digit hexadecimal representation) RFC 3986 unreserved characters. 字符 "?"、"#"、"/"、"*" 和 "" " (双引号字符) 必须在路径中进行百分号编码,才能表示文件或文件夹名称等数据。The characters "?", "#", "/", "*", and '"' (the double-quote character) must be percent-encoded in a path to represent data such as file or folder names. 所有百分比编码字符在检索前解码。All percent-encoded characters are decoded before retrieval. 因此,要检索名称为 Hello#World.html 的文件,请使用此 URI。Thus, to retrieve a file named Hello#World.html, use this URI.

ms-appx:///Hello%23World.html

查询(ms-appx 和 ms-appx-web)Query (ms-appx and ms-appx-web)

在资源检索过程中忽略查询参数。Query parameters are ignored during retrieval of resources. query 参数的标准化形式保持大小写。The normalized form of query parameters maintains case. 在比较过程中不忽略查询参数。Query parameters are not ignored during comparison.

ms-appdatams-appdata

使用 ms-appdata URI 方案引用来自应用的本地、漫游和临时数据文件夹的文件。Use the ms-appdata URI scheme to refer to files that come from the app's local, roaming, and temporary data folders. 有关这些应用数据文件夹的详细信息,请参阅存储和检索设置以及其他应用数据For more info about these app data folders, see Store and retrieve settings and other app data.

ms-appdata URI 方案不执行 ms appx 和 ms appx web 所执行的运行时内容协商。The ms-appdata URI scheme does not perform the runtime content negotiation that ms-appx and ms-appx-web do. 但你可以响应 ResourceContext.QualifierValues 的内容并使用它们在 URI 中的完整物理文件名加载相应资产。But you can respond to the contents of ResourceContext.QualifierValues and load the appropriate assets from app data using their full physical file name in the URI.

方案名称 (ms-appdata)Scheme name (ms-appdata)

URI 方案名称为字符串“ms-appdata”。The URI scheme name is the string "ms-appdata".

ms-appdata://

颁发机构 (ms-appdata)Authority (ms-appdata)

颁发机构为在程序包清单中定义的程序包标识名称。The authority is the package identity name that is defined in the package manifest. 因此在 URI 和 IRI(国际化资源标识符)形式中都限制为在程序包标识名称中允许的字符组。It is therefore limited in both the URI and IRI (Internationalized resource identifier) form to the set of characters allowed in a package identity name. 程序包名称必须是当前运行的应用包的名称。The package name must be the name of the current running app's package.

ms-appdata://Contoso.MyApp/

如果颁发机构中出现任何其他字符,则检索和比较会失败。If any other character appears in the authority, then retrieval and comparison fail. 颁发机构的默认值是当前运行的应用的程序包。The default value for the authority is the currently running app's package.

ms-appdata:///

用户信息和端口 (ms-appdata)User info and port (ms-appdata)

ms-appdata 方案与其他常用的方案不同,它不定义用户信息或端口组件。The ms-appdata scheme, unlike other popular schemes, does not define a user info or port component. 由于“@" and ":”不允许作为有效的颁发机构值使用,因此如果将其包括在其中,查找将失败。Since "@" and ":" are not allowed as valid authority values, lookup will fail if they are included. 以下各项均无法正常工作。Each of the following fails.

ms-appdata://john@contoso.myapp/local/data.xml
ms-appdata://john:password@contoso.myapp/local/data.xml
ms-appdata://contoso.myapp:8080/local/data.xml
ms-appdata://john:password@contoso.myapp:8080/local/data.xml

路径 (ms-appdata)Path (ms-appdata)

路径组件匹配通用 RFC 3986 语法,并支持 IRI 中的非 ASCII 字符。The path component matches the generic RFC 3986 syntax and supports non-ASCII characters in IRIs. Windows.Storage.ApplicationData 位置中有三个保留的文件夹用于本地、漫游和临时状态存储。Within the Windows.Storage.ApplicationData location are three reserved folders for local, roaming, and temporary state storage. ms-appdata 方案允许访问这些位置的文件和文件夹。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. 因此“hier-part”的“path-empty”形式不合法。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/

ms-appdata 的路径组件同通用 URI 一样区分大小写。The path component of ms-appdata is, like generic URIs, case sensitive. 但是,当访问资源所用的基本文件系统不区分大小写时,例如对于 NTFS,检索资源时将不区分大小写。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.

URI 的标准化形式保持大小写,并对 RFC 3986 未保留的字符进行百分比解码(“%”符号后紧跟两位十六进制表示形式)。The normalized form of the URI maintains case, and percent-decodes (a "%" symbol followed by the two-digit hexadecimal representation) RFC 3986 unreserved characters. 字符 "?"、"#"、"/"、"*" 和 "" " (双引号字符) 必须在路径中进行百分号编码,才能表示文件或文件夹名称等数据。The characters "?", "#", "/", "*", and '"' (the double-quote character) must be percent-encoded in a path to represent data such as file or folder names. 所有百分比编码字符在检索前解码。All percent-encoded characters are decoded before retrieval. 因此,要检索名称为 Hello#World.html 的本地文件,请使用此 URI。Thus, to retrieve a local file named Hello#World.html, use this URI.

ms-appdata://local/Hello%23World.html

资源的检索以及顶级路径段的标识在点标准化(“.././b/c”)后进行处理。Retrieval of the resource, and identification of the top level path segment, are handled after normalization of dots (".././b/c"). 因此,URI 不能在其中一个保留的文件夹对它们自身使用点。Therefore, URIs cannot dot themselves out of one of the reserved folders. 因此不允许使用以下 URI。Thus, the following URI is not allowed.

ms-appdata:///local/../hello/logo.png

但允许此 URI(尽管冗余)。But this URI is allowed (albeit redundant).

ms-appdata:///local/../roaming/logo.png

查询 (ms-appdata)Query (ms-appdata)

在资源检索过程中忽略查询参数。Query parameters are ignored during retrieval of resources. query 参数的标准化形式保持大小写。The normalized form of query parameters maintains case. 在比较过程中不忽略查询参数。Query parameters are not ignored during comparison.

ms-resourcems-resource

使用 ms-resource URI 方案引用从应用的资源文件 (.resw) 加载的字符串。Use the ms-resource URI scheme to refer to strings loaded from your app's Resources Files (.resw). 有关资源文件的示例和详细信息,请参阅本地化 UI 和应用包清单中的字符串For examples and more info about Resources Files, see Localize strings in your UI and app package manifest.

方案名称 (ms-resource)Scheme name (ms-resource)

URI 方案名称为字符串“ms-resource”。The URI scheme name is the string "ms-resource".

ms-resource://

颁发机构 (ms-resource)Authority (ms-resource)

颁发机构是在包资源索引 (PRI) 中定义的顶级资源映射,它通常对应在程序包清单中定义的程序包标识名称。The authority is the top-level resource map defined in the Package Resource Index (PRI), which typically corresponds to the package identity name that is defined in the package manifest. 请参阅) 打包应用See Packaging apps). 因此在 URI 和 IRI(国际化资源标识符)形式中都限制为在程序包标识名称中允许的字符组。It is therefore limited in both the URI and IRI (Internationalized resource identifier) form to the set of characters allowed in a package identity name. 程序包名称必须是在当前运行的应用的程序包依赖关系图中的其中一个包的名称。The package name must be the name of one of the packages in the current running app's package dependency graph.

ms-resource://Contoso.MyApp/
ms-resource://Microsoft.WinJS.1.0/

如果颁发机构中出现任何其他字符,则检索和比较会失败。If any other character appears in the authority, then retrieval and comparison fail. 颁发机构的默认值是当前运行的应用的区分大小写的包名称。The default value for the authority 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, happens case-insensitively.

用户信息和端口 (ms-resource)User info and port (ms-resource)

ms-resource 方案与其他常用的方案不同,它不定义用户信息或端口组件。The ms-resource scheme, unlike other popular schemes, does not define a user info or port component. 由于“@" and ":”不允许作为有效的颁发机构值使用,因此如果将其包括在其中,查找将失败。Since "@" and ":" are not allowed as valid authority values, lookup will fail if they are included. 以下各项均无法正常工作。Each of the following fails.

ms-resource://john@contoso.myapp/Resources/String1
ms-resource://john:password@contoso.myapp/Resources/String1
ms-resource://contoso.myapp:8080/Resources/String1
ms-resource://john:password@contoso.myapp:8080/Resources/String1

路径 (ms-resource)Path (ms-resource)

路径标识 ResourceMap 子树(请参阅资源管理系统)和其中的 NamedResource 的分层位置。The path identifies the hierarchical location of the ResourceMap subtree (see Resource Management System) and the NamedResource within it. 通常情况下,它对应资源文件 (.resw) 的文件名(不包括扩展)和其中的字符串资源的标识符。Typically, this corresponds to the filename (excluding extension) of a Resources Files (.resw) and the identifier of a string resource within it.

有关示例和详细信息,请参阅本地化 UI 和应用包清单中的字符串磁贴和 toast 通知的语言、比例和高对比度支持For examples and more info, see Localize strings in your UI and app package manifest and Tile and toast notification support for language, scale, and high contrast.

ms-resource 的路径组件同通用 URI 一样区分大小写。The path component of ms-resource is, like generic URIs, case sensitive. 但是,基础检索将执行 CompareStringOrdinal ,并将 regexoptions.ignorecase 设置为 trueHowever, the underlying retrieval does a CompareStringOrdinal with ignoreCase set to true.

URI 的标准化形式保持大小写,并对 RFC 3986 未保留的字符进行百分比解码(“%”符号后紧跟两位十六进制表示形式)。The normalized form of the URI maintains case, and percent-decodes (a "%" symbol followed by the two-digit hexadecimal representation) RFC 3986 unreserved characters. 字符 "?"、"#"、"/"、"*" 和 "" " (双引号字符) 必须在路径中进行百分号编码,才能表示文件或文件夹名称等数据。The characters "?", "#", "/", "*", and '"' (the double-quote character) must be percent-encoded in a path to represent data such as file or folder names. 所有百分比编码字符在检索前解码。All percent-encoded characters are decoded before retrieval. 因此,若要从名为的资源文件中检索字符串资源 Hello#World.resw ,请使用此 URI。Thus, to retrieve a string resource from a Resources File named Hello#World.resw, use this URI.

ms-resource:///Hello%23World/String1

查询 (ms-resource)Query (ms-resource)

在资源检索过程中忽略查询参数。Query parameters are ignored during retrieval of resources. query 参数的标准化形式保持大小写。The normalized form of query parameters maintains case. 在比较过程中不忽略查询参数。Query parameters are not ignored during comparison. 查询参数在比较时区分大小写。Query parameters are compared case-sensitively.

在此 URI 分析上分层的特定组件的开发人员在合适的情况下可以选择使用查询参数。Developers of particular components layered above this URI parsing may choose to use the query parameters as they see fit.