Pack URIs in WPF

In Windows Presentation Foundation (WPF), uniform resource identifiers (URIs) are used to identify and load files in many ways, including the following:

• Specifying the user interface (UI) to show when an application first starts.

• Loading images.

• Navigating to pages.

• Loading non-executable data files.

Furthermore, URIs can be used to identify and load files from a variety of locations, including the following:

• The current assembly.

• A referenced assembly.

• A location relative to an assembly.

• The application's site of origin.

To provide a consistent mechanism for identifying and loading these types of files from these locations, WPF leverages the extensibility of the pack URI scheme. This topic provides an overview of the scheme, covers how to construct pack URIs for a variety of scenarios, discusses absolute and relative URIs and URI resolution, before showing how to use pack URIs from both markup and code.

Este tópico contém as seguintes seções.

• The Pack URI Scheme
• Resource File Pack URIs
• Content File Pack URIs
• Site of Origin Pack URIs
• Page Files
• Absolutos vs.URIs relativos de pacote
• Pack URI Resolution
• Programming with Pack URIs
• Tópicos relacionados

The Pack URI Scheme

O pacote URI esquema é usada pelo Open Packaging Conventions especificação (OPC), que descreve um modelo para organizar e identificar o conteúdo. 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.

Para identificar as partes, a especificação OPC aproveita a extensibilidade do RFC 2396 (Uniform Resource Identifiers (URI): Sintaxe genérica) para definir o pacote URI esquema.

The scheme that is specified by a URI is defined by its prefix; http, ftp, and file are well-known examples. O pacote URI usa o esquema de "pack" como seu esquema e contém dois componentes: autoridade e o caminho. 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.

Para acessar esses tipos de arquivos, WPF suporta dois autoridades: aplicativo: / / / e Pack://sitedeorigem: / / /. 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.

Observação

O componente de autoridade de um pacote de URI é um recurso incorporado URI que aponta para um pacote de acordo com RFC 2396.Além disso, a "/" caractere deve ser substituído com o "," caractere e caracteres reservados como, por exemplo, "%" e "?" deve haver escape.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 File Pack URIs

Arquivos de recurso são configurados como MSBuild Resource itens e são compilados em assemblies. WPFoferece suporte a construção do pacote de URIs que pode ser usado para identificar arquivos de recurso que são compilados no assembly local ou compilados em um assembly referenciado a partir do assembly local.

Local Assembly Resource File

The pack URI for a resource file that is compiled into the local assembly uses the following authority and path:

• Autoridade: aplicativo: / / /.

• Caminho: O nome do arquivo de recursos, incluindo seu caminho, relativo à raiz de pasta de projeto de montagens local.

The following example shows the pack URI for a XAML resource file that is located in the root of the local assembly's project folder.

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

The following example shows the pack URI for a XAML resource file that is located in a subfolder of the local assembly's project folder.

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

Referenced Assembly Resource File

The pack URI for a resource file that is compiled into a referenced assembly uses the following authority and path:

• Autoridade: aplicativo: / / /.

• Caminho: O nome de um arquivo de recurso que é compilado em um assembly referenciado. The path must conform to the following format:

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

  • AssemblyShortName: o nome curto para o assembly referenciado.

  • ;Versão [opcional]: a versão do assembly referenciado que contém o arquivo de recurso. This is used when two or more referenced assemblies with the same short name are loaded.

  • ;PublicKey [opcional]: a chave pública que foi usada para assinar o assembly referenciado. This is used when two or more referenced assemblies with the same short name are loaded.

  • ; componente: Especifica que o assembly que está sendo chamado é referenciado da montagem de local.

  • /Path: o nome do arquivo de recursos, incluindo seu caminho, relativo à raiz da pasta de projeto do assembly referenciado.

The following example shows the pack URI for a XAML resource file that is located in the root of the referenced assembly's project folder.

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

The following example shows the pack URI for a XAML resource file that is located in a subfolder of the referenced assembly's project folder.

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

The following example shows the pack URI for a XAML resource file that is located in the root folder of a referenced, version-specific assembly's project folder.

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

Note that the pack URI syntax for referenced assembly resource files can be used only with the application:/// authority. For example, the following is not supported in WPF.

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

Content File Pack URIs

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

• Autoridade: aplicativo: / / /.

• Caminho: O nome do arquivo de conteúdo, incluindo seu caminho relativo para o local do sistema de arquivo do assembly de executável principal do aplicativo.

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

Observação

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

Site of Origin Pack URIs

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

• Autoridade: Pack://sitedeorigem: / / /.

• Caminho: O nome do site do arquivo de origem, incluindo seu caminho relativo para o local do qual o assembly executável foi iniciado.

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

Page Files

XAMLarquivos que são configurados como MSBuild Page itens são compilados em assemblies da mesma maneira como arquivos de recurso. Conseqüentemente, MSBuild Page itens podem ser identificados usando pack URIs para arquivos de recurso.

Os tipos de XAML arquivos que normalmente são configurados como MSBuild Page itens têm um dos seguintes como seu elemento raiz:

• System.Windows.Window

• System.Windows.Controls.Page

• System.Windows.Navigation.PageFunction<T>

• System.Windows.ResourceDictionary

• System.Windows.Documents.FlowDocument

• System.Windows.Controls.UserControl

