WPF 中的 Pack URI

在 Windows Presentation Foundation (WPF) 中，统一资源标识符 (URI) 用于以多种方式标识和加载文件，包括以下内容：

• 指定当应用程序第一次启动时显示的用户界面 (UI)。

• 加载图像。

• 导航到页。

• 加载不可执行的数据文件。

此外，可以使用 URI 标识和加载位于各种位置的文件，这些位置包括：

• 当前程序集。

• 引用的程序集。

• 相对于程序集的某个位置。

• 应用程序的源站点。

为了提供从这些位置标识和加载上述类型的文件的一致机制，WPF 利用了“pack URI 方案”的扩展性。 本主题将概述该方案，介绍如何为各种方案构造 pack URI，讨论绝对和相对 URI 以及 URI 解析，然后说明如何在标记和代码中使用 pack URI。

Pack URI 方案

pack URI 方案由开放式打包约定 (OPC) 规范使用，该规范描述用于组织和标识内容的模型。 此模型的关键元素是包和部件，其中“包”是一个或多个逻辑“部件”的逻辑容器。 下图阐释了此概念。

为了标识部件，OPC 规范利用 RFC 2396（统一资源标识符 (URI)：一般语法）的扩展性来定义 pack URI 方案。

URI 所指定的方案由其前缀定义；http、ftp 和 file 是众所周知的示例。 pack URI 方案使用“pack”作为它的方案，并且包含两个组件：授权和路径。 以下是 pack URI 的格式。

pack://authority/path

authority 指定包含部件的包的类型，而 path 指定部件在包内的位置。

下图阐释了此概念：

包和部件之间的关系类似于应用程序和文件之间的关系，其中应用程序（包）可以包含一个或多个文件（部件），包括：

• 编译到本地程序集内的资源文件。

• 编译到所引用的程序集内的资源文件。

• 编译到引用程序集内的资源文件。

• 内容文件。

• 源站点文件。

为了访问这些类型的文件，WPF 支持两种授权：application:/// 和 siteoforigin:///。 application:/// 授权标识在编译时已知的应用程序数据文件，包括资源文件和内容文件。 siteoforigin:/// 授权标识源站点文件。 下图显示了每种授权的范围。

注意

pack URI 的授权组件是一个嵌入式 URI，它指向一个包并且必须符合 RFC 2396。 另外，必须用字符“,”替换字符“/”，并且必须对保留字符（如“%”和“?”）进行转义。 有关详细信息，请参阅 OPC。

以下各节介绍如何将这两种授权与用于标识资源、内容和源站点文件的相应路径结合使用来构造 pack URI。

资源文件 Pack URI

将资源文件配置为 MSBuild Resource 项并将其编译到程序集内。 WPF 支持构造用于标识资源文件的 pack URI，这些文件会编译到本地程序集内，或者编译到从本地程序集引用的程序集内。

本地程序集资源文件

编译到本地程序集内的资源文件的 pack URI 使用以下授权和路径：

• 授权：application:///。

• 路径：资源文件的名称，包括其相对于本地程序集项目文件夹根目录的路径。

下面的示例演示了一个 XAML 资源文件的 pack URI，该资源文件位于本地程序集的项目文件夹的根目录中。

pack://application:,,,/ResourceFile.xaml

下面的示例演示了一个 XAML 资源文件的 pack URI，该资源文件位于本地程序集的项目文件夹的子文件夹中。

pack://application:,,,/Subfolder/ResourceFile.xaml

引用的程序集资源文件

编译到所引用程序集内的资源文件的 pack URI 使用以下授权和路径：

• 授权：application:///。

• 路径：编译到所引用程序集内的资源文件的名称。 路径必须符合以下格式：

  AssemblyShortName{;Version]{;PublicKey];component/Path

  • 程序集短名称：所引用的程序集的短名称。

  • ;版本 [可选]：所引用的包含资源文件的程序集的版本。 此部分在加载两个或多个具有相同短名称的引用程序集时使用。

  • ;公钥 [可选]：用于对引用程序集进行签名的公钥。 此部分在加载两个或多个具有相同短名称的引用程序集时使用。

  • ;组件：指定所引用的程序集是从本地程序集引用的。

  • /路径：资源文件的名称，包括其相对于所引用程序集的项目文件夹根目录的路径。

