Visão geral sobre recursos de página da Web ASP.NET

Se você criar páginas da Web que serão lidas por falantes de vários idiomas, você deve fornecer uma maneira para leitores de exibir a página em seu próprio idioma.Uma abordagem é recriar a página em cada idioma.Entretanto, essa abordagem pode ser repleta de erros, propensa a trabalho, e difícil de manter à medida que você altera a página original.

ASP.NET fornece a você uma maneira de criar uma página que possa obter conteúdo e outros dados com base na configuração de idioma preferencial para o navegador ou da escolha explícita de idioma do usuário.Conteúdo e outros dados são chamados de recursos e esses dados podem ser armazenadas em arquivos de recurso ou outras fontes.

Para a página da Web ASP.NET, você configura controles para obter seus valores de propriedades dos recursos.Em tempo de execução, as expressões de recurso são substituídas por recursos do arquivo de recurso apropriado.

Arquivos de recursos

Um arquivo de recursos é um arquivo XML que contém as sequências que você deseja converter em idiomas diferentes ou caminhos para imagens.O arquivo de recurso contém pares chave / valor.Cada par é um recurso individual.Nomes de chaves não diferenciam maiúsculas de minúsculas.Por exemplo, um arquivo recurso pode conter um recurso com a chave Button1 e o valor Submit.

Crie um arquivo de recurso separado para cada idioma (por exemplo, inglês e francês) ou para um idioma e cultura (por exemplo inglês [Inglaterra], inglês [EUA]).Cada arquivo de recurso localizado tem os mesmos pares chave / valor; a única diferença é que um arquivo recursos localizado pode conter menos recursos que o arquivo de recurso padrão.O de linguagem interna processa e, em seguida, alça carregando o recurso padrão ou neutro.

Arquivos de recurso no ASP.NET têm uma extensão .resx.Em tempo de execução, o arquivo .resx é compilado em um assembly, que às vezes é chamado de um assembly satélite.Como os arquivos .resx são compilados dinamicamente, da mesma maneira que páginas da Web ASP.NET, você não tem que criar os módulos de recursos.A compilação condensa vários arquivos de recursos de idiomas similares para o mesmo assembly.

Quando você cria arquivos de recurso, você inicia criando um arquivo base .resx.Para cada idioma que você deseja oferecer suporte, crie um novo arquivo que tenha o mesmo nome de arquivo.Mas no nome inclua o idioma ou o idioma e a cultura (nome de cultura).Para obter uma lista de nomes de cultura, consulte a classe CultureInfo.Por exemplo, você pode criar os seguintes arquivos:

• WebResources.resx

  O arquivo de recurso base.Este é o arquivo de recurso padrão, ou de retorno.

• WebResources.es.resx

  Um arquivo de recurso para espanhol.

• WebResources.es-mx.resx

  Um arquivo de recurso para Espanhol (México), especificamente.

• WebResources.de.resx

  Um arquivo de recurso para alemão.

Em tempo de execução, o ASP.NET usa arquivo de recurso que é a melhor correspondência para a configuração da propriedade CurrentUICulture.A cultura interface do usuário IU para o segmento é definida de acordo com a cultura interface do usuário IU da página.Por exemplo, se a cultura atual do usuário for Espanhol, o ASP.NET usa a versão compilada do arquivo WebResources.ES.RESX.Se não houver nenhuma correspondência para a cultura atual do usuário, o ASP.NET usa recursos de fallback.Ele inicia procurando por recursos para uma cultura específica.Se eles não estiverem disponíveis, ele procura os recursos para uma cultura neutra.Se eles não forem localizados, o ASP.NET carrega as arquivo de recurso padrão.Neste exemplo, o arquivo de recurso padrão é WebResource.RESX.

Criar arquivos de recursos para sites da Web ASP.NET

No ASP.NET, você pode criar arquivos de recursos que têm escopo diferente.Você pode criar arquivos de recursos que são globais, que significa que você pode ler o arquivo de recursos de qualquer página ou código que está no site.Você também pode criar arquivos de recurso locais, que armazenam recursos para uma único página da Web do ASP.NET (arquivo.aspx).

Arquivos de recursos globais

Crie um arquivo de recurso global colocando-o na pasta reservada App_GlobalResources na raiz do aplicativo.Qualquer arquivo .resx que está na pasta App_GlobalResources tem escopo global.Além disso, o ASP.NET gera um objeto fortemente tipado, que oferece aos desenvolvedores uma maneira simples de acessar os recursos globais por programação.