Absolutos vs.URIs relativos de pacote

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

Observação

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

Pack URI Resolution

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:

• Arquivos de conteúdo em assemblies referenciados: Não há suporte para esses tipos de arquivo WPF.

• Arquivos incorporados em assemblies referenciados: URIsque identificá-los são exclusivos porque eles incluem o nome do assembly referenciado e o ;component sufixo.

• Site de arquivos de origem: URIsque identificá-los são exclusivos porque eles são os únicos arquivos que podem ser identificados pelo pacote de URIs que contêm a Pack://sitedeorigem: / / / autoridade.

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.

Programming with Pack URIs

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

A pack URI is specified in markup by setting the element of an attribute with the pack URI. For example:

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

Table 1 illustrates the various absolute pack URIs that you can specify in markup.

Tabela 1: URIs de pacote absoluto na marcação

File	Absolute pack URI
Resource file - local assembly	"pack://application:,,,/ResourceFile.xaml"
Resource file in subfolder - local assembly	"pack://application:,,,/Subfolder/ResourceFile.xaml"
Resource file - referenced assembly	"pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml"
Resource file in subfolder of referenced assembly	"pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Resource file in versioned referenced assembly	"pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml"
Content file	"pack://application:,,,/ContentFile.xaml"
Content file in subfolder	"pack://application:,,,/Subfolder/ContentFile.xaml"
Site of origin file	"pack://siteoforigin:,,,/SOOFile.xaml"
Site of origin file in subfolder	"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

Table 2 illustrates the various relative pack URIs that you can specify in markup.

Tabela 2: URIs relativos do pacote na marcação

File	Relative pack URI
Resource file in local assembly	"/ResourceFile.xaml"
Resource file in subfolder of local assembly	"/Subfolder/ResourceFile.xaml"
Resource file in referenced assembly	"/ReferencedAssembly;component/ResourceFile.xaml"
Resource file in subfolder of referenced assembly	"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Content file	"/ContentFile.xaml"
Content file in subfolder	"/Subfolder/ContentFile.xaml"

Using Pack URIs in Code

Você especificar um pacote de URI no código pela instanciação de Uri classe e passando o pacote URI como um parâmetro para o construtor. This is demonstrated in the following example.

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

By default, the Uri class considers pack URIs to be absolute. Consequently, an exception is raised when an instance of the Uri class is created with a relative pack URI.

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

Fortunately, the Uri(String, UriKind) overload of the Uri class constructor accepts a parameter of type UriKind to allow you to specify whether a pack URI is either absolute or relative.

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

You should specify only Absolute or Relative when you are certain that the provided pack URI is one or the other. If you don't know the type of pack URI that is used, such as when a user enters a pack URI at run time, use RelativeOrAbsolute instead.

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

Table 3 illustrates the various relative pack URIs that you can specify in code by using System.Uri.

Tabela 3: Absoluto URIs do pacote no código

File	Absolute pack URI
Resource file - local assembly	Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute);
Resource file in subfolder - local assembly	Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Resource file - referenced assembly	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute);
Resource file in subfolder of referenced assembly	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Resource file in versioned referenced assembly	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute);
Content file	Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute);
Content file in subfolder	Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute);
Site of origin file	Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);
Site of origin file in subfolder	Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

Table 4 illustrates the various relative pack URIs that you can specify in code using System.Uri.

Tabela 4: URIs relativos de pacote no código

File	Relative pack URI
Resource file - local assembly	Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative);
Resource file in subfolder - local assembly	Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative);
Resource file - referenced assembly	Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative);
Resource file in subfolder - referenced assembly	Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative);
Content file	Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative);
Content file in subfolder	Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative);

Common Pack URI Scenarios

The preceding sections have discussed how to construct pack URIs to identify resource, content, and site of origin files. In WPF, these constructions are used in a variety of ways, and the following sections cover several common usages.

Specifying the UI to Show When an Application Starts

StartupUri specifies the first UI to show when a WPF application is launched. For standalone applications, the UI can be a window, as shown in the following example.

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

Standalone applications and XAML browser applications (XBAPs) can also specify a page as the initial UI, as shown in the following example.

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

If the application is a standalone application and a page is specified with StartupUri, WPF opens a NavigationWindow to host the page. For XBAPs, the page is shown in the host browser.

Navigating to a Page

The following example shows how to navigate to a page.

<Page
  xmlns="https://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>

For more information on the various ways to navigate in WPF, see Visão geral de navegação.

Specifying a Window Icon

The following example shows how to use a URI to specify a window's icon.

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

For more information, see Icon.

Loading Image, Audio, and Video Files

WPF allows applications to use a wide variety of media types, all of which can be identified and loaded with pack URIs, as shown in the following examples.

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

For more information on working with media content, see Graphics and Multimedia.

Loading a Resource Dictionary from the Site of Origin

Resource dictionaries (ResourceDictionary) can be used to support application themes. One way to create and manage themes is to create multiple themes as resource dictionaries that are located at an application's site of origin. This allows themes to be added and updated without recompiling and redeploying an application. These resource dictionaries can be identified and loaded using pack URIs, which is shown in the following example.

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

For an overview of themes in WPF, see Styling and Templating.

Consulte também

Conceitos

Recursos, conteúdo e arquivos de dados de aplicativos WPF