Empacotar URIs no WPF

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

• Especificando a interface do usuário (UI) para mostrar quando um aplicativo é iniciado pela primeira vez.

• Carregando imagens.

• Navegação para as 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 atual assembleia.

• Uma montagem referenciada.

• Um local relativo a uma montagem.

• O local de origem do aplicativo.

Para fornecer um mecanismo consistente para identificar e carregar esses tipos de ficheiros a partir destes locais, o WPF tira partido da extensibilidade do esquema de URI do 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 absolutos e relativos e a resolução de URI, antes de mostrar como usar URIs de pacote a partir do código de marcação e do código.

O esquema de URI do pacote

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

Para identificar peças, a especificação OPC aproveita a extensibilidade do RFC 2396 (URI (Uniform Resource Identifiers): Generic Syntax) para definir o esquema de URI do pacote.

O esquema especificado por um URI é definido por seu prefixo; HTTP, FTP e File são exemplos bem conhecidos. O esquema de URI do pacote usa "pack" como seu esquema e contém dois componentes: autoridade e caminho. A seguir está o formato de um URI de pacote.

pack://autoridade/caminho

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

Este conceito é ilustrado pela seguinte figura:

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

• Arquivos de recursos que são compilados na assemblagem local.

• Arquivos de recursos que são compilados em uma assembly referenciada.

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

• Arquivos de conteúdo.

• Site de arquivos de origem.

Para acessar esses tipos de arquivos, o WPF suporta duas autoridades: application:/// e siteoforigin:///. A autoridade application:/// identifica os arquivos de dados do aplicativo que são conhecidos em tempo de compilação, incluindo arquivos de recursos e conteúdo. A autoridade siteoforigin:/// identifica os ficheiros do sítio de origem. O âmbito de aplicação de cada autoridade é apresentado na figura seguinte.

Diagrama do Pack URI

Observação

O componente de autoridade de um URI de pacote é um URI incorporado que aponta para um pacote e deve estar em conformidade com a RFC 2396. Além disso, o caractere "/" deve ser substituído pelo caractere "," e os caracteres reservados, como "%" e "?", devem ser transformados em caracteres de escape. 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.

Pacote de Ficheiros de Recursos URIs

Os arquivos de recursos são configurados como itens de Resource do MSBuild e são compilados em assemblies. O WPF suporta a construção de URIs de pacote que podem ser usados para identificar ficheiros de recursos que são compilados na assembleia local ou compilados numa assembleia referenciada a partir da assembleia local.

Arquivo de recurso de assembly local

O URI do pacote para um arquivo de recurso que é compilado no assembly local usa a seguinte autoridade e caminho:

• Autoridade: application:///.

• Path: O nome do ficheiro de recurso, incluindo o seu caminho, relativo à pasta raiz do projeto de 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 que está localizado em uma subpasta da pasta de projeto do assembly local.

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

Arquivo de recursos referenciado do assembly

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

• Autoridade: application:///.

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

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

  • AssemblyShortName: o nome abreviado para o assembly referenciado.

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

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

  • ; Componente: Especifica que a montagem que está a ser referida é referenciada a partir da montagem local.

  • /Path: o nome do ficheiro de recurso, incluindo o seu caminho, relativo à 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 que está 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 do pacote para um arquivo de recurso XAML localizado na pasta raiz de uma pasta de projeto de assembly referenciada e específica da versão.

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

Observe que a sintaxe URI do pacote para arquivos de recurso de assembly referenciados pode ser usada somente com a autoridade application:///. Por exemplo, o seguinte não é suportado no WPF.

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

Pacote de Ficheiros de Conteúdo URIs

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

• Autoridade: application:///.

• Path: O nome do arquivo de conteúdo, incluindo seu caminho relativo ao local do sistema de arquivos do assembly executável principal do aplicativo.

O exemplo a seguir mostra o URI do pacote para um ficheiro de conteúdo XAML, localizado na mesma pasta que a assemblagem 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

Observação

Não é possível navegar nos arquivos de conteúdo HTML. O esquema de URI suporta apenas a navegação para arquivos HTML localizados no site de origem.

URI do Pacote do Site de Origem

O URI do pacote para um arquivo de site de origem usa a seguinte autoridade e caminho:

• Autoridade: siteoforigin:///.

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

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

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

O exemplo a seguir mostra o URI do pacote para um arquivo de origem do site XAML, armazenado na subpasta relativa ao local a partir do qual o assembly executável do aplicativo é iniciado.

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

Arquivos de página

Os arquivos XAML configurados como itens de Page MSBuild são compilados em assemblies da mesma forma que os arquivos de recurso. Consequentemente, os itens Page do MSBuild podem ser identificados através de URIs de pacote para ficheiros de recursos.

Os tipos de arquivos XAML que são comumente configurados como itens dePage MSBuild 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

URIs de pacote absolutas vs. relativas

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 seguinte URI de pacote absoluto para um arquivo de recurso na assemblagem local.

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

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

