Sistema de Gerenciamento de Recursos

Applies to Windows and Windows Phone

O Sistema de Gerenciamento de Recursos é empregado no momento em que você constrói seu aplicativo. Ele cria um arquivo que é empacotado com o aplicativo e ajuda a resolver recursos no tempo de execução.

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.

  • 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 aos arquivos no pacote.
  • Normalmente os pacotes contêm um único arquivo PRI 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 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 têm o formato PE. Eles são criados especificamente para serem somente dados como o formato de recursos do Windows. Eles substituem os recursos contidos em DLLs no modelo de aplicativo do Win32.

APIs do WinRT

Funcionalidade básica (ResourceLoader)

O acesso a recursos é exposto por meio de APIs do WinRT para JavaScript, C#, VB e C++. A forma mais simples de acessar os recursos é por meio do namespace Windows.ApplicationModel.Resources via ResourceLoader. ResourceLoader fornece acesso básico a recursos de cadeia de caracteres a partir de vários arquivos de recursos, bibliotecas referenciadas ou outros pacotes.

Funcionalidade avançada (ResourceManager)

ResourceManager no namespace Windows.ApplicationModel.Resources.Core permite um acesso mais avançado que ResourceLoader a informações sobre recursos, como enumeração e inspeção.

Um NamedResource é 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.

Um ResourceCandidate é um valor de recurso concreto único e seus qualificadores, como a cadeia de caracteres "Hello World" para inglês ou "logo.scale-100.jpg" para dimensionar 100 dispositivos.

Os recursos disponíveis para um aplicativo são armazenados em coleções hierárquicas conhecidas como ResourceMaps. O ResourceManager fornece acesso aos vários ResourceMaps de nível superior s de um aplicativo da Windows Store, que correspondem aos vários pacotes do aplicativo. O mainResourceMap corresponde ao mapa de recursos para o pacote de aplicativo atual, e não a seus pacotes de estrutura referenciados. Cada ResourceMap é nomeado depois do nome do pacote especificado no manifesto do pacote. Em um ResourceMap estão as Subárvores do ResourceMap (veja ResourceMap.GetSubtree), que ainda contêm NamedResources. As subárvores normalmente correspondem ao arquivo de recurso (veja Como carregar recursos de cadeia de caracteres) que contém o recurso.

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

Observação  Os argumentos do identificador de recursos são tratados como fragmentos de URI (Identificador de Recursos Uniforme), sujeitos à semântica de URI. Por exemplo, getValue("Caption%20") é tratado como getValue("Caption "). Não use "?" ou "#" em identificadores de recursos, porque eles terminam o caminho de recursos nomeado. Por exemplo, "Foo?3" é tratado como "Foo".

Além de dar suporte ao acesso aos 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 do ResourceMap "Arquivos" reservada. Por exemplo, o arquivo "images/logo.png" corresponde ao nome de 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 é um conjunto de valores de qualificadores de recursos (linguagem, escala, etc.) Um contexto padrão usa a configuração atual do aplicativo para cada valor de qualificador, a menos que substituída. 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 escala-100 corresponde em um certo grau a um contexto de escala-180, embora não tão bem quanto os candidatos qualificados para escala-140 ou (correspondência perfeita) escala-180.

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.

Em seguida, o processo global de classificação é iniciado, avaliando candidatos em relação ao qualificador de maior prioridade, o idioma. Não correspondências são eliminadas. Os demais candidatos são classificados em relação à sua qualidade de correspondência para o 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 do comando MakePRI.exe

MakePRI.exe tem um conjunto de opções de comando: 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

Normalmente, MakePRI.exe é 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> para o indexador associado a esse contêiner deve ser incluído no arquivo de configuração). Normalmente, os qualificadores encontrados em uma entidade receptora, 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

O indexador de pasta é identificado por um atributo de tipo FOLDER. Ele 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

O indexador ResJSON é identificado por um atributo de tipo RESJSON. Ele indexa o conteúdo de um arquivo .resjson, que é um arquivo de recurso de cadeia de caracteres. Veja a seção ResJSN do tópico Indexadores específicos de formato.

ResW

O indexador ResW é identificado por um atributo de tipo RESW. Ele 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

O indexador ResFiles é identificado por um atributo de tipo RESFILES. Ele indexa o conteúdo de um arquivo .resfiles. Veja a seção ResFiles do tópico Indexadores específicos de formato.

PRI

O indexador PRI é identificado por um atributo de tipo PRI. Ele indexa o conteúdo de um arquivo PRI. Ele normalmente é usado para indexar um recurso contido em outro assembly, DLL, SDK 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

O indexador PRIInfo é identificado por um atributo de tipo PRIINFO. Ele indexa o conteúdo de um arquivo de despejo detalhado. O arquivo de despejo é produzido usando 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:
© 2014 Microsoft