Dicionários de recursos mesclados (WPF .NET)

  • Artigo

Os recursos do Windows Presentation Foundation (WPF) oferecem suporte a um recurso de dicionário de recursos mesclado. Esse recurso fornece uma maneira de definir a parte de recursos de um aplicativo WPF fora do aplicativo XAML compilado. Os recursos podem ser compartilhados entre aplicativos e são também isolados de modo mais conveniente para localização.

Importante

A documentação do Guia da Área de Trabalho para .NET 7 e .NET 6 está em construção.

Criar um dicionário mesclado

Na marcação, você pode usar a seguinte sintaxe para introduzir um dicionário de recursos mesclados em uma página:

<Page.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <ResourceDictionary Source="myresourcedictionary.xaml"/>
      <ResourceDictionary Source="myresourcedictionary2.xaml"/>
    </ResourceDictionary.MergedDictionaries>
  </ResourceDictionary>
</Page.Resources>

O ResourceDictionary elemento não tem uma diretiva x:Key, que geralmente é necessária para todos os itens em uma coleção de recursos. Mas outra ResourceDictionary referência dentro da MergedDictionaries coleção é um caso especial, reservado para esse cenário de dicionário de recursos mesclado. Além disso, o ResourceDictionary que introduz um dicionário de recursos mesclados não pode ter uma diretiva x:Key.

Normalmente, cada ResourceDictionary dentro da MergedDictionaries coleção especifica um Source atributo. O valor de deve ser um identificador de recurso uniforme (URI) que resolve para o local do arquivo de Source recursos a ser mesclado. O destino desse URI deve ser outro arquivo XAML, com ResourceDictionary como seu elemento raiz.

Observação

É legal definir recursos dentro de um dicionário que é especificado como um ResourceDictionary dicionário mesclado, seja como uma alternativa para especificar Source, ou além de quaisquer recursos incluídos da fonte especificada. No entanto, esse não é um cenário comum. O cenário principal para dicionários mesclados é mesclar recursos de locais de arquivos externos. Se você quiser especificar recursos dentro da marcação de uma página, defina-os no principal ResourceDictionary e não nos dicionários mesclados.

Comportamento do dicionário mesclado

Os recursos em um dicionário mesclado ocupam um local no escopo de pesquisa de recursos que está logo após o escopo do dicionário de recursos principal em que são mesclados. Embora uma chave de recurso deva ser exclusiva em qualquer dicionário individual, uma chave pode existir várias vezes em um conjunto de dicionários mesclados. Nesse caso, o recurso retornado virá do último dicionário encontrado sequencialmente na MergedDictionaries coleção. Se a coleção foi definida em XAML, a ordem dos dicionários mesclados na coleção é a MergedDictionaries ordem dos elementos, conforme fornecido na marcação. Se uma chave for definida no dicionário primário e também em um dicionário que foi mesclado, o recurso retornado virá do dicionário primário. Essas regras de escopo se aplicam igualmente para referências de recursos estáticos e referências de recursos dinâmicos.

Dicionários e código mesclados

Os dicionários mesclados podem ser adicionados a um dicionário Resources por meio do código. O padrão, inicialmente vazio ResourceDictionary que existe para qualquer Resources propriedade também tem uma propriedade de coleção padrão, inicialmente vazia.MergedDictionaries Para adicionar um dicionário mesclado por meio de código, você obtém uma referência ao primário ResourceDictionarydesejado, obtém seu MergedDictionaries valor de propriedade e chama Add o genérico Collection contido no MergedDictionaries. O objeto adicionado deve ser um novo ResourceDictionaryarquivo .

No código, você não define a Source propriedade. Em vez disso, você deve obter um objeto criando um ou carregando um ResourceDictionary . Uma maneira de carregar um existente para chamar XamlReader.Load um fluxo de arquivos XAML existente ResourceDictionary que tenha uma ResourceDictionary raiz e, em seguida, converter o valor de retorno para ResourceDictionary.

URIs de dicionário mesclados

Há várias técnicas para incluir um dicionário de recursos mesclados, que são indicadas pelo formato URI (identificador uniforme de recursos) que você usa. Em linhas gerais, essas técnicas podem ser divididas em duas categorias: recursos que são compilados como parte do projeto e recursos que não são compilados como parte do projeto.

Para obter recursos que são compilados como parte do projeto, você pode usar um caminho relativo que se refere ao local do recurso. O caminho relativo é avaliado durante a compilação. Seu recurso deve ser definido como parte do projeto como uma ação de compilação de Recurso . Se você incluir um arquivo .xaml de recurso no projeto como Recurso, não será necessário copiar o arquivo de recurso para o diretório de saída, o recurso já estará incluído no aplicativo compilado. Você também pode usar a ação de compilação de conteúdo, mas deve copiar os arquivos para o diretório de saída e também implantar os arquivos de recurso na mesma relação de caminho para o executável.

Observação

Não use a ação de compilação de Recursos Incorporados . A ação de compilação em si é suportada para aplicativos WPF, mas a resolução de Source não incorpora ResourceManagere, portanto, não pode separar o recurso individual do fluxo. Você ainda pode usar o Recurso Incorporado para outros fins, desde que também tenha usado ResourceManager para acessar os recursos.

Uma técnica relacionada é usar um URI de pacote para um arquivo XAML e fazer referência a ele como Source. O URI do pacote permite referências a componentes de assemblies referenciados e outras técnicas. Para obter mais informações sobre URIs de pacote, consulte Arquivos de recursos, conteúdo e dados do aplicativo WPF.

Para recursos que não são compilados como parte do projeto, o URI é avaliado em tempo de execução. Você pode usar um transporte de URI comum, como file: ou http: para fazer referência ao arquivo de recurso. A desvantagem de usar a abordagem de recursos não compilados é que o arquivo: o acesso requer etapas de implantação adicionais e o acesso http: implica a zona de segurança da Internet.

Reutilizando dicionários mesclados

Você pode reutilizar ou compartilhar dicionários de recursos mesclados entre aplicativos, pois o dicionário de recursos a ser mesclado pode ser referenciado por meio de qualquer URI (identificador uniforme de recursos) válido. Exatamente como você faz isso depende de sua estratégia de implantação de aplicativo e qual modelo de aplicativo você segue. A estratégia de URI do pacote mencionada anteriormente fornece uma maneira de originar comumente um recurso mesclado em vários projetos durante o desenvolvimento, compartilhando uma referência de assembly. Nesse cenário, os recursos ainda são distribuídos pelo cliente e pelo menos um dos aplicativos deve implantar o assembly referenciado. Também é possível fazer referência a recursos mesclados por meio de um URI distribuído que usa o protocolo http: .

Escrever dicionários mesclados como arquivos de aplicativos locais ou no armazenamento compartilhado local é outro cenário possível de implantação de dicionário e aplicativo mesclados.

Localização

Se os recursos que precisam ser localizados forem isolados em dicionários mesclados em dicionários primários e mantidos como XAML solto, esses arquivos poderão ser localizados separadamente. Essa técnica é uma alternativa simples para localizar os assemblies satélite de recursos. Para detalhes, consulte Visão geral de globalização e localização do WPF.

Confira também