下面的示例演示了一个 XAML 资源文件的 pack URI，该资源文件位于所引用程序集的项目文件夹的根目录中。

pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml

下面的示例演示了一个 XAML 资源文件的 pack URI，该资源文件位于所引用程序集的项目文件夹的子文件夹中。

pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml

下面的示例演示了一个 XAML 资源文件的 pack URI，该资源文件位于特定于版本的引用程序集的项目文件夹的根文件夹中。

pack://application:,,,/ReferencedAssembly;v1.0.0.1;component/ResourceFile.xaml

请注意，所引用的程序集资源文件的 pack URI 语法只能与 application:/// 授权一起使用。 例如，WPF 中不支持下面的格式。

pack://siteoforigin:,,,/SomeAssembly;component/ResourceFile.xaml

内容文件 Pack URI

内容文件的 pack URI 使用以下授权和路径：

• 授权：application:///。

• 路径：内容文件的名称，包括其相对于应用程序的主可执行程序集的文件系统位置的路径。

下面的示例演示了一个 XAML 内容文件的 pack URI，该内容文件与可执行程序集位于相同的文件夹中。

pack://application:,,,/ContentFile.xaml

下面的示例演示了一个 XAML 内容文件的 pack URI，该内容文件位于某个相对于应用程序的可执行程序集的子文件夹中。

pack://application:,,,/Subfolder/ContentFile.xaml

注意

无法导航到 HTML 内容文件。 URI 方案仅支持导航到位于源站点的 HTML 文件。

源站点 Pack URI

源站点文件的 pack URI 使用以下授权和路径：

• 授权：siteoforigin:///。

• 路径：源站点文件的名称，包括其相对于可执行程序集启动位置的路径。

下面的示例演示了一个 XAML 源站点文件的 pack URI，该源站点文件存储在可执行程序集的启动位置。

pack://siteoforigin:,,,/SiteOfOriginFile.xaml

下面的示例演示了一个 XAML 源站点文件的 pack URI，该源站点文件存储在相对于应用程序可执行程序集的启动位置的子文件夹中。

pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml

页面文件

配置为 MSBuild Page 项的 XAML 文件采用与资源文件相同的方式编译到程序集内。 因此，可以使用资源文件的 pack URI 来标识 MSBuild Page 项。

通常配置为 MSBuild Page 项的 XAML 文件类型会将下列元素之一作为它们的根元素：

• System.Windows.Window

• System.Windows.Controls.Page

• System.Windows.Navigation.PageFunction<T>

• System.Windows.ResourceDictionary

• System.Windows.Documents.FlowDocument

• System.Windows.Controls.UserControl

绝对 Pack URI 与相对 Pack URI

完全限定的 pack URI 包括方案、授权和路径，它视为绝对 pack URI。 作为面向开发者的简化，XAML 元素通常允许使用仅包含路径的相对 pack URI 来设置相应的属性。

例如，假设本地程序集中的某个资源文件具有以下绝对 pack URI。

pack://application:,,,/ResourceFile.xaml

引用此资源文件的相对 pack URI 如下所示。

/ResourceFile.xaml

注意

因为源站点文件不与程序集相关联，所以只能使用绝对 pack URI 引用源站点文件。

默认情况下，会将相对 pack URI 视为相对于包含引用的标记或代码的位置。 但是，如果使用前导反斜杠，则将相对 pack URI 引用视为相对于应用程序的根目录。 例如，假设具有以下项目结构。

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

如果 Page1.xaml 包含引用 Root\SubFolder\Page2.xaml 的 URI，该引用可以使用以下相对 pack URI。

Page2.xaml

如果 Page1.xaml 包含引用 Root\Page2.xaml 的 URI，该引用可以使用以下相对 pack URI。

/Page2.xaml

Pack URI 解析

pack URI 的格式让不同文件类型的 pack URI 看起来相同成为可能。 例如，假设具有以下绝对 pack URI。

pack://application:,,,/ResourceOrContentFile.xaml

此绝对 pack URI 可以引用本地程序集内的资源文件，或者引用内容文件。 对于以下相对 URI 而言也是如此。

/ResourceOrContentFile.xaml

