URIs de Pacotes no Windows Presentation Foundation

  • Artigo

No Windows Presentation Foundation (WPF), uniform resource identifiers (URIs) são utilizadas para identificar e carregar arquivos de várias formas, incluindo as seguintes:

  • Especificar o interface do usuário (UI) a ser exibida quando uma aplicação inicia.

  • Carregar imagens.

  • Navegar entre páginas.

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

Além disso, URIs podem ser utilizados para identificar e carregar arquivos a partir de uma variedade de locais, incluindo os seguintes:

  • O assembly atual.

  • Assembly referenciado.

  • Um local relativo a um assembly.

  • O local de origem da aplicação.

Para proporcionar um mecanismo consistente para identificar e carregar esses tipos de arquivos a partir desses locais, o WPF alavanca a extensibilidade do pack URI scheme. Este tópico fornece uma visão geral do esquema, aborda a forma de construir URIs de pacote para uma variedade de cenários, discute URIs absolutos e relativos e resolução de URI, antes de mostrar como utilizar URIs de pacotes a partir de marcação e código.

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

  • O Esquema de URI de Pacotes
  • URIs de Pacote de Arquivos de Recurso
  • URIs de Pacote de Arquivo de Conteúdo
  • URIs de Pacote do Local de Origem
  • Arquivos de Página
  • Absolutos vs.URIs relativos de empacotar
  • Resolução de URI de Pacote
  • Programação com as URIs de Pacote
  • Tópicos relacionados

O Esquema de URI de Pacotes

O empacotar de URI esquema é usada pela em em aberto Packaging Conventions Especificação (OPC), que descreve um modelo para organizar e identificar conteúdo. Os elementos-chave desse modelo são pacotes e partes, onde um pacote é um contêiner lógico para uma ou mais partes lógicas. A imagem seguinte ilustra este conceito.

Diagrama de partes e pacote

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

O esquema especificado pela URIé definido por seu prefixo; http, ftp, e file são exemplos bem conhecidos. O empacotar de URIesquema usa "empacotar" sistema autônomo seu esquema e contém dois componentes: autoridade e o caminho. Segue o formato de um URI de pacote.

pack://autoridade/caminho

A autoridade especifica o tipo de pacote que contém a parte, enquanto o caminho especifica o localização de uma parte no pacote.

A imagem seguinte ilustra este conceito.

Relação entre pacote, autoridade e caminho

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

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

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

  • Arquivos de recurso que são compilados em um assembly que referencia.

  • Arquivos de conteúdo.

  • Arquivos de local de origem.

Para acessar esses tipos de arquivos, WPF oferece suporte a duas autoridades: aplicativo: / / / e sitedeorigem: / / /. A autoridade application:/// identifica arquivos de dados do aplicativo conhecidos em tempo de compilação, incluindo arquivos de recurso e conteúdo. A autoridade siteoforigin:/// identifica arquivos de local de origem. O escopo de cada autoridade é exibido na figura a seguir.

Diagrama de URI de pacote

ObservaçãoObservação:

O componente de autoridade de um empacotar URI é um incorporado URI que aponta para um pacote e deve estar de acordo com RFC 2396. Além disso, o caractere "/" deve ser substituído com o caractere "," e reservado caracteres sistema autônomo "%" e "?" devem vir seguidas pelo caractere de escape. Veja o OPC para detalhes.

As seções seguintes explicam como construir URIs de pacote utilizando estas duas autoridades em conjunto com os caminhos apropriados para identificação de arquivos de recurso, conteúdo e local de origem.

URIs de Pacote de Arquivos de Recurso

Resource files are configured as MSBuild Resource items and are compiled into assemblies. WPF oferece suporte a construção de empacotar URIs que podem ser usados para identificar recurso arquivos que são compilados no assembly local ou compilados em um assembly referenciado do conjunto de módulos (assembly) local.

Arquivo de Recursos de Assembly Local

A URI de pacote para um arquivo de recurso compilado no assembly local utiliza a seguinte autoridade e caminho:

  • Autoridade: aplicativo: / / /.

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

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

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

O exemplo seguinte mostra a URI de 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 para um Assembly Referenciado

A URI de pacote para um arquivo de recurso compilado em um assembly referenciado utiliza a seguinte autoridade e caminho:

  • Autoridade: aplicativo: / / /.

  • Caminho: O nome de um arquivo de recurso é compilado em um assembly referenciado. O caminho precisa seguir o seguinte formato:

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

    • AssemblyShortName: o nome curto para o assembly mencionado.

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

    • PublicKey [opcional]: a chave pública usada para assinar o assembly mencionado. Utilizado quando dois ou mais assemblies referenciados que possuem o mesmo nome curto são carregados.

    • ; componente: Especifica que o assembly que está sendo referenciado é referenciado do conjunto de módulos (assembly) local.

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

