Recurso de aplicativo do WPF, conteúdo e arquivos de dados

Em WPF, um arquivo de recursos é um arquivo incluído em um projeto Microsoft build engine (MSBuild) como um item Resource.

<Project "xmlns=http://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <ItemGroup>
    <Resource Include="ResourceFile.xaml" />
  </ItemGroup>
  ...
</Project>

Observação
Em Microsoft Visual Studio, você cria um arquivo de recursos acrescentando um arquivo a um projeto e definindo seu Build Action como Resource.

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

Para carregar um arquivo de recurso, você pode chamar o GetResourceStream método da Application classe, passando de um pacote de URI que identifica o arquivo de recurso desejado. GetResourceStream Retorna um StreamResourceInfo objeto, que expõe o arquivo de recurso como 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" />

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="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="SOOPage.xaml" />

Você pode fazer isso quando um arquivo XAML é incluído em um projeto Microsoft build engine (MSBuild) como um item Page.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <ItemGroup>
    <Page Include="MainWindow.xaml" />
  </ItemGroup>
  ...
</Project>

Observação
Em Visual Studio, você acrescenta um novo Window, NavigationWindow, Page, FlowDocument ou ResourceDictionary a um projeto, o Build Action para o arquivo de marcação vai ser por default 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ção
Se um arquivo XAML é configurado como um item Resource, e não tem um arquivo code-behind, o XAML bruto é compilado em um assembly em vez de uma versão binária do XAML bruto.

Para adicionar um arquivo de conteúdo a um projeto, um arquivo de dados do aplicativo deve ser incluído como um Content item. Além disso, como um arquivo de conteúdo não é compilado diretamente no assembly, você deverá definir o MSBuildCopyToOutputDirectory o elemento de metadados para especificar que o arquivo de conteúdo é copiado para um local que é relativo ao assembly incorporado. 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="http://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <ItemGroup>
    <Content Include="ContentFile.xaml">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
  ...
</Project>

Observação
Em Visual Studio, você cria um arquivo de conteúdo acrescentando um arquivo a um projeto e definindo seu Build Action como Content, e define seu Copy to Output Directory como Copy always (o mesmo que Always) e Copy if newer (o mesmo que 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.

Para carregar um arquivo de conteúdo, você pode chamar o GetContentStream método da Application classe, passando de um pacote de URI que identifica o arquivo de conteúdo desejado. GetContentStream Retorna um StreamResourceInfo objeto, que expõe o arquivo de conteúdo como 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" />

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 Microsoft build engine (MSBuild) como item None. Como com os arquivos de conteúdo, você precisará definir a MSBuildCopyToOutputDirectory atributo para especificar que o site do arquivo de origem é copiado para um local que é relativo ao assembly incorporado, especificando a Always valor ou a PreserveNewest valor. 

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >
  ...
  <None Include="PageSiteOfOriginFile.xaml">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
  ...
</Project>

Observação
Em Visual Studio, você cria um arquivo de local de origem acrescentando um arquivo a um projeto e definindo seu Build Action como None.

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

Para carregar um site do arquivo de origem, você pode chamar o GetRemoteStream método da Application classe, passando de um pacote de URI que identifica o site desejado do arquivo de origem. GetRemoteStream Retorna um StreamResourceInfo objeto, que expõe o site do arquivo de origem como 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:,,,/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" />