为了确定 pack URI 引用的文件的类型，WPF 使用下面的启发法来解析本地程序集内的资源文件以及内容文件的 URI：

1. 探测程序集元数据中是否有与包 URI 匹配的 AssemblyAssociatedContentFileAttribute 的属性。

2. 如果找到了 AssemblyAssociatedContentFileAttribute 属性，包 URI 的路径将引用内容文件。

3. 如果未找到 AssemblyAssociatedContentFileAttribute 属性，请探测编译到本地程序集中的集资源文件。

4. 如果找到与 pack URI 的路径匹配的资源文件，则 pack URI 的路径将引用资源文件。

5. 如果未找到资源文件，则内部创建的 Uri 无效。

URI 解析不适用于引用以下文件的 URI：

• 所引用程序集内的内容文件：WPF 不支持这些文件类型。

• 所引用程序集内的嵌入式文件：标识这些文件的 URI 是唯一的，因为它们包含应用程序集的名称以及 ;component 后缀。

• 源站点文件：标识这些文件的 URI 是唯一的，因为仅这些文件使用包含 siteoforigin:/// 授权的 pack URI 进行标识。

pack URI 解析所允许使用的一种简化形式是让代码在一定程度上独立于资源和内容文件的位置。 例如，如果本地程序集内的某个资源文件已重新配置为内容文件，则该资源的 pack URI 会保留原样，而使用该 pack URI 的代码也是如此。

使用 Pack URI 编程

许多 WPF 类都实现了可以用 pack URI 设置的属性，包括：

• Application.StartupUri

• Frame.Source

• NavigationWindow.Source

• Hyperlink.NavigateUri

• Window.Icon

• Image.Source

可以从标记和代码中设置这些属性。 本节演示这两种设置方式的基本构造，然后演示通用方案示例。

在标记中使用 Pack URI

在标记中，使用 pack URI 设置某个属性的元素，从而指定 pack URI。 例如：

<element attribute="pack://application:,,,/File.xaml" />

表 1 阐释了可以在标记中指定的各种绝对 pack URI。

表 1：标记中的绝对 Pack URI

文件	绝对 pack URI
资源文件 - 本地程序集	"pack://application:,,,/ResourceFile.xaml"
子文件夹中的资源文件 - 本地程序集	"pack://application:,,,/Subfolder/ResourceFile.xaml"
资源文件 - 引用的程序集	"pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml"
所引用程序集的子文件夹中的资源文件	"pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
所引用版本化程序集中的资源文件	"pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml"
内容文件	"pack://application:,,,/ContentFile.xaml"
子文件夹中的内容文件	"pack://application:,,,/Subfolder/ContentFile.xaml"
源站点文件	"pack://siteoforigin:,,,/SOOFile.xaml"
子文件夹中的源站点文件	"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

表 2 阐释了可以在标记中指定的各种相对 pack URI。

表 2：标记中的相对 Pack URI

文件	相对 pack URI
本地程序集内的资源文件	"/ResourceFile.xaml"
本地程序集的子文件夹中的资源文件	"/Subfolder/ResourceFile.xaml"
所引用程序集内的资源文件	"/ReferencedAssembly;component/ResourceFile.xaml"
所引用程序集的子文件夹中的资源文件	"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
内容文件	"/ContentFile.xaml"
子文件夹中的内容文件	"/Subfolder/ContentFile.xaml"

在代码中使用 Pack URI

在代码中，可以通过实例化 Uri 类并将 pack URI 作为参数传递给构造函数来指定 pack URI。 以下示例就此进行演示。

Uri uri = new Uri("pack://application:,,,/File.xaml");

默认情况下，Uri 类将 pack URI 视为绝对 pack URI。 因此，在使用相对 pack URI 创建 Uri 类的实例时会引发异常。

Uri uri = new Uri("/File.xaml");

幸运的是，Uri 类构造函数的 Uri(String, UriKind) 重载接受类型为 UriKind 的参数，以允许你指定包 URI 是绝对的还是相对的。

// Absolute URI (default)
Uri absoluteUri = new Uri("pack://application:,,,/File.xaml", UriKind.Absolute);
// Relative URI
Uri relativeUri = new Uri("/File.xaml",
                        UriKind.Relative);