/ResourceFile.xaml

Observação

Como os arquivos de site de origem não estão associados a assemblies, eles só podem ser referidos com URIs de pacote absoluto.

Por padrão, um URI de pacote relativo é considerado relativo ao local da marcação ou código que contém a referência. No entanto, se uma barra invertida à esquerda for usada, a referência de URI do pacote relativo será considerada relativa à raiz do aplicativo. Por exemplo, considere a seguinte estrutura de projeto.

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

Se Page1.xaml contiver um URI que faça referência a Root\SubFolder\Page2.xaml, a referência poderá usar o seguinte URI relativo do pacote.

Page2.xaml

Se Page1.xaml contiver um URI que faça referência a Root\Page2.xaml, a referência poderá usar o seguinte URI relativo de pacote.

/Page2.xaml

Resolução de URI do pacote

O formato dos URIs do pacote possibilita que os URIs do pacote para diferentes tipos de arquivos tenham a mesma aparência. Por exemplo, considere o seguinte URI de pacote absoluto.

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 seguinte URI relativo.

/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 em busca de um atributo AssemblyAssociatedContentFileAttribute que corresponda ao URI do pacote.

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

3. Se o atributo AssemblyAssociatedContentFileAttribute não for encontrado, investigue os arquivos de recursos definidos que são 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 refere 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: estes tipos de ficheiros não são suportados pelo WPF.

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

• Arquivos de site de origem: os URIs que os identificam são exclusivos porque são os únicos arquivos que podem ser identificados por URIs de pacote 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 que é reconfigurado para ser um arquivo de conteúdo, o URI do pacote para o recurso permanece o mesmo, assim como o código que usa o URI do pacote.

Programação com URIs de pacote

Muitas classes 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, em seguida, mostra exemplos de cenários comuns.

Utilização de URIs de pacote em markup

Um URI de pacote é especificado na marcação definindo o elemento de um atributo com o URI do pacote. Por exemplo:

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

A Tabela 1 ilustra os vários URIs absolutos de pacote que pode especificar na linguagem de marcação.

Tabela 1: URIs absolutos do pacote na marcação

Ficheiro	URI absoluto do pacote
Arquivo de recurso - montagem local	"pack://application:,,,/ResourceFile.xaml"
Arquivo de recurso na subpasta - assemblagem local	"pack://application:,,,/Subfolder/ResourceFile.xaml"
Arquivo de recurso - assemblagem referenciada	"pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml"
Arquivo de recurso na subpasta do assembly referenciado	"pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Ficheiro de recursos num assembly referenciado com 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"
Ficheiro do local de origem	"pack://siteoforigin:,,,/SOOFile.xaml"
Arquivo do site de origem na subpasta	"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

A Tabela 2 ilustra os vários URIs de pacotes relativos que você pode especificar na marcação.

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

Ficheiro	URI relativo do pacote
Arquivo de recursos no assembly local	"/ResourceFile.xaml"
Arquivo de recurso na subpasta da assemblagem local	"/Subfolder/ResourceFile.xaml"
Arquivo de recurso no assembly referenciado	"/ReferencedAssembly;component/ResourceFile.xaml"
Arquivo de recurso na subpasta da assemblagem referenciada	"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Arquivo de conteúdo	"/ContentFile.xaml"
Arquivo de conteúdo na subpasta	"/Subfolder/ContentFile.xaml"

Usando URIs de pacote no código

Você especifica 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 URIs de pacote como absolutos. Consequentemente, uma exceção é gerada quando uma instância da classe Uri é criada com um URI de pacote relativo.

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

Felizmente, a sobrecarga de 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 de 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 os vários URIs de pacotes relativos que você pode especificar no código usando System.Uri.

Tabela 3: URIs absolutos do pacote no código

Ficheiro	URI absoluto do pacote
Arquivo de recurso - assembly local	Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso na pasta secundária - montagem local	Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso - assemblagem referenciada	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso no subdiretório da assemblagem referenciada	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Arquivo de recurso no assembly com versão referenciada	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);
Ficheiro de origem	Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);
Arquivo do site de origem na subpasta	Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

A Tabela 4 ilustra os vários URIs relativos do pacote que você pode especificar no código usando System.Uri.

Tabela 4: URIs relativos do pacote no código

Ficheiro	URI relativo do pacote
Arquivo de recurso - montagem local	Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative);
Arquivo de recurso na subpasta - assemblagem 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 na subpasta - assemblagem referenciada	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 de URI do Common 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 cobrem vários usos comuns.

Especificando a interface do usuário a ser exibida 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 aplicativos de navegador XAML (XBAPs) 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á um NavigationWindow para hospedar a página. Para XBAPs, a página é mostrada no navegador host.

Navegar 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 da 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 apoiar temas de aplicação. Uma maneira de criar e gerenciar temas é criar vários temas como dicionários de recursos que estão 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, 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 Styling and Templating.

Ver também

• Recursos de Aplicação WPF, Conteúdo e Ficheiros de Dados