URIs "pack://" no WPF

No Windows Presentation Foundation (WPF), URIs (uniform resource identifiers) são usados para identificar e carregar arquivos de várias maneiras, incluindo o seguinte:

• Especificando a interface do usuário (UI) para exibir quando um aplicativo inicia pela primeira vez.

• Carregando imagens.

• Navegando entre páginas.

• Carregando arquivos de dados não executáveis.

Além disso, os URIs podem ser usados para identificar e carregar arquivos de uma variedade de locais, incluindo o seguinte:

• A assembleia atual.

• Um assembly referenciado.

• Um local relativo a um assembly.

• O site de origem do aplicativo.

Para fornecer um mecanismo consistente para identificar e carregar esses tipos de arquivos desses locais, o WPF aproveita a extensibilidade do esquema de URI "pack://". Este tópico fornece uma visão geral do esquema, aborda como construir URIs de pacote para uma variedade de cenários, discute URIs absolutas e relativas e a resolução de URIs, antes de mostrar como usar URIs de pacote tanto de marcação quanto de código.

O esquema de URI do pacote

O esquema de URI do pacote é usado pela especificação OPC (Open Packaging Conventions), que descreve um modelo para organizar e identificar conteúdo. Os principais elementos desse modelo são pacotes e partes, em que um pacote é um contêiner lógico para uma ou mais partes lógicas . A figura a seguir ilustra esse conceito.

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

O esquema especificado por um URI é definido por seu prefixo; http, ftp e arquivo são exemplos bem conhecidos. O esquema de URI do pacote usa "pack" como seu esquema e contém dois componentes: autoridade e caminho. Veja a seguir o formato de um URI de pacote.

pack://autoridade/caminho

A autoridade especifica o tipo de pacote pelo qual uma parte está contida, enquanto o caminho especifica o local de uma parte dentro de um pacote.

Esse conceito é ilustrado pela seguinte figura:

Pacotes e partes são análogos a aplicativos e arquivos, em que um aplicativo (pacote) pode incluir um ou mais arquivos (partes), incluindo:

• Arquivos de recursos que são compilados no assembly local.

• Arquivos de recursos que são compilados em um assembly referenciado.

• Arquivos de recursos que são compilados em um assembly de referência.

• Arquivos de conteúdo.

• Arquivos de site de origem.

Para acessar esses tipos de arquivos, o WPF dá suporte a duas autoridades: application:/// e siteoforigin:///. A autoridade application:/// identifica arquivos de dados de aplicativo que são conhecidos no tempo de compilação, incluindo arquivos de recurso e conteúdo. A autoridade siteoforigin:/// identifica arquivos de site de origem. O escopo de cada autoridade é mostrado na figura a seguir.

diagrama de URI do Pacote

Nota

O componente de autoridade de um URI de pacote é um URI inserido que aponta para um pacote e deve estar em conformidade com o RFC 2396. Além disso, o caractere “/” precisa ser substituído pelo caractere “,”; caracteres reservados como “%” e “?” precisam ser escapados. Consulte o OPC para obter detalhes.

As seções a seguir explicam como construir URIs de pacote usando essas duas autoridades em conjunto com os caminhos apropriados para identificar arquivos de recurso, conteúdo e site de origem.

URIs "pack://" de arquivo de recurso

Os arquivos de recurso são configurados como itens MSBuild Resource e são compilados em assemblies. O WPF dá suporte à construção de URIs "pack://" que podem ser usados para identificar arquivos de recurso compilados no assembly local ou compilados em um assembly referenciado do assembly local.

Arquivo de recursos de montagem local

O URI "pack://" para um arquivo de recurso que é compilado no assembly local utiliza a seguinte autoridade e caminho:

• Autoridade: application:///.

• Caminho: o nome do arquivo de recurso, incluindo seu caminho, em relação à raiz da pasta de projeto do assembly local.

O exemplo a seguir mostra o URI do pacote para um arquivo de recurso XAML localizado na raiz da pasta de projeto do assembly local.

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

O exemplo a seguir mostra o URI do pacote para um arquivo de recurso XAML localizado em uma subpasta da pasta de projeto do assembly local.

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

Arquivo de recurso de assembly referenciado

O URI do pacote para um arquivo de recurso compilado em um assembly referenciado usa a seguinte autoridade e caminho:

• Autoridade: application:///.