O exemplo seguinte mostra uma URIde 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 seguinte mostra uma URI de 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 seguinte mostra uma URI de pacote para um arquivo de recurso XAML localizado na raiz da pasta de projeto de uma versão específica de assembly referenciado.

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

Note que a sintaxe da URI de pacote para arquivos de recurso de assembly referenciado só podem ser usados com a autoridade aplication:///. Por exemplo, o seguinte não é suportado no WPF.

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

URIs de Pacote de Arquivo de Conteúdo

A URI de pacote para um arquivo de conteúdo utiliza os seguintes autoridade e caminho:

  • Autoridade: aplicativo: / / /.

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

O exemplo a seguir mostra uma URI de pacote para um arquivo de conteúdo XAML, localizado na mesma pasta do assembly executável.

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

O exemplo a seguir mostra a URI de 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çãoObservação:

Arquivos de conteúdo HTML não podem ser visitados. O esquema de URI suporta navegação apenas para arquivos HTML localizados no site de origem.

URIs de Pacote do Local de Origem

A URI de pacote para um local de origem utiliza os seguintes autoridade e caminho:

  • Autoridade: sitedeorigem: / / /.

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

O exemplo a seguir mostra uma URI de pacote para um arquivo XAML do local de origem, armazenado no local de onde o assembly executável foi lançado.

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

O exemplo a seguir mostra uma URI de pacote para um arquivo XAML do local de origem, armazenado em uma subpasta relativa ao local de onde o assembly executável foi lançado.

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

Arquivos de Página

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:

Absolutos vs.URIs relativos de empacotar

Uma URI de pacote totalmente qualificada inclui um esquema, uma autoridade, e o caminho, e é considerada uma URI de pacote absoluta. Como simplificação para os desenvolvedores, elementos XAML tipicamente permitem que atributos apropriados sejam definidos com uma URI de pacote relativa, que inclui apenas o caminho.

Por exemplo, considere a seguinte URI de pacote absoluta para um arquivo de recurso no assembly local.

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

A URI de pacote relativa que referencia este arquivo de recurso seria o seguinte.

/ResourceFile.xaml

ObservaçãoObservação:

Como site dos arquivos de origem não estão associados com assemblies, eles podem apenas ser chamados com empacotar absoluto URIs.

Por padrão, uma URI de pacote relativa é considerada relativa à localização do markup ou código que contém a referência. Se uma barra invertida inicial for utilizada, entretanto, a referência de URI de pacote é considerada relativa à raiz do aplicativo. Por exemplo, considere a estrutura de projeto a seguir:

App.xaml

Page2.xaml

\SubFolder

  + Page1.xaml

  + Page2.xaml

Se Page1.xaml contém um URI que referencia Root\SubFolder\Page2.xaml, a referência pode utilizar a seguinte URI de pacote relativa.

Page2.xaml

Se Page1.xaml contém um URI que referencia Root\Page2.xaml, a referência pode utilizar a seguinte URI de pacote relativa.

/Page2.xaml

Resolução de URI de Pacote

O formato de URIs de pacote tornam possível que URIs de pacote para diferentes tipos de arquivos tenham a mesma aparência. Por exemplo, considere a URI de pacote absoluta a seguir:

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

A URIde pacote absoluta poderia se referir tanto a um arquivo de recurso no assembly local como a um arquivo de conteúdo. O mesmo vale para a seguinte URI de pacote relativa.

/ResourceOrContentFile.xaml

Para determinar a que tipo de arquivo a URI de pacote se refere, o WPF resolve URIs para arquivos de recurso em assemblies locais e arquivos de conteúdo seguinte as seguintes heurísticas:

  1. Verifica nos metadados do assembly um atributo AssemblyAssociatedContentFileAttribute que case com a URI de pacote.

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

  3. Se o atributo AssemblyAssociatedContentFileAttribute não for encontrado, verificar o conjunto de arquivos de recurso compilados no assembly local.

  4. Se um arquivo de recurso que case com o caminho da URI de pacote for encontrado, o caminho da URI de pacote se refere a um arquivo de recurso.

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

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

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

  • Arquivos incorporados em assemblies consultados: URIs que identificá-los são exclusivos, como incluir o nome do assembly referenciado e o ;component sufixo.

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

Uma simplificação que a resolução de URI de pacote permite é para código ser independente da localização de arquivos de recurso e conteúdo. Por exemplo, se você tem um arquivo de recurso no assembly local reconfigurado como um arquivo de conteúdo, a URI de pacote para o recurso permanece o mesmo, assim como o código que utiliza a URI de pacote.

Programação com as URIs de Pacote

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

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

Utilizando URIs de Pacote em Marcação

