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

  • Artigo

Microsoft Windows aplicativos geralmente dependem de arquivos que contêm dados não-executável, sistema autônomo Extensible Application Markup Language (XAML), imagens, vídeo e áudio. Windows Presentation Foundation (WPF) oferece suporte especial para configurar, identificando e uso desses tipos de arquivos de dados, que são chamados arquivos de dados do aplicativo. Esse suporte gira em torno de um conjunto específico de tipos de arquivos de dados de aplicação, incluindo:

  • Arquivos de recurso: Arquivos de dados que são compilados em um executável ou biblioteca WPF assembly.

  • Arquivos de conteúdo: Arquivos de dados autônomo que tem uma associação explícita com um executável WPF assembly.

  • Site de arquivos de origem: Arquivos de dados autônomo que não tem nenhuma associação com um executável WPF assembly.

Uma distinção importante a se fazer entre esses três tipos de arquivos é que arquivos de recurso e arquivos de conteúdo são conhecidos em tempo de compilaçao; um assembly não tem conhecimento explícito sobre eles. Para local de arquivos de origem, entretanto, um assembly pode não ter qualquer conhecimento sobre eles, ou conhecimento implícito através de um pacote de referência uniform resource identifier (URI); nesse último caso, não há garantias que o local referenciado de arquivo de origem realmente existe.

Para referenciar arquivos de dados de aplicação, Windows Presentation Foundation (WPF) utiliza o esquema Pack uniform resource identifier (URI), que é descrito em detalhes em URIs de Pacotes no Windows Presentation Foundation.

Este tópico descreve como configurar e utilizar arquivos de dados de aplicação.

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

  • Arquivos de recursos
  • Arquivos de Conteúdo
  • Arquivos de Local de Origem
  • Recompilando Após Modificar o Tipo de Compilação
  • Tópicos relacionados

Arquivos de recursos

Se um arquivo de dados de aplicação deve estar sempre disponível para uma aplicação, a única maneira de garantir a disponibilidade é compilá-lo em um assembly executável principal da aplicação ou em um de seus assemblies referenciados. Esse tipo de arquivo de dados de aplicação é conhecido como arquivo de recurso.

Você deve utilizar arquivos de recurso quando:

  • Você não precisa atualizar o conteúdo do arquivo de recursos após ser compilado em um assembly.

  • Você quer simplificar a complexidade da distribuição da aplicação reduzindo o número de dependências de arquivos.

  • Seu arquivo de dados de aplicação precisa ser localizável (veja Visão geral de globalização e localização do WPF).

ObservaçãoObservação:

recurso (dicionários XAML arquivos com ResourceDictionary sistema autônomo o elemento de nível superior) não são WPF recurso de arquivos; ao mesmo tempo WPF arquivos de recurso podem ser dicionários de recurso, um dicionário de recurso não precisa ser um arquivo de recurso (consulte ResourceDictionary).

Além disso, WPF arquivos de recurso, não são sistema autônomo mesmos tipo de recursos que podem ser configuradas usando o núcleo incorporado ou vinculado .NET Framework suporte para recursos do assembly (consulte ). Enquanto WPF arquivos de recurso aproveitar o núcleo .NET Framework incorporado recurso suporta, a capacidade de acessar WPF arquivos de recursos usando o empacotar URIs  é mais fácil do que usar espaços para nome.

Configurando Arquivos de Recursos

Em WPF, um arquivo de recursos é um arquivo incluído em um projeto Mecanismo de compilação Microsoft (MSBuild) como um item Resource.

<Project "xmlns=https://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <ItemGroup>
    <Resource Include="ResourceFile.xaml" />
  </ItemGroup>
  ...
</Project>
ObservaçãoObservação:

Em Microsoft Visual Studio, criar um arquivo de recurso adicionando um arquivo para um projeto e a configuração de seu Build Action para Resource.

Quando o projeto é compilado, MSBuild compila o recurso para dentro do assembly.

Utilizando Arquivos de Recursos

