Sistema de Gerenciamento de Recursos

Sistema de Gerenciamento de Recursos

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

O Sistema de Gerenciamento de Recursos faz parte do suporte a ferramentas que acontece quando você compila seu aplicativo. Ele cria um arquivo que é empacotado com o aplicativo e, em seguida, é chamado pelo Tempo de Execução do Windows para resolver recursos quando o aplicativo é executado em um contexto de usuário.

Arquivo PRI (Índice de Recurso do Pacote)

Cada pacote de aplicativo deve conter um índice binário dos recursos no aplicativo. Esse arquivo é criado em tempo de compilação e é referenciado como um arquivo PRI (Indexador de Recursos de Pacote).

  • O arquivo PRI é empacotado com o resto do aplicativo e ajuda a resolver recursos no tempo de execução.
  • O PRI contém recursos de cadeia de caracteres reais e um conjunto indexado de caminhos de arquivos que fazem referência a vários arquivos do pacote.
  • Normalmente, os pacotes contêm um único arquivo PRI por idioma, chamado resources.pri.
  • O arquivo resources.pri da raiz de cada pacote é carregado automaticamente quando é criada uma instância do ResourceManager.
  • Os arquivos PRI podem ser criados e despejados com a ferramenta MakePRI.exe.
  • Para o desenvolvimento de aplicativos comum você não precisará de MakePRI.exe porque ele já está integrado ao fluxo de trabalho de compilação do Visual Studio, e o Visual Studio dá suporte à edição de arquivos PRI em uma interface do usuário dedicada. No entanto, os tradutores e as ferramentas que eles usam talvez dependam de MakePRI.exe.
  • Cada arquivo PRI contém uma coleção nomeada de recursos, conhecida como resource map. Quando um arquivo PRI de um pacote é carregado, o nome do mapa de recursos é verificado de forma a corresponder com o nome de identidade do pacote.
  • Os arquivos PRI são somente dados e não usam o formato de arquivo PE. Eles são criados especificamente para serem somente dados como o formato de recurso do Windows. Eles substituem os recursos contidos em DLLs no modelo de aplicativo do Win32.

APIs de Tempo de Execução do Windows

Funcionalidade básica (ResourceLoader)

O acesso a recursos é exposto por meio de APIs do Tempo de Execução do Windows para JavaScript, C#, Visual Basic e C++. A forma mais simples de acessar os recursos é por meio do namespace Windows.ApplicationModel.Resources e da classe ResourceLoader. ResourceLoader fornece acesso básico a recursos de cadeia de caracteres a partir do conjunto de arquivos de recursos, bibliotecas referenciadas ou outros pacotes.

Funcionalidade avançada (ResourceManager)

A classe ResourceManager (no namespace Windows.ApplicationModel.Resources.Core) fornece informações adicionais sobre recursos, como enumeração e inspeção. Isso vai além do que a classe ResourceLoader pode oferecer.

Um objeto NamedResource representa um recurso lógico individual com vários idiomas ou outras variações qualificadas. Ele descreve a exibição lógica do ativo ou recurso, com um nome como Header1 ou logo.jpg.

O objeto ResourceCandidate representa um valor de recurso concreto único e seus qualificadores, como a cadeia de caracteres "Hello World" para o inglês ou "logo.scale-100.jpg" como um recurso de imagem qualificado específico à resolução scale-100.

Os recursos disponíveis para um aplicativo são armazenados em coleções hierárquicas, que você pode acessar com um objeto ResourceMap. A classe ResourceManager fornece acesso às várias instâncias de ResourceMap de alto nível usadas pelo aplicativo, que correspondem aos vários pacotes do aplicativo. O valor MainResourceMap corresponde ao mapa de recursos para o pacote do aplicativo atual, e exclui quaisquer pacotes de estrutura referenciados. Cada ResourceMap é nomeado de acordo com o nome do pacote especificado no manifesto do pacote. Em um ResourceMap estão as subárvores de ResourceMap (veja ResourceMap.GetSubtree), que ainda contêm objetos NamedResource. As subárvores normalmente correspondem aos arquivos de recursos que contêm o recurso. Para saber mais, veja "Como carregar recursos de cadeias de caracteres" (HTML ou XAML). A seguir está um exemplo:



var rcns = Windows.ApplicationModel.Resources.Core;
var resMap = rcns.ResourceManager.current.mainResourceMap.getSubtree("Resources");
var resContext = rcns.ResourceContext.getForCurrentView();
var str = resMap.getValue("String1", resContext).valueAsString;