Uma URI de pacote é especificada em marcação definindo-se um elemento do atributo com a URI de pacote. Por exemplo:

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

Tabela 1 ilustra as várias URIs de pacote absolutas que você pode especificar na marcação.

Tabela 1: Absoluto empacotar URIs na marcação

File

URI de pacote absoluta

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 subpasta de assembly referenciado versionado

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

Arquivo de conteúdo

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

Arquivo de conteúdo em subpasta

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

Arquivo do site de origem

"pack://siteoforigin:,,,/SOOFile.xaml"

Arquivo do site de origem em subpasta

"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

Tabela 2 ilustra as várias URIs de pacote relativas que você pode especificar na marcação.

Tabela 2: URIs relativos empacotar na marcação

File

URI de pacote relativa

Arquivo de recurso em subpasta - assembly local

"/ResourceFile.xaml"

Arquivo de recurso em 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 em subpasta

"/Subfolder/ContentFile.xaml"

Utilizando URIs de Pacote em Código

Você especifica uma URI de pacote em código instanciando a classe Uri e passando a URI de pacote como parâmetro para o construtor. Isto é demonstrado no exemplo a seguir.

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

Por padrão, a classe Uri considera a URIs de pacote como absoluta. Consequentemente, uma exceção é levantada quando uma instância da classe Uri é criada com uma URI de pacote relativa.

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

Felizmente, a sobrecarga Uri(String, UriKind) do construtor da classe Uri aceita um parâmetro de tipo UriKind que permite especificar se a URI de pacote é absoluta ou relativa.

// 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 apenas especificar Absolute ou Relative quando tiver certeza se que a URI de pacote fornecida for uma ou outra. Se não tiver certeza do tipo de URI de pacote utilizada, por exemplo, quando o usuário entra uma URI de pacote em tempo de execução, use o RelativeOrAbsolute.

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

Tabela 3 ilustra as várias URIs de pacote relativas que você pode especificar em código utilizando System.Uri.

Tabela 3: Absoluto empacotar URIs no código

File

URI de pacote absoluta

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 em subpasta de assembly referenciado

Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);

Arquivo de recurso em subpasta de assembly referenciado versionado

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

Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute);

Arquivo do site de origem

Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);

Arquivo do site de origem em subpasta

Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

Tabela 4 ilustra as várias URIs de pacote relativas que você pode especificar em código utilizando System.Uri.

Tabela 4: URIs relativos de empacotar no código

File

URI de pacote relativa

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

Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative);

Cenários comuns de URI de Pacote

As seções anteriores discutiram como construir uma URIs de pacote para identificar arquivos de recurso, conteúdo, e do site de origem. No WPF, essas construções são utilizadas de diversas formas, e os cenários seguintes abrangem vários usos comuns.

Especificar a UI a ser Exibida quando uma Aplicação Inicia.

StartupUri especifica a primeira UI a exibir quando um aplicativo WPF é iniciado. Para aplicativos standalone, a UI pode ser uma janela, como mostrado no exemplo seguinte.

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

Aplicativos standalone e aplicativos de navegador XAML (XBAPs) também podem especificar uma página como UI inicial, como mostrado no exemplo a seguir.

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

Se o aplicativo for um aplicativo standalone e a página especificada com StartupUri, o WPF abre a NavigationWindow para hospedar a página. Para XBAPs, a página é exibida no navegador host.

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

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

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

Especificando um Ícone de Janela

O exemplo a seguir mostra como utilizar um URI para especificar um ícone de janela.

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

Para obter mais informações, consulte Icon.

Carregando Arquivos de Imagem, Áudio e Vídeo

WPF permite que aplicativos utilizem uma grande variedade de tipos de mídia, todos os quais podem ser identificados e carregados com URIs de pacote, como exibido nos exemplos seguintes.

<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 Visão Geral de elementos gráficos, animação e media do WPF.

Carregando um Dicionário de Recurso do Site de Origem

Dicionários de recurso (ResourceDictionary) podem ser utilizados para dar suporte à temas de aplicativos. Uma maneira de criar e gerenciar temas é criando múltiplos temas como dicionários de recurso localizados no site de origem do aplicativo. Isto permite que temas sejam adicionados e atualizados sem recompilar e fazer redeploy de um aplicativo. Estes dicionários de recurso podem ser identificados e carregados usando URIs, o que é mostrado no exemplo seguinte.

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

Para uma demonstração de utilizar múltiplos dicionários de recurso para criar um tema de aplicação, veja Exemplo de aplicativo skinned.

Para obter uma visão geral de temas WPF , consulte Styling and Templating.

Consulte também

Tarefas

Exemplo URI de pacote

Conceitos

Arquivos de Recurso, Conteúdo e Dados de Aplicações Windows Presentation Foundation