Arquivos de recursos locais

Um arquivo de recurso local é um que se aplica a apenas uma página ASP.NET (uma arquivo ASP.NET com a extensão .aspx, .ascx, .master, e assim por diante).Você coloca arquivos de recursos locais nas pastas que têm o nome reservado App_LocalResources.Pastas App_LocalResources podem existir em qualquer pasta no aplicativo, diferentemente da pasta raiz App_GlobalResources.Você associa um conjunto de arquivos de recursos com uma página da Web específica usando o nome do arquivo de recurso.

Por exemplo, se você tem uma página chamada Default.aspx na pasta App_LocalResources, você poderá criar os seguintes arquivos:

• padrão.aspx.resx.Isso é o arquivo de recurso local padrão (o arquivo de recurso de fallback) se não for encontrada nenhuma correspondência linguagem.

• padrão.aspx.es.resx.Este é o arquivo de recurso para espanhol, sem informações de cultura.

• padrão.aspx.es-mx.resx.Este é o arquivo de recurso para Espanhol (México) especificamente.

• padrão.aspx.fr.resx.Este é o arquivo de recurso para francês, sem informações de cultura.

O nome de base do arquivo corresponde ao nome de arquivo de página, seguido por um nome, idioma e cultura e terminando com a extensão .resx.Para obter uma lista dos nomes de cultura, consulte CultureInfo.

Localizando Recursos de Script de Cliente

O suporte a localização para script de cliente ASP.NET AJAX cria a localização na base do modelo de ASP.NET 2.0.Nesse modelo, você incorpora arquivos de script e recursos de script localizado em uma organização hub e spoke de conjuntos de módulos (conjuntos de satélite).Você pode então seletivamente usar esses scripts incorporados do cliente e recursos para regiões e idiomas específicos.Esse modelo permite que um único código base suporte diversas culturas.Também há suporte para arquivos script localizados que são fornecidos como arquivos .js no disco.ASP.NET pode gerar scripts de cliente e recursos localizados automaticamente para idiomas e regiões específicos.

Para obter mais informações, consulte os seguintes tópicos:

• Visão geral da Localização de Recursos para Componentes de Bibliotecas

• Demonstra Passo a passo: A incorporação de recursos localizados de um arquivo JavaScript

• Demonstra Passo a passo: Globalizando uma data usando o script de cliente

Escolhendo entre arquivos de recursos globais e locais

Você pode usar qualquer combinação de arquivos de recursos globais e locais no aplicativo da Web.Geralmente, você adiciona recursos a um arquivo de recurso global sempre que desejar compartilhar recursos entre páginas.Também recursos em arquivos de recursos globais são fortemente tipados para sempre que desejar acessar os arquivos de forma programática.

No entanto, arquivos de recursos globais podem ficar maiores, se você armazenar todos os recursos localizados neles.Arquivos de recursos globais também podem ser mais difícil de gerenciar, se mais de um desenvolvedor estiver funcionando em páginas diferentes mas em um único arquivo de recurso.

Arquivos de Recurso local facilitam o gerenciamento de recursos para uma única página da Web do ASP.NET.Mas você não pode compartilhar recursos entre páginas.Além disso, você pode criar muitos arquivos de recurso local, se você tiver muitas páginas que devem ser localizadas em vários idiomas.Se os sites forem grandes com vários idiomas e pastas, recursos locais rapidamente podem expandir o número de conjuntos de módulos (assemblies) no domínio do aplicativo.

Quando você faz uma alteração para arquivo de recurso um padrão, local ou global, ASP.NET recompila os recursos e reinicia o aplicativo ASP.NET.Isso pode afetar o desempenho geral do seu site.Adicionar arquivos de recurso satélite não causa uma recompilação de recursos, mas o aplicativo ASP.NET será reiniciado.

Observação:
Recursos vinculados têm suporte somente nos arquivos de recursos Globais.

Trabalhando com recursos em páginas da Web

Depois de criar arquivos de recurso, você pode usá-los em páginas Web ASP.NET.Normalmente você usa os recursos para preencher os valores de propriedades dos controles na página.Por exemplo, convém usar os recursos para definir a propriedade Text de um controle Button, em vez de embutir código na propriedade como uma string específica.