当你能够确定所提供的 pack URI 是相对 pack URI 还是绝对 pack URI 时，应仅指定 Absolute 或 Relative。 如果你不了解所使用的 pack URI 的类型（例如，当用户在运行时输入 pack URI 时），请改用 RelativeOrAbsolute。

// Relative or Absolute URI provided by user via a text box
TextBox userProvidedUriTextBox = new TextBox();
Uri uri = new Uri(userProvidedUriTextBox.Text, UriKind.RelativeOrAbsolute);

表 3 阐释了可以使用 System.Uri 在代码中指定的各种相对 pack URI。

表 3：代码中的绝对 Pack URI

文件	绝对 pack URI
资源文件 - 本地程序集	Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute);
子文件夹中的资源文件 - 本地程序集	Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute);
资源文件 - 引用的程序集	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute);
所引用程序集的子文件夹中的资源文件	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);
所引用版本化程序集中的资源文件	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute);
内容文件	Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute);
子文件夹中的内容文件	Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute);
源站点文件	Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);
子文件夹中的源站点文件	Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

表 4 阐释了可以使用 System.Uri 在代码中指定的各种相对 pack URI。

表 4：代码中的相对 Pack URI

文件	相对 pack URI
资源文件 - 本地程序集	Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative);
子文件夹中的资源文件 - 本地程序集	Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative);
资源文件 - 引用的程序集	Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative);
子文件夹中的资源文件 - 引用的程序集	Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative);
内容文件	Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative);
子文件夹中的内容文件	Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative);

常见 Pack URI 方案

前面几节讨论了如何构造 pack URI 以标识资源文件、内容文件和源站点文件。 在 WPF 中，可以通过各种方式使用这些构造，下面的几节将介绍几种常见用法。

指定当应用程序启动时显示的 UI

StartupUri 指定要在启动 WPF 应用程序时显示的第一个 UI。 对于独立应用程序，UI 可以是一个窗口，如下面的示例所示。

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="MainWindow.xaml" />

独立应用程序和 XAML 浏览器应用程序 (XBAP) 还可以将页面指定为初始 UI，如下面的示例所示。

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="HomePage.xaml" />

如果应用程式是独立应用程序，并且使用 StartupUri 指定了一个页面，WPF 将打开 NavigationWindow 以托管该页面。 对于 XBAP，该页面在宿主浏览器中显示。

导航到页面

下面的示例演示如何导航到页面。

<Page
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  WindowTitle="Page With Hyperlink"
  WindowWidth="250"
  WindowHeight="250">

<Hyperlink NavigateUri="UriOfPageToNavigateTo.xaml">
  Navigate to Another Page
</Hyperlink>

</Page>

有关在 WPF 中导航的各种方式的详细信息，请参阅导航概述。

指定窗口图标

下面的示例演示如何使用 URI 指定窗口的图标。

<Window
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  x:Class="SDKSample.MainWindow"
    Icon="WPFIcon1.ico">
</Window>

有关详细信息，请参阅 Icon。

加载图像、音频和视频文件

WPF 使应用程序可以使用各种媒体类型，所有这些媒体类型都可以用 pack URI 标识和加载，如下面的示例所示。

<MediaElement Stretch="Fill" LoadedBehavior="Play" Source="pack://siteoforigin:,,,/Media/bee.wmv" />

<MediaElement Stretch="Fill" LoadedBehavior="Play" Source="pack://siteoforigin:,,,/Media/ringin.wav" />

<Image Source="Images/Watermark.png" />

有关使用媒体内容的详细信息，请参阅图形和多媒体。

从源站点加载资源字典

资源字典 (ResourceDictionary) 可用于支持应用程序主题。 创建和管理主题的一种方式是将多个主题创建为位于应用程序源站点的资源字典。 这样，在添加和更新主题时将无需重新编译和重新部署应用程序。 可以使用 pack URI 来标识和加载这些资源字典，如下面的示例所示。

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="HomePage.xaml">
  <Application.Resources>
    <ResourceDictionary Source="pack://siteoforigin:,,,/PageTheme.xaml" />
  </Application.Resources>
</Application>

有关 WPF 中主题的概述，请参阅样式设置和模板化。

另请参阅

• WPF 应用程序资源、内容和数据文件