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

Artigo
10/15/2014

A localização é o processo de personalização de um aplicativo para um idioma ou cultura específico.A funcionalidade AJAX no ASP.NET oferece suporte aos seguintes modelos de localização para trabalhar com script de cliente:

Os modelos de recursos .NET Framework, com suporte expandido para recursos localizados que estão associados com os componentes ECMAScript (JavaScript).Nesse modelo, você incorpora arquivos de script e recursos de script localizados em uma organização hub e spoke de conjuntos de módulos (ou seja, você usa conjunto de módulos satélites).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.
Arquivos JavaScript Estáticos (autônomos) no disco.Nesse modelo, arquivos localizados são agrupados em um único diretório como arquivos .js em vez de incorporados em um conjunto de módulos (assembly).
Atualizando scripts e recursos de script incorporados em um conjunto de módulos (assembly) usando arquivos JavaScript estáticos.Esse modelo permite que você forneça suporte adicional de localização para scripts e recursos incorporados sem exigir alterações no conjunto de módulos original.

Este tópico contém as informações a seguir:

Cenários
Segundo plano
Localização de Scripts de Cliente e Recursos de Script em Conjuntos de Módulos (assemblies)
Localizando Arquivos de Script Estáticos e Seus Recursos
Usando ScriptManager para Gerenciar Scripts em uma Localização Central
Exemplos de código
Referência de Classe

Cenários

Os recursos AJAX do ASP.NET ajudam a localização do cliente tanto para desenvolvedores de página como para desenvolvedores de componentes.Desenvolvedores de página geralmente localizam o seguinte:

Mensagens de exceção que são geradas a partir do AJAX do ASP.NET ou de componentes de bibliotecas, com base na configuração de idioma do navegador.
Interface do usuário para controles, como as sequências de caracteres para a propriedade Text de um controle Button.
Os valores para propriedades públicas de controles de servidor AJAX do ASP.NET.
Os valores para propriedades objetos de script de cliente e componentes, como componentes não visuais, comportamentos e controles.

Desenvolvedores de componente geralmente usam recursos de localização para o seguinte:

Localização de recursos mencionados no código em bibliotecas JavaScript (arquivos .js).Os recursos localizados podem ser implantados em instalações separadas, sem recriar o conjunto principal ou a biblioteca de script.
Expor propriedades localizável de controles de servidor que são mapeados para as propriedades dos objetos de cliente.

Segundo plano

Funcionalidade AJAX no ASP.NET é criada no modelo de localização do ASP.NET 2.0.Ele fornece suporte adicional para arquivos de script localizados que estiverem incorporados em um conjunto de módulos (assembly) ou forem arquivos .js estáticos no disco.

Se você não estiver familiarizado com o modelo de localização do ASP.NET, você encontrará informações sobre ele nos tópicos a seguir:

Localização de Scripts de Cliente e Recursos de Script em Conjuntos de Módulos (assemblies)

A funcionalidade AJAX do ASP.NET aproveita o modelo de recurso .NET Framework para localização.Esse modelo usa uma organização hub e spoke para empacotar e implantar recursos localizados que podem ser atualizados aos poucos.O hub é o conjunto principal que contém o código executável não localizado.Ele inclui tanto código de servidor .NET Framework como qualquer código JavaScript em arquivos .js que estão incorporados como um recurso no conjunto de módulos (assembly).

O conjunto principal também pode conter os recursos para um única cultura, que é conhecida como a cultura Neutral ou Default.A cultura neutra é a cultura reserva utilizada pelo aplicativo.Ela é usado se nenhuma cultura for especificada ou se não houver nenhum recursos para a cultura especificada.

Recursos localizados para uma cultura normalmente são criados como pares nome/valor em arquivos .resx .(Esses arquivos .resx podem ser compilados em arquivos .resources.) O nome fornece acesso às informações no código, e o valor é o termo localizado (traduzido), imagem ou outro elemento para esse nome.Quando um conjunto de módulos (assembly) é criado, um tipo é gerado para o arquivo .resx na qual os nomes são expostos como campos que fornecem acesso programático aos valores.(Você especifica o nome desse tipo gerado como parte das propriedades do conjunto de módulos (assembly), conforme descrito posteriormente.)

No modelo hub e spoke, cada spoke conecta à um conjunto de módulos satélite que contém os recursos para uma única cultura.O conjunto de módulos satélite não contém qualquer código que é executado pelo servidor.Ele contém apenas o tipo gerado que fornece acesso programático aos valores do recurso para aquela cultura.