Para usar recursos para definir valores de propriedades de controles, você poderá usar localização implícita ou localização explícita, da seguinte forma:

• Localização implícita trabalha com recursos locais e permite que você defina propriedades de controle para recursos correspondentes automaticamente.

• Localização explícita permite que você use uma expressão de recurso para definir uma propriedade de controle a um recurso específico em um arquivo local ou global de recursos.

Localização Implícita com recursos locais

Se você tiver criado arquivos de recursos locais para uma página específica, você pode usar localização implícita para preencher os valores de propriedade para um controle de arquivo de recurso.Em localização implícita, ASP.NET lê um arquivo de recursos e corresponde com recursos para valores de propriedade.

Para usar localização implícita, você deve usar uma convenção de nomes para recursos em um arquivo de recurso local que utiliza o padrão a seguir:

Chave.Propriedade

Por exemplo, se você estiver criando recursos para um controle Button chamado Button1, você pode criar os seguintes pares chave/valor no arquivo de recurso local:

Button1.Text
Button1.BackColor
Label1.Text

Você pode usar qualquer nome para Chave, mas Propriedade deve corresponder a uma propriedade do controle que você está localizando.

Na página, você usa um atributo meta especial na marcação para o controle para especificar a localização implícita.Não é necessário especificar explicitamente quais propriedades são localizadas.Um controle Button que esteja configurado para localização implícita pode assemelhar-se ao seguinte:

<asp:Button ID="Button1"  Text="DefaultText" 
    meta:resourcekey="Button1" />

O valor resourcekey corresponde a uma chave no arquivo de recurso correspondente.Em tempo de execução, ASP.NET corresponde a propriedades de recursos para controlar usando o rótulo de controle como o resourcekey.Se um valor da propriedade for definido no arquivo de recurso, ASP.NET substitui o valor de recursos para a propriedade.

Localização explícita

Como alternativa, você pode usar localização explícita, onde você utiliza uma expressão de recursos.Diferentemente da localização implícita, você deve utilizar uma expressão de recurso para cada propriedade que você deseja definir.

Um controle Button que esteja configurado para definir a propriedade Text de um arquivo de recurso global pode se parecer com o seguinte:

<asp:Button ID="Button1"  
    Text="<%$ Resources:WebResources, Button1Caption %>" />

A expressão de recurso assume a forma a seguir, onde Class é opcional, a menos que o recurso é um arquivo global, e ResourceID é necessário:

<%$Recursos:Classe,Identificação de Recurso%>

O valor Class identifica o arquivo de recurso a ser usado quando você usa recursos globais.Quando arquivos .resx são compilados, o nome de arquivo base, sem extensões, é usado como o nome de classe do assembly resultante, explicitamente.Se você quiser usar os recursos de um arquivo de recurso local (aquele que corresponde ao nome de página atual), não é necessário incluir o nome da classe.Isso ocorre porque ASP.NET compara a classe da página com a classe do recurso.

O Valor ResourceID é o identificador do recurso para ler.No exemplo anterior, a propriedade Text para o botão é lida do arquivo de recurso global WebResources.resx o (ou a versão apropriada localizada).Nesse arquivo, ASP.NET usa o valor para o recurso com o identificador Button1Caption e para a própria página.Para definir as propriedades da página, você pode usar expressões de recurso na diretiva @ Page.

Você pode especificar uma expressão explícita de recurso ou uma expressão implícita de recursos para um controle, mas não ambos.A seguinte sintaxe declarativa em um controle Button causa um erro do analisador:

<asp:Button ID="Button1" 
             
            meta:resourcekey="Button1Resource1"
            Text="<%$ Resources:WebResources, Button1Caption %>" />

Nesse exemplo, um arquivo implícito de recurso local (aquele que corresponde ao nome de página atual) é especificado assim como um arquivo de recurso explícito chamado WebResources.Para impedir um erro do analisador para esse controle, remova uma das expressões de recursos.

Localizando texto estático

Se uma página incluir texto estático, você pode usar a localização do ASP.NET, incluindo-a em um controle Localize e, em seguida, usando localização explícita para definir o texto estático.O controle Localize não processa nenhuma marcação; sua única função é atuar como um espaço reservado para texto localizado.O controle Localize pode ser editado no modo de exibição Design, não apenas na grade de propriedade.Em tempo de execução, o ASP.NET trata o controle Localize como um controle Literal.Por exemplo, a página pode incluir o código a seguir:

