The pack URI scheme is used by the Open Packaging Conventions (OPC) specification, which describes a model for organizing and identifying content. The key elements of this model are packages and parts, where a package is a logical container for one or more logical parts. The following figure illustrates this concept.

To identify parts, the OPC specification leverages the extensibility of RFC 2396 (Uniform Resource Identifiers (URI): Generic Syntax) to define the pack URI scheme.

The scheme that is specified by a URI is defined by its prefix; http, ftp, and file are well-known examples. The pack URI scheme uses "pack" as its scheme, and contains two components: authority and path. The following is the format for a pack URI.

pack://authority/path

The authority specifies the type of package that a part is contained by, while the path specifies the location of a part within a package.

This concept is illustrated by the following figure:

Packages and parts are analogous to applications and files, where an application (package) can include one or more files (parts), including:

• Resource files that are compiled into the local assembly.

• Resource files that are compiled into a referenced assembly.

• Resource files that are compiled into a referencing assembly.

• Content files.

• Site of origin files.

To access these types of files, WPF supports two authorities: application:/// and siteoforigin:///. The application:/// authority identifies application data files that are known at compile time, including resource and content files. The siteoforigin:/// authority identifies site of origin files. The scope of each authority is shown in the following figure.

Note:
The authority component of a pack URI is an embedded URI that points to a package and must conform to RFC 2396. Additionally, the "/" character must be replaced with the "," character, and reserved characters such as "%" and "?" must be escaped. See the OPC for details.

The following sections explain how to construct pack URIs using these two authorities in conjunction with the appropriate paths for identifying resource, content, and site of origin files.

Resource files are configured as MSBuild Resource items and are compiled into assemblies. WPF supports the construction of pack URIs that can be used to identify resource files that are either compiled into the local assembly or compiled into an assembly that is referenced from the local assembly.

Local Assembly Resource File

Referenced Assembly Resource File

The pack URI for a content file uses the following authority and path:

• Authority: application:///.

• Path: The name of the content file, including its path relative to the file system location of the application's main executable assembly.

The following example shows the pack URI for a XAML content file, located in the same folder as the executable assembly.

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

The following example shows the pack URI for a XAML content file, located in a subfolder that is relative to the application's executable assembly.

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

Note:
HTML content files cannot be navigated to. The URI scheme only supports navigation to HTML files that are located at the site of origin.

The pack URI for a site of origin file uses the following authority and path:

• Authority: siteoforigin:///.

• Path: The name of the site of origin file, including its path relative to the location from which the executable assembly was launched.

The following example shows the pack URI for a XAML site of origin file, stored in the location from which the executable assembly is launched.

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

The following example shows the pack URI for a XAML site of origin file, stored in subfolder that is relative to the location from which the application's executable assembly is launched.

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

XAML files that are configured as MSBuild Page items are compiled into assemblies in the same way as resource files. Consequently, MSBuild Page items can be identified using pack URIs for resource files.

The types of XAML files that are commonly configured as MSBuild Page items have one of the following as their root element:

• System.Windows..::.Window

• System.Windows.Controls..::.Page

• System.Windows.Navigation..::.PageFunction<(Of <(T>)>)

• System.Windows..::.ResourceDictionary

• System.Windows.Documents..::.FlowDocument

• System.Windows.Controls..::.UserControl

A fully qualified pack URI includes the scheme, the authority, and the path, and it is considered an absolute pack URI. As a simplification for developers, XAML elements typically allow you to set appropriate attributes with a relative pack URI, which includes only the path.

For example, consider the following absolute pack URI for a resource file in the local assembly.

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

The relative pack URI that refers to this resource file would be the following.

/ResourceFile.xaml

Note:
Because site of origin files are not associated with assemblies, they can only be referred to with absolute pack URIs.

By default, a relative pack URI is considered relative to the location of the markup or code that contains the reference. If a leading backslash is used, however, the relative pack URI reference is then considered relative to the root of the application. For example, consider the following project structure.

App.xaml

Page2.xaml

\SubFolder

  + Page1.xaml

  + Page2.xaml

If Page1.xaml contains a URI that references Root\SubFolder\Page2.xaml, the reference can use the following relative pack URI.

Page2.xaml

If Page1.xaml contains a URI that references Root\Page2.xaml, the reference can use the following relative pack URI.

/Page2.xaml

The format of pack URIs makes it is possible for pack URIs for different types of files to look the same. For example, consider the following absolute pack URI.

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

This absolute pack URI could refer to either a resource file in the local assembly or a content file. The same is true for the following relative URI.

/ResourceOrContentFile.xaml

In order to determine the type of file that a pack URI refers to, WPF resolves URIs for resource files in local assemblies and content files by using the following heuristics:

1. Probe the assembly metadata for an AssemblyAssociatedContentFileAttribute attribute that matches the pack URI.

2. If the AssemblyAssociatedContentFileAttribute attribute is found, the path of the pack URI refers to a content file.

3. If the AssemblyAssociatedContentFileAttribute attribute is not found, probe the set resource files that are compiled into the local assembly.

4. If a resource file that matches the path of the pack URI is found, the path of the pack URI refers to a resource file.

5. If the resource is not found, the internally created Uri is invalid.

URI resolution does not apply for URIs that refer to the following:

• Content files in referenced assemblies: these file types are not supported by WPF.

• Embedded files in referenced assemblies: URIs that identify them are unique because they include both the name of the referenced assembly and the ;component suffix.

• Site of origin files: URIs that identify them are unique because they are the only files that can be identified by pack URIs that contain the siteoforigin:/// authority.

One simplification that pack URI resolution allows is for code to be somewhat independent of the locations of resource and content files. For example, if you have a resource file in the local assembly that is reconfigured to be a content file, the pack URI for the resource remains the same, as does the code that uses the pack URI.

Many WPF classes implement properties that can be set with pack URIs, including:

• Application..::.StartupUri

• Frame..::.Source

• NavigationWindow..::.Source

• Hyperlink..::.NavigateUri

• Window..::.Icon

• Image..::.Source

These properties can be set from both markup and code. This section demonstrates the basic constructions for both and then shows examples of common scenarios.

Using Pack URIs in Markup

Using Pack URIs in Code

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

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

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

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

Common Pack URI Scenarios

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

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

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

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

<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" />

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

Concepts