Observação  O identificador de recurso é tratado como um fragmento de URI (Identificador de Recursos Uniforme), sujeito à semântica de URI. Por exemplo, GetValue("Caption%20") é tratado como GetValue("Caption "). Não use "?" ou "#" em identificadores de recursos, pois eles encerram a avaliação do caminho de recursos. Por exemplo, "MeuRecurso?3" é tratado como "MeuRecurso".
 

Além de dar suporte ao acesso a recursos de cadeia de caracteres de um aplicativo, o ResourceManager também mantém a capacidade de enumerar e inspecionar os diversos recursos de arquivo. Para evitar colisões entre arquivos e outros recursos originados de dentro de um arquivo, os caminhos de arquivos indexados residem todos em uma subárvore de ResourceMap "Files" reservada. Por exemplo, o arquivo images/logo.png corresponde ao nome do recurso Files/images/Logo.png.

As APIs de StorageFile tratam de forma transparente as referências a arquivos como recursos e são apropriadas para cenários de uso típicos. O ResourceManager deve ser usado somente para cenários avançados, como contextos substituídos ou enumeração de valores possíveis.

ResourceContext

Os candidatos a recursos são escolhidos com base em um ResourceContext específico, que é uma coleção de valores de qualificadores de recursos (idioma, escala etc.). Um contexto padrão usa a configuração atual do aplicativo para cada valor de qualificador, a menos que seja substituído. Em geral, recursos podem ser qualificado para escala, o que pode variar de um monitor para o outro e, portanto, de uma exibição de aplicativo para outra. Por essa razão, cada exibição de aplicativo tem um contexto padrão distinto. O contexto padrão para uma determinada exibição pode ser obtido com o uso de ResourceContext.GetForCurrentView. Sempre que um candidato a recurso é recuperado, uma instância ResourceContext deve ser transmitida para obter o valor mais apropriado para uma determinada exibição.

Quando um recurso é solicitado, pode haver vários candidatos que correspondem em um certo grau ao contexto de recurso atual. O Sistema de Gerenciamento de Recursos irá analisar todos os candidatos e determinar o melhor deles para ser retornado. Para isso, todos os qualificadores são levados em consideração para classificar todos os candidatos.

Nesse processo de classificação, os diferentes qualificadores recebem prioridades distintas: o idioma tem o maior impacto sobre a classificação geral, seguido por contraste, depois escala e assim por diante. Para cada qualificador, qualificadores candidatos são comparados com o valor do qualificador de contexto para determinar uma qualidade de correspondência. A foma como a comparação é feita depende do qualificador.

Para alguns qualificadores, como escala e contraste, há sempre um grau mínimo de correspondência. Por exemplo, um candidato qualificado para scale-100 corresponde em certa medida a um contexto de scale-180, embora não tão bem quanto os candidatos qualificados para scale-140 ou scale-180 (correspondência perfeita).

No entanto, para outros qualificadores, como idioma ou região inicial, é possível ter uma comparação de não correspondência (bem como graus de correspondência). Por exemplo, um candidato qualificado para idioma como "en-US" corresponde a um contexto de "en-GB" pelo menos em um certo grau, mas um candidato qualificado como "fr" não corresponde em nada a esse contexto. Da mesma forma, um candidato qualificado para a região inicial como "155" (Europa Ocidental) corresponde relativamente bem a um contexto para um usuário cuja configuração de região inicial é "FR". Porém, um candidato qualificado como "US" não corresponde em nada.

Quando um candidato é avaliado, se houver uma comparação de não correspondência para qualquer qualificador, esse candidato receberá uma classificação geral de não correspondência e não será selecionado. Dessa forma, os qualificadores de maior prioridade podem ter a maior ponderação na seleção da melhor correspondência, mas até mesmo um qualificador de baixa prioridade pode eliminar um candidato devido a uma não correspondência.

Um candidato é neutro em relação a um qualificador quando ele não está marcado para esse qualificador. Para qualquer qualificador, um candidato neutro é sempre uma correspondência para o valor do qualificador de contexto, mas somente com uma qualidade de correspondência inferior à de qualquer candidato que tenha sido marcado para esse qualificador e tenha um certo grau de correspondência (exata ou parcial). Por exemplo, se tivermos candidatos qualificados para "en-US", "en", "fr" e também um candidato de idioma neutro, para um contexto com um valor de qualificador de idioma de "en-GB", os candidatos serão classificados na seguinte ordem: "en", "en-US", neutro, and "fr". Nesse caso, "fr" não corresponde, mas os outros candidatos correspondem em algum nível.