<h1>
  <asp:Localize runat=server 
    ID="WelcomeMessage" 
    Text="Welcome!" meta:resourcekey="LiteralResource1" />
</h1>
<br />
<br />
<asp:Localize 
    ID="NameCaption"
    Text="Name: " meta:resourcekey="LiteralResource2" />
<asp:TextBox  ID="TextBox1" 
    meta:resourcekey="TextBox1Resource1" />

Observação de segurança:
Este exemplo tem uma caixa de texto que aceita entrada do usuário, que é uma ameaça potencial de segurança.Por padrão, páginas Web ASP.NET validam se as entradas de usuário não incluem scripts ou elementos HTML.Para obter mais informações, consulte Visão Geral de Scripts Maliciosos.

Localização Implícita nos Modelos

Em controles modelo, como os controles DataList,GridView, e Wizard, você localiza propriedades de estilo modelo acessando as propriedades por meio da expressão implícita do recurso do controle pai.Não é possível usar uma expressão implícita de recursos no próprio modelo.

Para localizar valores de propriedades em um modelo, use o atributo meta e uma chave de recurso para o controle ao qual pertence o modelo.Em seguida, use a sintaxe Property.Subproperty ou Property-Subproperty no arquivo de recurso.Por exemplo, a seguinte sintaxe declarativa é válida para um controle Wizard:

<asp:Wizard ID="Wizard1" 
     
    meta:resourcekey="Wizard1Resource1">
  <NavigationStyle 
    BorderWidth="<%$ resources:navBorderWidth %>"/>
  <WizardSteps>
    <asp:WizardStep ID="WizardStep1" 
       
      Title="Step 1" 
      meta:resourcekey="WizardStep1Resource1">
    </asp:WizardStep>
  </WizardSteps>
</asp:Wizard>

Os seguintes pares chave/valor no arquivo de recurso local podem ser usados para o exemplo anterior:

Wizard1Resource1.NavigationStyle.BackColor, Red
navborderWidth, 5

Ou os seguintes pares chave/valor podem ser usados:

Wizard1Resource1.NavigationStyle-BackColor, Red
navborderWidth, 5

Você pode usar uma expressão explícita de recursos para a propriedade NavigationStyle do controle Wizard no exemplo anterior.A expressão explícita do recurso omite o nome Class de forma que recursos de um arquivo de recurso local sejam usados.

Para obter mais informações sobre controles modelo de servidor, consulte Modelos de controles servidores web ASP.NET.

Selecionando arquivos de recurso para idiomas diferentes

Quando uma página é executada, o ASP.NET seleciona a versão do arquivo de recurso que melhor coincide com a configuração atual UICulture para a página .Se não houver correspondência, o ASP.NET usará recursos de retorno para obter um recurso.Por exemplo, se você estiver executando a página Default.aspx e a propriedade atual UICulture estiver definida como es (Espanhol), ASP.NET usará a versão compilada do arquivo de recurso local Default.aspx.es.resx.

O ASP.NET pode definir as propriedades UICulture e Culture para a página para os valores de idioma e cultura que são passados pelo navegador.Como alternativa, você pode definir as propriedades UICulture e Culture explicitamente, de maneira declarativa ou em código.Você também pode definir os valores declarativamente nos arquivos Web.config.Para informações detalhadas, consulte Como: conjunto a cultura e UI Culture for ASP.NET Web página globalização.

Observação:

Você não deve confiar exclusivamente em Configurações do navegador para Definir informações idioma e cultura, porque os usuários podem estar usando um navegador em um computador diferente de seus próprios.Além disso, navegadores frequentemente comunicam somente informações de idioma sem uma configuração de cultura específica.Nesse caso, o servidor tem que deduzir uma cultura específica para formatar dados.Uma boa estratégia é permitir que os usuários selecionem um idioma explicitamente.

Trabalhar com recursos Programáticamente

Além de definir valores de recurso na marcação com expressões de recurso, você pode recuperar valores de recurso programaticamente.Você pode fazer isso se o valor do recurso não for conhecido em tempo de design ou se você desejar definir o valor dos recursos com base em um valor obtido em tempo de execução.Para obter mais informações, consulte Como: Recuperar valores de recurso por programação.

Consulte também

Outros recursos

Globalização e Localização no ASP.NET