Esse modelo oferece os seguintes recursos:

Você pode adicionar recursos de culturas novas implantando novos conjuntos de módulos satélite após você já ter implantado um conjunto de módulos (assembly).O Desenvolvimento de recursos para culturas específicas pode exigir um tempo adicional.Esse modelo, portanto, permite que você libere seu aplicativo principal em primeiro lugar e fornecer recursos adicionais para culturas específicas posteriormente.
Você pode atualizar um conjunto de módulos satélite do aplicativo sem recompilar seu conjunto principal.
Um aplicativo deve carregar somente o conjunto de módulo satélite para uma determinada cultura, ao invés de descarregar e recarregar o conjunto principal.Isso pode reduzir significativamente o uso de recursos do sistema.

Para obter informações sobre como criar arquivos de recurso para o ASP.NET, consulte Como: Criar arquivos de recursos para sites da Web do ASP.NET e Localizando Páginas da Web ASP.NET Usando Recursos.

Para obter informações sobre como usar o .NET Framework arquivo de recurso (Resgen.exe) gerador ferramenta, consulte Recurso Arquivo Generator (Resgen.exe). Essa ferramenta converte arquivos .resx ou .txt para arquivos .Recursos binário que podem ser vinculados em módulos (assemblies).

Organizando Conjunto de Módulos Localizados Principal e Satélite

Você pode usar o modelo hub e spoke quando desejar localizar um aplicativo que inclui arquivos JavaScript (.js).Em geral, você organizar o conjunto de módulos como você faria em qualquer aplicativo ASP.NET que está localizado.

Para gerenciar os arquivos de JavaScript para um aplicativo ASP.NET com AJAX habilitado, você deve escrever um código de JavaScript para que ele não inclua sequências de caracteres ou outros elementos que devam ser localizados.Em vez disso, em qualquer lugar onde o código JavaScript deva usar valores localizados, você obtém um campo do tipo que é gerado por arquivo de recurso.

O conjunto principal normalmente inclui os seguintes elementos:

Os arquivos de JavaScript que executam as tarefas do aplicativo, e que são gravados para usar os recursos localizados em vez daqueles embutidos.O assembly opcionalmente pode incluir versões de depuração desses arquivos JavaScript.
Opcionalmente, os recursos (arquivo .resx ou .resources) para uma única cultura neutra, que atua como a reserva de cultura para o aplicativo.
Opcionalmente, qualquer versão de depuração dos recursos de cultura neutra.A versão de depuração de um arquivo de recurso inclui qualquer pares nome/valor extras que são necessários para as versões de depuração dos arquivos de JavaScript.

Um conjunto de módulos satélite normalmente inclui recursos localizados para uma única cultura para o aplicativo ASP.NET.(Nenhum conjunto de módulos satélite é necessário para a cultura de reserva.) Os recursos para uma única cultura são criados em um arquivo de recurso separado (arquivo .resx ou .resources) e, em seguida, compilados em um único conjunto de módulos satélite.

Observação:
ASP.NET permite que você criar um personalizado IU cultura e um personalizado nome de cultura.No entanto, geralmente nomes de cultura baseados em um código de linguagem ISO que consiste em de duas letras para um linguagem e duas letras maiúsculas para um Country ou região.Exemplos incluem es-MX (espanhol , M exico ), es-CO (espanhol , Colômbia ) e francês (fr-autoridade de certificação , Canadá ).Para obter uma lista completa de nomes de cultura, s consultar o System.Globalization.CultureInfo Visão geral da classe.

ASP.NET permite que você criar um personalizado IU cultura e um personalizado nome de cultura.No entanto, geralmente nomes de cultura baseados em um código de linguagem ISO que consiste em de duas letras para um linguagem e duas letras maiúsculas para um Country ou região.Exemplos incluem es-MX (espanhol , M exico ), es-CO (espanhol , Colômbia ) e francês (fr-autoridade de certificação , Canadá ).Para obter uma lista completa de nomes de cultura, s consultar o System.Globalization.CultureInfo Visão geral da classe.

Nomes de arquivos de script localizados embutidos

O seguinte convenção de nomenclatura é recomendada para arquivos de script localizados que são incorporados como recursos:

scriptname_noextension.[debug].[UI culture identifier].[resources|resx]

A versão de depuração de um arquivo inclui ".debug" no nome.O versão de lançamento não.