O processo global de classificação começa avaliando candidatos em relação ao qualificador de maior prioridade, que é o idioma. Os que não corresponderem serão eliminados. Os demais candidatos são classificados em relação à sua qualidade de correspondência de idioma. Se houver empate, o qualificador de maior prioridade seguinte, contraste, será levado em consideração, usando a qualidade de correspondência para contraste com o objetivo de diferenciar entre os candidatos empatados. Após o contraste, o qualificador de escala é usado para diferenciar os demais empates, e assim por diante em quantos qualificadores forem necessários para chegar a uma classificação bem ordenada.

Se todos os candidatos são eliminados da consideração porque os qualificadores não correspondem ao contexto, o carregador de recursos faz uma segunda passada procurando um candidato padrão para exibir. Os candidatos padrão são determinados durante a criação do arquivo PRI e devem garantir que sempre haja um candidato para seleção em qualquer contexto de tempo de execução (veja detalhes em Compilando recursos (MakePRI.exe)). Se um candidato tem algum qualificador que não corresponde e não é um padrão, esse candidato a recurso é descartado permanentemente.

Para todos os candidatos a recurso ainda em consideração, o carregador de recursos examina o valor do qualificador de contexto de prioridade mais alta e escolhe aquele que corresponde melhor ou com a melhor pontuação padrão. Qualquer correspondência real é considerada melhor que uma pontuação padrão.

Se há um vínculo, o valor do qualificador de contexto com a próxima prioridade mais alta é inspecionado e o processo continua, até encontrar uma correspondência melhor.

Veja exemplos em Exemplos de como os recursos são escolhidos.

Compilando recursos (MakePRI.exe)

MakePRI.exe é uma ferramenta de linha de comando usada para criar e despejar arquivos PRI. Ele é integrado como parte do MSBuild no Microsoft Visual Studio, mas pode ser útil para desenvolvedores criarem pacotes manualmente ou por sistema de compilação personalizados.

Opções de comandos de MakePRI.exe

MakePRI.exe tem um conjunto de opções de comandos: createconfig, new, versioned, resourcepack e dump. Para ver detalhes sobre seu uso, consulte Opções do comando MakePRI.exe.

Configuração de MakePRI.exe

O arquivo de configuração XML de PRI determina como e quais recursos são indexados. O esquema do XML de configuração é descrito na Configuração de MakePRI.exe.

Indexadores específicos do formato

MakePRI.exe normalmente é usado com as opções new, versioned ou resourcepack. Nesses casos, ele indexa os arquivos de origem para gerar um índice de recursos. MakePRI.exe usa vários indexadores individuais para ler diferentes arquivos ou contêineres de recursos de origem. O indexador mais simples é o indexador de pasta, que indexa o conteúdo de uma pasta, como imagens .jpg ou .png.

Os indexadores específicos de formato são identificados por elementos <indexer-config> em um elemento <index> do arquivo de configuração. O atributo type identifica o indexador específico de formato que é usado.

Os contêineres de recursos encontrados durante a indexação geralmente têm seu conteúdo indexado em vez de serem adicionados ao índice. Por exemplo, os arquivos .resjson que o indexador de pasta encontra podem ser indexados ainda por um indexador .resjson; nesse caso, o próprio arquivo .resjson não aparece no índice. (Observe que, para que isso aconteça, um elemento <indexer-config> do indexador associado a esse contêiner deve ser incluído no arquivo de configuração). Em geral, os qualificadores encontrados em uma entidade contentora, como uma pasta ou um arquivo .resjson, são aplicados a todos os recursos contidos, como os arquivos dentro da pasta ou as cadeias de caracteres no arquivo .resjson.

Veja em Indexadores específicos de formato as descrições e os esquemas dos seguintes tipos de indexador.

Pasta

Indexa o conteúdo de uma pasta e determina os qualificadores de recursos a partir dos nomes de pasta e arquivo. Veja a seção Pasta do tópico Indexadores específicos de formato.

ResJSON

Indexa o conteúdo de um arquivo .resjson, que é um arquivo de recurso de cadeia de caracteres. Veja a seção ResJSON do tópico Indexadores específicos de formato.

ResW

Indexa o conteúdo de um arquivo .resw, que é um arquivo de recurso de cadeia de caracteres. Veja a seção ResW do tópico Indexadores específicos de formato.

ResFiles

Indexa o conteúdo de um arquivo .resfiles. Veja a seção ResFiles do tópico Indexadores específicos de formato.

PRI

Indexa o conteúdo de um arquivo PRI. Normalmente é usado para indexar um recurso contido em outro assembly, DLL ou biblioteca de classes.

Todos os nomes de recursos, qualificadores e valores contidos no arquivo PRI são mantidos diretamente no novo arquivo PRI. Entretanto, o mapa de recursos de nível superior não é mantido no PRI final. Os Mapas de Recursos são mesclados.