Para carregar um arquivo de recurso, você pode telefonar o GetResourceStream método para o Application classe, passando um empacotar URI que identifica o arquivo de recurso desejado. GetResourceStream Retorna um StreamResourceInfo objeto, que expõe o arquivo de recurso sistema autônomo um Stream e descreve seu tipo de conteúdo.

Como um exemplo, o código a seguir mostra como utilizar GetResourceStream para carregar um arquivo de recursos Page e defini-lo como o conteúdo de um Frame (pageFrame):

// Navigate to xaml page
Uri uri = new Uri("/PageResourceFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetResourceStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;

Embora chamar GetResourceStream lhe dê acesso ao Stream, você precisa realizar trabalho adicional de convertê-lo para o tipo de propriedade que você vai definir com ele. Em vez disso, você pode deixar WPF cuidar da abertura e conversão de Stream carregando um arquivo de recursos diretamente na propriedade de um tipo utilizando código.

O exemplo a seguir mostra como carregar Page diretamente em um Frame (pageFrame) utilizando código.

Uri pageUri = new Uri("/PageResourceFile.xaml", UriKind.Relative);
this.pageFrame.Source = pageUri;

O exemplo a seguir mostra o equivalente em marcação do exemplo anterior.

<Frame Name="pageFrame" Source="PageResourceFile.xaml" />

Arquivos de Código de Aplicação como Arquivos de Recurso

Um conjunto especial de arquivos de código de aplicação WPF pode ser referenciado utilizando pacote URIs incluindo janelas, páginas, documentos de fluxo e dicionários de recursos. Por exemplo, você pode definir a propriedade Application.StartupUri com um pacote URI que referencia a janela ou página que você gostaria de carregar quando uma aplicação inicia.

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

Você pode fazer isso quando um arquivo XAML é incluído em um projeto Mecanismo de compilação Microsoft (MSBuild) como um item Page.

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <ItemGroup>
    <Page Include="MainWindow.xaml" />
  </ItemGroup>
  ...
</Project>
ObservaçãoObservação:

Em Visual Studio, você adiciona um novo Window, NavigationWindow, Page, FlowDocument, ou ResourceDictionary para um projeto a Build Action para a marcação de arquivo padrão será Page.

Quando um projeto com itens Page é compilado, os itens XAML são convertidos em formato binário e compilados para dentro do assembly associado. Consequentemente, esses arquivos podem ser utilizados da mesma maneira que arquivos de recursos típicos.

ObservaçãoObservação:

Se um XAML arquivo está configurado sistema autônomo um Resource item e não tiver um arquivo code-behind, o bruto XAML é compilado em um assembly, em vez de uma versão binária do bruto XAML.

Arquivos de Conteúdo

Um arquivo de conteúdo é distribuído como arquivo avulso juntamente com um assembly executável. Apesar de não serem compilados em um assembly, assemblies são compilados com metadados que estabelecem uma associação com cada arquivo de conteúdo.

Você deve utilizar arquivos de conteúdo quando sua aplicação requerer um conjunto específico de arquivos de dados de aplicação que você pode querer atualizar sem recompilar o assembly que os consome.

Configurando Arquivos de Conteúdo

Para acrescentar um arquivo de conteúdo a um projeto, um arquivo de dados de aplicação deve ser incluído em um item Content. Furthermore, because a content file is not compiled directly into the assembly, you need to set the MSBuild CopyToOutputDirectory metadata element to specify that the content file is copied to a location that is relative to the built assembly. Se você quer quer o recurso seja copiado para a pasta de saída de compilação toda vez que o projeto for compilado, você define o elemento de metadados CopyToOutputDirectory com o valor Always. Caso contrário, você pode assegurar que somente a versão mais nova do recurso seja copiada para a pasta de saída de compilação utilizando o valor PreserveNewest.

O seguinte mostra um arquivo configurado como um arquivo de conteudo que é copiado para a pasta de saída de compilação apenas quando uma nova versão do recurso é acrescentada ao projeto.

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <ItemGroup>
    <Content Include="ContentFile.xaml">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
  ...
</Project>
ObservaçãoObservação:

Em Visual Studio, criar um arquivo de conteúdo adicionando um arquivo para um projeto e a configuração de seu Build Action para Contente defina seu Copy to Output Directory para Copy always (igual a Always) e Copy if newer (igual a PreserveNewest).

Quando o projeto é compilado, um atributo AssemblyAssociatedContentFileAttribute é compilado nos metadados do assembly de cada arquivo de conteúdo.

[assembly: AssemblyAssociatedContentFile("ContentFile.xaml")]

O valor do AssemblyAssociatedContentFileAttribute implica o caminho para o arquivo de conteúdo relativo à sua posição no projeto. Por exemplo, se um arquivo de conteúdo estava localizado em uma subpasta do projeto, a informação de caminho adicional seria incorporada ao valor AssemblyAssociatedContentFileAttribute.

[assembly: AssemblyAssociatedContentFile("Resources/ContentFile.xaml")]

O valor do AssemblyAssociatedContentFileAttribute também é o valor do caminho para o arquivo de conteúdo na pasta de saída de compilação.

Utilizando Arquivos de Conteúdo

Para carregar um arquivo de conteúdo, você pode chamar o GetContentStream método para o Application classe, passando um empacotar URI que identifica o arquivo de conteúdo desejado. GetContentStream Retorna um StreamResourceInfo objeto, que expõe o arquivo de conteúdo sistema autônomo um Stream e descreve seu tipo de conteúdo.

Como um exemplo, o código a seguir mostra como utilizar GetContentStream para carregar um arquivo de conteúdo Page e defini-lo como o conteúdo de um Frame (pageFrame):

// Navigate to xaml page
Uri uri = new Uri("/PageContentFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetContentStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;

Embora chamar GetContentStream lhe dê acesso ao Stream, você precisa realizar trabalho adicional de convertê-lo para o tipo de propriedade que você vai definir com ele. Em vez disso, você pode deixar WPF cuidar da abertura e conversão de Stream carregando um arquivo de recursos diretamente na propriedade de um tipo utilizando código.

O exemplo a seguir mostra como carregar Page diretamente em um Frame (pageFrame) utilizando código.

Uri pageUri = new Uri("/PageContentFile.xaml", UriKind.Relative);
this.pageFrame.Source = pageUri;

O exemplo a seguir mostra o equivalente em marcação do exemplo anterior.

<Frame Name="pageFrame" Source="PageContentFile.xaml" />

Arquivos de Local de Origem

Arquivos de recurso têm um relacionamento explícito com os assemblies com que eles são distribuídos, conforme definido pelo AssemblyAssociatedContentFileAttribute. Mas, há momentos em que você pode querer estabelecer um relacionamento implícito ou inexistente entre um assembly e um arquivo de dados de aplicação, incluindo quando:

  • Um arquivo não existe em tempo de compilação.

  • Você não sabe quais arquivos seu assembly vai requerer até o tempo de execução.

  • Você quer poder atualizar arquivos sem recompilar o assembly ao qual estão associados.

  • Sua aplicação utiliza arquivos de dados grandes, tais como áudio e vídeo, e você só quer que os usuários efetuem o seu download se assim escolherem.

É possível carregar esses tipos de arquivos utilizando esquemas tradicionais URI, tais como esquemas file:/// e http://.

<Image Source="file:///C:/DataFile.bmp" />
<Image Source="http://www.datafilewebsite.com/DataFile.bmp" />

Entretanto, os esquemas file:/// e http:// requerem que sua aplicafile:/// and http:// são tenha confiança total. Se sua aplicação é um aplicativo de navegador XAML (XBAP) que foi iniciada pela Internet ou intranet, e solicita apenas o conjunto de permissões permitido para aplicações iniciadas dessas localizações, arquivos avulsos so podem ser carregados do local de origem da aplicação (localização da inicialização). Tais arquivos são conheciso como arquivos de local de origem.

Arquivos de local de origem são a única opção para aplicações de confiança parcial, apesar de não serem limitados a aplicações de confiança parcial. Aplicações de confiança total podem ainda precisar carregar arquivos de dados que não conheciam em tempo de compilação; embora aplicações de confiança total possam utilizar file:///, é provável que os arquivos de dados de aplicaçao serão instalados na mesma pasta ou numa subpasta do assembly da aplicação. Nesse caso, utilizar o referenciamento ao local de origem é mais fácil do que utilizar file:///, porque utilizar file:/// requer que você utilize o caminho completo do arquivo.

ObservaçãoObservação:

Site de origem não são armazenados em cache arquivos com um aplicativo de navegador XAML (XBAP) em uma computador cliente, enquanto são arquivos de conteúdo. Consequentemente, só é efetuado seu download quando solicitados especificamente. Se uma aplicação aplicativo de navegador XAML (XBAP) possui arquivos de mídia grandes, configurá-lo como arquivos de local de origem significa que o disparo inicial da aplicação é muito mais rápido, e que o download dos arquivos é feito sob demanda.

Configurando Arquivos de Local de Origem

Se os seus arquivos de local de origem são inexistentes ou desconhecidos em tempo de compilação, você precisa utilizar mecanismos tradicionais de implantação para assegurar que os arquivos requeridos estão disponíveis em tempo de execução, incluindo utilizar o programa de linha de comando XCopy ou o Microsoft Windows Installer.

Se você conhece em tempo de compilação os arquivos que você gostaria que estivessem localizados no local de origem, mas ainda quer evitar uma dependência explícita, você pode acrescentar esses arquivos a um projeto Mecanismo de compilação Microsoft (MSBuild) como item None. As with content files, you need to set the MSBuild CopyToOutputDirectory attribute to specify that the site of origin file is copied to a location that is relative to the built assembly, by specifying either the Always value or the PreserveNewest value.

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <None Include="PageSiteOfOriginFile.xaml">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
  ...
</Project>
ObservaçãoObservação:

Em Visual Studio, você criar um site do arquivo de origem adicionando um arquivo para um projeto e a configuração de seu Build Action para None.

Quando o projeto é compilado, MSBuild copia os arquivos especificados para a pasta de saída de compilação.

Utilizando Arquivos de Local de Origem

Para carregar um site do arquivo de origem, você pode chamar o GetRemoteStream método para o Application classe, passando um empacotar URI que identifica o site desejado do arquivo de origem. GetRemoteStream Retorna um StreamResourceInfo objeto, que expõe o site do arquivo de origem sistema autônomo um Stream e descreve seu tipo de conteúdo.

Como um exemplo, o código a seguir mostra como utilizar GetRemoteStream para carregar um arquivo de recursos Page e defini-lo como o conteúdo de um Frame (pageFrame):

// Navigate to xaml page
Uri uri = new Uri("/SiteOfOriginFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetRemoteStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;

Embora chamar GetRemoteStream lhe dê acesso ao Stream, você precisa realizar trabalho adicional de convertê-lo para o tipo de propriedade que você vai definir com ele. Em vez disso, você pode deixar WPF cuidar da abertura e conversão de Stream carregando um arquivo de recursos diretamente na propriedade de um tipo utilizando código.

O exemplo a seguir mostra como carregar Page diretamente em um Frame (pageFrame) utilizando código.

Uri pageUri = new Uri("pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml", UriKind.Absolute);
this.pageFrame.Source = pageUri;

O exemplo a seguir mostra o equivalente em marcação do exemplo anterior.

<Frame Name="pageFrame" Source="pack://siteoforigin:,,,/SiteOfOriginFile.xaml" />

Recompilando Após Modificar o Tipo de Compilação

Após mudar o tipo de compilação de um arquivo de dados de aplicação, você precisa recompilar toda a aplicação para assegurar que as modificações sejam aplicadas. Se você apenas compilar a aplicação, as alterações não são aplicadas.

Consulte também

Conceitos

URIs de Pacotes no Windows Presentation Foundation