A tabela a seguir mostra exemplos deste convenção de nomenclatura.Os exemplos mostram uma versão de lançamento de uma de depuração de um arquivo de script incorporado.Eles também mostram a versão associada de lançamento e de depuração de recursos para esse arquivos de script.

Sample.js
Um versão de lançamento de um arquivo de script de cultura neutra, que é incorporado no conjunto principal.
Sample.debug.js
Um versão de depuração de um arquivo de script de cultura neutra, que é também incorporado no conjunto principal.
Sample.fr-FR.Resources
Um versão de lançamento de recursos que estão associados a arquivo de script SAMPLE.js, localizado para uma cultura específica da interface do usuário.Esses recursos tornam-se parte do conjunto de módulos satélite.
Sample.debug.fr-FR.resources
Recursos específicos de depuração associados ao arquivo de script SAMPLE.debug.js, localizado para uma cultura específica da interface do usuário.Esses recursos tornam-se parte do conjunto satélite que também inclui o arquivo Sample.fr-FR.resources.

Esta convenção de nomenclatura não é estritamente necessária para arquivos de script que são incorporados em conjuntos de módulos (assemblies) ou arquivos de recurso.Isso ocorre porque o mapeamento entre o tipo gerado para o recurso e o nome do recurso é realizado usando um atributo de conjunto de módulos (assembly).

Localizando Recursos de Script de Depuração

Se você estiver trabalhando em modo de depuração, no tempo de execução o ASP.NET combina a versão de lançamento dos recursos para os arquivos de script com os recursos adicionais de depuração.Em seguida, ele envia a combinação resultante para o navegador.Portanto, quando você cria arquivos de recurso para versões de depuração de scripts, você precisará definir apenas os pares nome/valor que não estiverem incluídos na versão dos arquivos de script de recursos.Por convenção, as versões de depuração de script de recursos de script usam o mesmo nome que as suas contraparte lançadas mas incluem ".debug" após o nome do arquivo de script.

Especificando Atributos de Montagem para Scripts Localizados e Recursos Localizado Associados à Scripts

Para especificar como os arquivos de recurso são gerenciados quando um conjunto de módulos (assembly) é criado, você inclui atributos no arquivo AssemblyInfo (arquivo AssemblyInfo.vb ou AssemblyInfo.cs).

Observação:
Em Visual Studio, para projetos escritos em Visual Basic, o arquivo AssemblyInfo.vb está a Meu projeto nó of O gerenciador de soluções.Se você não vir quaisquer arquivos no nó Meu Projeto, faça o seguinte: no menu Projeto, clique em Mostrar todos os arquivos.Para projetos escritos em C#, o arquivo AssemblyInfo.cs está no nó Propriedades do Gerenciador de Soluções.

Em Visual Studio, para projetos escritos em Visual Basic, o arquivo AssemblyInfo.vb está a Meu projeto nó of O gerenciador de soluções.Se você não vir quaisquer arquivos no nó Meu Projeto, faça o seguinte: no menu Projeto, clique em Mostrar todos os arquivos.Para projetos escritos em C#, o arquivo AssemblyInfo.cs está no nó Propriedades do Gerenciador de Soluções.

No ASP.NET, você marca recursos para o aplicativo usando a classe WebResourceAttribute.Para incorporar arquivos JavaScript em um conjunto de módulos (assembly), você usa esse atributo para especificar os arquivos .js como um recurso da Web.

Para incluir arquivos de recursos para os arquivos incorporados JavaScript, você usa a classe ScriptResourceAttribute.Esse atributo identifica os recursos com base em texto especificamente como recursos para os arquivos de JavaScript.

Observação:
O ScriptResourceAttribute classe pode ser usada para identificar apenas recursos com base em texto para arquivos JavaScript. Para associar um arquivo de imagem localizado (binário) com uma cultura, armazene seu URL como um recurso localizado que script pode resolver e carregar.

O exemplo a seguir mostra como usar atributos de conjunto de módulos (Assembly) para identificar scripts incorporados e seus recursos de script associado.

' Indicates that neutral fallback resources are retrieved from 
' the main assembly named MainAssembly.
<assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)>

' Defines embedded scripts as Web resources.
<assembly:WebResource("Sample.js", "text/javascript")>
<assembly:WebResource("Sample.debug.js", "text/javascript")>

' Defines the script resources for the scripts and their types.
<assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")>
<assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")>

// Indicates that neutral fallback resources are retrieved from 
// the main assembly named MainAssembly.

[assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)]

// Defines embedded scripts as Web resources.
[assembly:WebResource("Sample.js", "text/javascript")]
[assembly:WebResource("Sample.debug.js", "text/javascript")]

// Defines the script resources for the scripts and their types.
[assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")]
[assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")]

Este exemplo, um assembly principal chamado MainAssembly contém uma versão de lançamento incorporado de um arquivo de script de cliente nomeado Sample.js. O assembly também contém a versão de depurar correspondente denominada Sample.depurar.js.sistema autônomo arquivos .js são identificados sistema autônomo recursos pelo WebResourceAttribute atributo.

O atributo NeutralResourcesLanguageAttribute do conjunto de módulos (assembly) é usado para especificar o conjunto principal como cultura de reserva.Para obter mais informações, consulte **Idiomas de recursos neutros** para localização e a visão geral da classe System.Resources.NeutralResourcesLanguageAttribute .

Os recursos usados pelos arquivos de script são definidos pelo uso do atributo ScriptResourceAttribute.Os arquivos Sample.resources e Sample.debug.resources contêm valores de recursos para os arquivos, Sample.js e Sample.debug.js, respectivamente.

Um tipo chamado Sample.Res é gerado para a versão de lançamento e de depuração dos recursos de script.Este é o tipo que o código JavaScript usa para acessar valores localizadas.Tanto para o modo de lançamento como o modo de depuração, o processo de compilação cria somente um único tipo.Em modo de depuração os recursos para o versão de lançamento são combinados com os recursos adicionais para a versão de depuração.

Para obter mais informações sobre como criar arquivos de informações do conjunto de módulos e o metadados do conjunto que são necessários para conjuntos de módulos (assemblies) versionados, consulte Como: Criar conjuntos com versão atualizada para sites da Web pré-compilados.

Localizando Arquivos de Script Estáticos e Seus Recursos

Você pode organizar uma biblioteca de script como arquivos estáticos de script localizados (arquivos .js) no disco em vez de incorporar os arquivos de script em conjuntos de módulos (assemblies).Desenvolvedores da página podem fazer referência aos arquivos de script por meio da classe ScriptReferenceCollection.

No modelo de arquivos estáticos de script, não há arquivos .resx ou .resources separados que podem ser automaticamente gerenciados como recursos para arquivos JavaScript.Em vez disso, existem apenas arquivos .js, um para cada combinação de cultura e localidade da interface do usuário.Na verdade, cada arquivo .js representa uma versão específicas da localidade do código completo do JavaScript.Uma maneira comum para gerenciar arquivos script localizado nesse modelo é usar a mesma lógica de JavaScript em cada arquivo .js.Como no modelo de conjuntos incorporados, o código JavaScript chama um tipo para recuperar valores de recurso localizado.A diferença é que você deve fornecer o tipo que contém os valores localizados — ele não é gerado para você.Por exemplo, o .js para cada localidade pode incluir o código do aplicativo e uma classe que define os campos que armazenam valores localizadas.Em cada arquivo .js, essa classe contém valores em um idioma diferente.

Observação:
Em o estático modelo de arquivo de script o código JavaScript do aplicativo em .js podem arquivos Obter Limite de sincronização com o código em um arquivo JavaScript incorporado .Isso é porque cada arquivo de script inclui uma cópia do o código .Para evitar version - controle problema com s Duplicar d código , Você pode manter uma única cópia da JavaScript fonte arquivos e criar tipos de recurso localizado em arquivos separados.Você pode em seguida gerar o arquivos combinados finais durante a seu aplicativo processo de compilação .

Em o estático modelo de arquivo de script o código JavaScript do aplicativo em .js podem arquivos Obter Limite de sincronização com o código em um arquivo JavaScript incorporado .Isso é porque cada arquivo de script inclui uma cópia do o código .Para evitar version - controle problema com s Duplicar d código , Você pode manter uma única cópia da JavaScript fonte arquivos e criar tipos de recurso localizado em arquivos separados.Você pode em seguida gerar o arquivos combinados finais durante a seu aplicativo processo de compilação .

Arquivos estático de script localizados são mapeados para a cultura da interface do usuário, incluindo o nome da cultura da interface do usuário como parte de nome de arquivo, como com recursos incorporados em um conjunto de módulos (assembly).Por exemplo, um arquivo de script de cliente incorporado que é de cultura neutra para francês seria nomeado Sample.fr.js e um recurso JavaScript específico de cultura para Francês (Canadá) seria nomeado Sample.fr-CA.js.

Scripts de depuração localizadas no Modelo de Arquivo Estáticos de Script

No modelo e arquivo estático de script, recursos localizado que um script se refere são geralmente definidos como um tipo em um único arquivo .js.Uma versão de depuração de um arquivo de script é organizada da mesma forma, com recursos versão localizada e recursos adicionais de depuração definidos como um tipo em um único arquivo.Versões de depuração de scripts usam o mesmo nome que a versão de lançamento correspondente, mas incluem ".debug" após o nome.

Usando ScriptManager para Gerenciar Scripts

Você pode usar o controle ScriptManager para gerenciar scripts estáticos que estão localizados em uma pasta central no disco.Para fazer isso, colocar todas as versões dos arquivos de script em uma pasta, que inclui versões de lançamento e de depuração de todos os arquivos localizados.O exemplo seguinte mostra o layout de uma estrutura de diretórios para um biblioteca de arquivos de script estáticos.

SampleNamespace/

1.0.0.0/

Sample.js

Sample.debug.js

Sample.de-DE.js

Sample.debug.de-DE.js

Sample.fr-FR.js

Sample.debug.fr-FR.js

Nesse exemplo, todos os arquivos de script que estão em uma pasta que é chamada usando a versão da Biblioteca de Script (1.0.0.0).Esta pasta de versão específica está em uma pasta que está denominada após o espaço de nome da biblioteca.Organizar uma biblioteca de script em pastas por namespace e versão pode fornecer algum controle de versão para sua biblioteca.Ele também pode ajudar você evitar colisões de nome de script entre bibliotecas.Além disso, ele permite que os clientes de sua biblioteca identifiquem quais biblioteca e versão os arquivos pertencem.

Entendendo o Papel do Controle ScriptManager na Localização

O controle ScriptManager fornece a seguinte funcionalidade para o uso de scripts localizados e recursos de script:

Permite que você defina quais culturas da interface do usuário são suportadas, que inclui culturas personalizadas da interface do usuário.
Interpreta os atributos do conjunto de módulos de uma cultura específica e detecta automaticamente a cultura da interface do usuário do navegador (se houver algum).Em seguida, ele lê os scripts localizada ou de reserva e recursos do conjunto de módulos.No modo de depuração, ele tenta carregar um recurso de script que contém o nome de cultura da interface do usuário apropriado e a sequência de caracteres ".debug" no nome de arquivo, como Sample.debug.fr-FR.resources.
Gera URLs que apontam para os scripts apropriados e aos seus recursos localizados.Para segurança adicional, ele criptografa as URLs.
Determina se um script ou recurso de script será compactado, com base em um parâmetro do URL gerado.
Adiciona um carimbo de data /hora ao conjunto que contém scripts incorporados para que o navegador não armazene os scripts em cache indefinidamente.

Para obter mais informações, consulte a visão geral da classe ScriptManager.

O exemplo a seguir mostra a parte um página da Web que usa o controle ScriptManager para registrar um controle de cliente que está localizado em um conjunto de módulos (assembly).O script incorporado é registrado pelo uso das propriedades Assembly e Name.

<%@ Register TagPrefix="Samples" Namespace="DemoControls" 
  Assembly=" SampleAssembly" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head >
  <title>ScriptReference</title>
</head>
<body>
  <form id="form1" >
    <div>
      <asp:ScriptManager ID="ScriptManager1" >
        <Scripts>
          <asp:ScriptReference Assembly="SampleAssembly"
              Name="DemoControls.SampleControl.js" />
        </Scripts>
      </asp:ScriptManager>

      <!-- Additional markup here. -->

    </div>
  </form>
</body>

Exemplos de código

As seções a seguir incluem o código exemplos que mostram como trabalhar com arquivos JavaScript e recursos.

Tópicos de demonstração e explicação passo a passo

Referência de Classe

A tabela a seguir lista as classes principais que são usadas para localização de componente das bibliotecas.

ScriptManager
Gerencia os componentes AJAX, renderização parcial da página, solicitações de cliente e respostas do servidor em páginas do servidor ASP.NET.
ScriptReference
Fornece APIs para registrar arquivos JavaScript para uso em um página da Web, os arquivos que são incorporados em um conjunto de módulos (assembly) ou que estão no disco.
ScriptReferenceCollection
Fornece acesso a objetos ScriptReference que representam arquivos script de cliente.

Consulte também

Compartilhar via