Veja a seção PRI do tópico Indexadores específicos de formato.

PRIINFO

Indexa o conteúdo de um arquivo de despejo detalhado. O arquivo de despejo é gerado com o comando dump de MakePri.exe, com a opção de tipo de despejo detalhado. Veja a seção PRIINFO do tópico Indexadores específicos de formato.

Avisos e mensagens de erro de MakePRI.exe

O aviso

Resources found for language(s) '<language(s)>' but no resources found for default language(s): '<language(s)>'. Change the default language or qualify resources with the default language.

é mostrado quando MakePRI.exe ou MSBuild descobre arquivos ou recursos de cadeia de caracteres para um determinado recurso nomeado que parecem estar marcados com qualificadores de idioma, mas não existem candidatos para um idioma padrão. O processo de marcação de arquivos é descrito em Como nomear recursos usando qualificadores. Um arquivo ou uma pasta pode conter um nome de idioma, mas não é descoberto nenhum recurso qualificado para o idioma padrão exato. Por exemplo, se um projeto usa "en-US" como idioma padrão e tem um arquivo chamado "de/logo.png", mas não tem nenhum arquivo marcado com o idioma padrão "en-US", esse aviso será exibido. Para remover esse aviso, algum arquivo ou recurso de cadeia de caracteres deve ser qualificado com o idioma padrão, ou o idioma padrão deve ser mudado. Você pode alterar o idioma padrão em projetos de aplicativo da Windows Store abrindo package.appxmanifest no Visual Studio e editando "Idioma padrão" na guia Interface de Usuário do Aplicativo.

O aviso

No default or neutral resource given for '<resource identifier>'. The application may throw an exception for certain user configurations when retrieving the resources.

é mostrado quando MakePRI.exe ou MSBuild descobre arquivos ou recursos que parecem estar marcados com qualificadores de idioma cujos recursos não são claros. Há qualificadores, mas não há garantia de que um candidato a recurso específico possa ser retornado para esse identificador de recurso no tempo de execução. Se não for possível encontrar nenhum candidato a recurso de um determinado idioma, região ou outro qualificador que seja um padrão ou que sempre corresponda ao contexto de um usuário, esse aviso será exibido. No tempo de execução, para configurações de usuário específicas, como as preferências de idioma de um usuário ou a localização inicial (Configurações do PC > Região e idioma), as APIs usadas para recuperar o recurso podem gerar uma exceção inesperada. Para remover esse aviso, devem ser fornecidos recursos padrão, como um recurso no idioma padrão ou na região inicial global (homeregion-001) do projeto.

Usando MakePRI.exe em um sistema compilado

Os sistemas compilados devem usar os comandos MakePRI.exe "new", "versioned" ou "resourcepack", dependendo do tipo de projeto que está sendo criado. Os sistemas compilados que criam um arquivo PRI novo devem usar o comando "new". Os sistemas compilados que devem garantir a compatibilidade de deslocamentos internos por meio de iterações podem usar o comando "versioned". Os sistemas compilados que devem criar um arquivo PRI que contém variações adicionais de recursos, com validação para garantir que nenhum novo recurso seja adicionado para essa variação, devem usar o comando "resourcepack".

Os sistemas compilados que exigem controle explícito sobre arquivos de origem que são indexados podem usar o indexador ResFiles em vez de indexarem uma pasta. Os sistemas compilados também podem usar várias passagens de índice com diferentes indexadores específicos de formato para gerar um único arquivo PRI.

Os sistemas compilados também podem usar o indexador específico de formato PRI para adicionar arquivos PRI pré-compilados no PRI do pacote de outros componentes, como bibliotecas de classes, assemblies, SDKs e DLLs.

Quando são criados arquivos PRI para outros componentes, bibliotecas de classes, assemblies, DLLs e SDKs, a configuração de initialPath deve ser usada para garantir que os recursos de componente tenham seus próprios mapas de sub-recursos que não entrem em conflito com o aplicativo no qual estão incluídos.

Tópicos relacionados

APIs
Windows.ApplicationModel.Resources
ResourceLoader
Windows.ApplicationModel.Resources.Core
NamedResource
ResourceCandidate
ResourceManager
ResourceManager.DefaultContext
ResourceMap
Outros tópicos
Exemplos de como os recursos são escolhidos
Opções do comando MakePRI.exe
Configuração de MakePRI.exe
Indexadores específicos do formato
Como carregar recursos de cadeias de caracteres
Como nomear recursos usando qualificadores

 

 

Mostrar:
© 2018 Microsoft