• Caminho: o nome de um arquivo de recurso compilado em um assembly referenciado. O caminho deve estar em conformidade com o seguinte formato:

  AssemblyShortName{;Versão]{;PublicKey];component/Caminho

  • AssemblyShortName: o nome curto do assembly referenciado.

  • ; Versão [opcional]: a versão do assembly referenciado que contém o arquivo de recurso. É usada quando são carregados dois ou mais assemblies referenciados com o mesmo nome curto.

  • ;PublicKey [opcional]: a chave pública que foi usada para assinar o assembly referenciado. Isso é utilizado quando dois ou mais conjuntos referenciados com o mesmo nome curto são carregados.

  • ; componente: especifica que a montagem a ser referenciada é proveniente da montagem local.

  • /Path: o nome do arquivo de recurso, incluindo seu caminho em relação à raiz da pasta de projeto do assembly referenciado.

O exemplo a seguir mostra o URI do pacote para um arquivo de recurso XAML localizado na raiz da pasta de projeto do assembly referenciado.

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

O exemplo a seguir mostra o URI do pacote para um arquivo de recurso XAML localizado em uma subpasta da pasta de projeto do assembly referenciado.

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

O exemplo a seguir mostra o URI "pack://" para um arquivo de recurso XAML que está localizado na pasta raiz de uma pasta de projeto do assembly referenciado específico da versão.

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

Observe que a sintaxe de URI "pack://" para arquivos de recurso de assembly referenciados só pode ser usada com a autoridade de application:///. Por exemplo, não há suporte para o seguinte no WPF.

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

URIs do Pacote de Arquivos de Conteúdo

O URI do pacote para um arquivo de conteúdo usa a seguinte autoridade e caminho:

• Autoridade: application:///.

• Caminho: o nome do arquivo de conteúdo, incluindo o caminho em relação ao local do sistema de arquivos do principal assembly executável do aplicativo.

O exemplo a seguir mostra o URI "pack://" para um arquivo de conteúdo XAML, localizado na mesma pasta que o assembly executável.

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

O exemplo a seguir mostra o URI do pacote para um arquivo de conteúdo XAML, localizado em uma subpasta relativa ao assembly executável do aplicativo.

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

Nota

Não é possível navegar até os arquivos de conteúdo HTML. O esquema de URI dá suporte apenas à navegação para arquivos HTML localizados no site de origem.

URIs "pack://" de site de origem

O URI "pack://" para um arquivo de site de origem usa a seguinte autoridade e caminho:

• Authority: siteoforigin:///.

• Caminho: o nome do arquivo de site de origem, incluindo o caminho em relação ao local a partir do qual o assembly executável foi iniciado.

O exemplo a seguir mostra o URI "pack://" para um arquivo de origem do site XAML, que está armazenado no local a partir do qual o assembly executável é iniciado.

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

O exemplo a seguir mostra o URI "pack://" para um arquivo XAML de origem, armazenado em uma subpasta relativa ao local de onde o assembly executável do aplicativo é iniciado.

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

Arquivos de paginação

Os arquivos XAML configurados como MSBuild Page itens são compilados em assemblies da mesma forma que os arquivos de recurso. Como resultado, os itens do MSBuild Page podem ser identificados usando URIs de pacote para arquivos de recurso.

Os tipos de arquivos XAML geralmente configurados como MSBuildPage itens têm um dos seguintes como 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

URIs "pack://" absolutos vs. relativos

Um URI de pacote totalmente qualificado inclui o esquema, a autoridade e o caminho, e é considerado um URI de pacote absoluto. Como uma simplificação para desenvolvedores, os elementos XAML normalmente permitem que você defina atributos apropriados com um URI de pacote relativo, que inclui apenas o caminho.

Por exemplo, considere o URI "pack://" absoluto a seguir para um arquivo de recurso no assembly local.

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

O URI do pacote relativo que se refere a esse arquivo de recurso seria o seguinte.

/ResourceFile.xaml

Nota

Como os arquivos de site de origem não estão associados a assemblies, eles só podem ser referenciados com URIs "pack://" absolutos.

Por padrão, um URI "pack://" relativo é considerado relativo à localização da marcação ou código que contém a referência. No entanto, se uma barra invertida for usada, a referência de URI "pack://" relativo será então considerada em relação à raiz do aplicativo. Por exemplo, considere a estrutura de projeto a seguir.

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

Se Page1.xaml contiver um URI que referencie Raiz\SubFolder\Page2.xaml, a referência poderá usar o URI "pack://" relativo a seguir.

Page2.xaml

Se Page1.xaml contiver um URI que referencie Raiz\Page2.xaml, a referência poderá usar o URI "pack://" relativo a seguir.

/Page2.xaml

Resolução de URI "pack://"

O formato de URIs do pacote possibilita que URIs de pacote para diferentes tipos de arquivos sejam iguais. Por exemplo, considere o URI do pacote absoluto a seguir.

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

Esse URI de pacote absoluto pode se referir a um arquivo de recurso no assembly local ou a um arquivo de conteúdo. O mesmo é verdadeiro para o URI relativo a seguir.

/ResourceOrContentFile.xaml

Para determinar o tipo de arquivo ao qual um URI de pacote se refere, o WPF resolve URIs para arquivos de recursos em assemblies locais e arquivos de conteúdo usando a seguinte heurística:

1. Investigue os metadados do assembly para um atributo AssemblyAssociatedContentFileAttribute que corresponda ao URI do pacote.

2. Se o atributo AssemblyAssociatedContentFileAttribute for encontrado, o caminho do URI do pacote se referirá a um arquivo de conteúdo.

3. Se o atributo AssemblyAssociatedContentFileAttribute não for encontrado, investigue os arquivos de recurso definidos compilados no assembly local.

4. Se um arquivo de recurso que corresponde ao caminho do URI do pacote for encontrado, o caminho do URI do pacote se referirá a um arquivo de recurso.

5. Se o recurso não for encontrado, o Uri criado internamente será inválido.

A resolução de URI não se aplica a URIs que se referem ao seguinte:

• Arquivos de conteúdo em assemblies referenciados: esses tipos de arquivo não são suportados pelo WPF.

• Arquivos incorporados em assemblies referenciados: os URIs que os identificam são exclusivos porque incluem tanto o nome do assembly referenciado quanto o sufixo ;component.

• Arquivos de origem do site: URIs que os identificam são únicos porque são os únicos arquivos que podem ser identificados por URIs "pack://" que contêm a autoridade siteoforigin:///.

Uma simplificação que a resolução de URI do pacote permite é que o código seja um pouco independente dos locais dos arquivos de recursos e conteúdo. Por exemplo, se você tiver um arquivo de recurso no assembly local reconfigurado para ser um arquivo de conteúdo, o URI do pacote para o recurso permanecerá o mesmo, assim como o código que usa o URI do pacote.

Programando com URIs "pack://"

Muitas classes do WPF implementam propriedades que podem ser definidas com URIs de pacote, incluindo:

• Application.StartupUri

• Frame.Source

• NavigationWindow.Source

• Hyperlink.NavigateUri

• Window.Icon

• Image.Source

Essas propriedades podem ser definidas a partir de marcação e código. Esta seção demonstra as construções básicas para ambos e mostra exemplos de cenários comuns.

Utilizando URIs "pack://" em marcação

Um URI "pack://" é especificado na marcação definindo o elemento de um atributo com o URI "pack://". Por exemplo:

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

A Tabela 1 ilustra as diferentes URIs absolutas do pacote que você pode especificar na marcação.

Tabela 1: URIs "pack://" absolutos em marcação

Arquivo	URI "pack://" absoluto
Arquivo de recurso – assembly local	"pack://application:,,,/ResourceFile.xaml"
Arquivo de recurso em subpasta - assembly local	"pack://application:,,,/Subfolder/ResourceFile.xaml"
Arquivo de recurso – assembly referenciado	"pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml"
Arquivo de recurso em subpasta de assembly referenciado	"pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Arquivo de recurso em assembly referenciado com controle de versão	"pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml"
Arquivo de conteúdo	"pack://application:,,,/ContentFile.xaml"
Arquivo de conteúdo na subpasta	"pack://application:,,,/Subfolder/ContentFile.xaml"
Arquivo de site de origem	"pack://siteoforigin:,,,/SOOFile.xaml"
Arquivo de site de origem em subpasta	"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

A Tabela 2 ilustra os diversos URIs "pack://" relativos que você pode especificar na linguagem de marcação.

Tabela 2: URIs "pack://" relativos em marcação

Arquivo	URI "pack://" relativo
Arquivo de recurso em assembly local	"/ResourceFile.xaml"
Arquivo de recursos em uma subpasta do assembly local	"/Subfolder/ResourceFile.xaml"
Arquivo de recurso em assembly referenciado	"/ReferencedAssembly;component/ResourceFile.xaml"
Arquivo de recurso em subpasta de assembly referenciado	"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Arquivo de conteúdo	"/ContentFile.xaml"
Arquivo de conteúdo na subpasta	"/Subfolder/ContentFile.xaml"

Utilizando URIs "pack://" em código

Especifique um URI de pacote no código instanciando a classe Uri e passando o URI do pacote como um parâmetro para o construtor. Isso é demonstrado no exemplo a seguir.

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

Por padrão, a classe Uri considera os URIs do pacote absolutos. Consequentemente, uma exceção é gerada quando uma instância da classe Uri é criada com um URI "pack://" relativo.

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

Felizmente, a sobrecarga Uri(String, UriKind) do construtor de classe Uri aceita um parâmetro do tipo UriKind para permitir que você especifique se um URI de pacote é absoluto ou relativo.

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

Você deve especificar apenas Absolute ou Relative quando tiver certeza de que o URI do pacote fornecido é um ou outro. Se você não souber o tipo de URI do pacote usado, como quando um usuário insere um URI de pacote em tempo de execução, use RelativeOrAbsolute em vez disso.

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

A Tabela 3 ilustra as várias URIs de pacote relativo que você pode especificar no código usando System.Uri.

Tabela 3: URIs "pack://" absolutos em código

Arquivo	URI "pack://" absoluto
Arquivo de recurso – assembly local	Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso em subpasta - assembly local	Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso – assembly referenciado	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso na subpasta do conjunto referenciado	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso em assembly referenciado com controle de versão	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute);
Arquivo de conteúdo	Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute);
Arquivo de conteúdo na subpasta	Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute);
Arquivo de site de origem	Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);
Arquivo de site de origem em subpasta	Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

A Tabela 4 ilustra os diferentes URIs de pacote relativo que você pode especificar no código usando System.Uri.

Tabela 4: URIs "pack://" relativos em código

Arquivo	URI "pack://" relativo
Arquivo de recurso – assembly local	Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative);
Arquivo de recurso em subpasta - assembly local	Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative);
Arquivo de recurso - assembly referenciado	Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative);
Arquivo de recurso em subpasta – assembly referenciado	Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative);
Arquivo de conteúdo	Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative);
Arquivo de conteúdo na subpasta	Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative);

Cenários comuns de URI "pack://"

As seções anteriores discutiram como construir URIs de pacote para identificar arquivos de recurso, conteúdo e site de origem. No WPF, essas construções são usadas de várias maneiras e as seções a seguir abrangem vários usos comuns.

Especificando a interface do usuário para mostrar quando um aplicativo é iniciado

StartupUri especifica a primeira interface do usuário a ser exibida quando um aplicativo WPF é iniciado. Para aplicativos autônomos, a interface do usuário pode ser uma janela, conforme mostrado no exemplo a seguir.

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

Aplicativos autônomos e XBAPs (aplicativos de navegador XAML) também podem especificar uma página como a interface do usuário inicial, conforme mostrado no exemplo a seguir.

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

Se o aplicativo for um aplicativo autônomo e uma página for especificada com StartupUri, o WPF abrirá uma NavigationWindow para hospedar a página. Para XBAPs, a página é mostrada no navegador do host.

Navegação para uma página

O exemplo a seguir mostra como navegar até uma página.

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

Para obter mais informações sobre as várias maneiras de navegar no WPF, consulte Visão geral de navegação.

Especificando um ícone de janela

O exemplo a seguir mostra como usar um URI para especificar o ícone de uma janela.

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

Para obter mais informações, consulte Icon.

Carregando arquivos de imagem, áudio e vídeo

O WPF permite que os aplicativos usem uma ampla variedade de tipos de mídia, todos os quais podem ser identificados e carregados com URIs de pacote, conforme mostrado nos exemplos a seguir.

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

Para obter mais informações sobre como trabalhar com conteúdo de mídia, consulte Graphics and Multimedia.

Carregando um dicionário de recursos do site de origem

Dicionários de recursos (ResourceDictionary) podem ser usados para dar suporte a temas do aplicativo. Uma maneira de criar e gerenciar temas é criar vários temas como dicionários de recursos localizados no site de origem de um aplicativo. Isso permite que os temas sejam adicionados e atualizados sem recompilar e reimplantar um aplicativo. Esses dicionários de recursos podem ser identificados e carregados usando URIs de pacote, o que é mostrado no exemplo a seguir.

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

Para obter uma visão geral dos temas no WPF, consulte Estilo e Modelagem.

Consulte também

• Arquivos de recursos, de conteúdo e de dados de aplicativos do WPF