Classe CultureAndRegionInfoBuilder

Este artigo fornece observações complementares à documentação de referência para esta API.

Observação

A CultureAndRegionInfoBuilder classe é útil apenas para sistemas operacionais Windows. Os arquivos .nlp gerados não são suportados em sistemas operacionais que não sejam Windows. Além disso, mesmo no Windows, os arquivos .nlp gerados são suportados apenas no .NET Framework (ou no .NET Core ao usar o modo de globalização NLS).

A classe CultureInfo contém informações específicas da cultura, como o idioma associado, o dialeto, o país/região, o calendário e as convenções culturais. Essa classe também fornece instâncias específicas da cultura das classes DateTimeFormatInfo, NumberFormatInfo, CompareInfo e TextInfo, que são necessárias para operações específicas da cultura, como colocação de maiúsculas e minúsculas, formatação e análise de datas e números e comparação de cadeias de caracteres.

Por padrão, o .NET dá suporte a objetos CultureInfo que representam um conjunto predefinido de culturas. Para obter uma lista dessas culturas disponíveis em sistemas Windows, confira a coluna Marca de idioma na lista de nomes de idioma/região compatíveis com o Windows. Os nomes de cultura seguem o padrão definido pelo BCP 47. A classe CultureAndRegionInfoBuilder permite que você crie uma cultura personalizada completamente nova ou que substitua uma cultura predefinida. Quando uma cultura personalizada é instalada e registrada em um computador específico, ela se torna indistinguível de objetos CultureInfo predefinidos e pode ser instanciada e usada da mesma forma que esses objetos.

Importante

A CultureAndRegionInfoBuilder classe é encontrada em um assembly chamado sysglobl.dll. Para compilar com êxito o código que usa esse tipo, você deve adicionar uma referência a sysglobl.dll.

Uma cultura personalizada pode ser registrada em um computador somente por um usuário que tenha direitos administrativos nesse computador. Consequentemente, os aplicativos normalmente não criam e instalam culturas personalizadas. Em vez disso, você pode usar a classe CultureAndRegionInfoBuilder para criar uma ferramenta de finalidade especial que um administrador pode usar para criar, instalar e registrar uma cultura personalizada. Depois que a cultura personalizada for registrada em um computador, você poderá usar a classe CultureInfo em seu aplicativo para criar instâncias da cultura personalizada da mesma forma que faria para uma cultura predefinida.

Se você analisar as cadeias de caracteres de data e hora geradas para uma cultura personalizada, deverá usar o método DateTime.ParseExact ou DateTime.TryParseExact em vez do método DateTime.Parse ou DateTime.TryParse para aumentar a probabilidade de que a operação de análise seja bem-sucedida. Uma cadeia de caracteres de data e hora para uma cultura personalizada pode ser complicada e, portanto, difícil de analisar. Os métodos Parse e TryParse tentam analisar uma cadeia de caracteres com vários padrões de análise implícitos, todos os quais podem falhar. O método TryParseExact, por outro lado, requer que o aplicativo designe explicitamente um ou mais padrões exatos de análise que provavelmente serão bem-sucedidos.

Definir e criar uma cultura personalizada

Você usa a classe CultureAndRegionInfoBuilder para definir e nomear uma cultura personalizada. A cultura personalizada pode ser uma cultura totalmente nova, uma nova cultura baseada em uma cultura existente (ou seja, uma cultura complementar) ou uma cultura que substitui uma cultura .NET existente. Em cada caso, as etapas básicas são as mesmas:

1. Instancie um objeto CultureAndRegionInfoBuilder chamando seu construtor CultureAndRegionInfoBuilder(String, CultureAndRegionModifiers). Para substituir uma cultura existente, passe o nome dessa cultura e o valor de enumeração CultureAndRegionModifiers.Replacement para o construtor. Para criar uma nova cultura ou uma cultura complementar, passe um nome de cultura exclusivo e o valor de enumeração CultureAndRegionModifiers.Neutral ou CultureAndRegionModifiers.None.

   Observação

   Se você usar o valor de enumeração CultureAndRegionModifiers.Replacement para instanciar um objeto CultureAndRegionInfoBuilder, as propriedades do objeto CultureAndRegionInfoBuilder serão preenchidas automaticamente com valores do objeto CultureInfo a serem substituídos.

2. Se você estiver criando uma cultura nova ou complementar:

   • Preencha as propriedades do objeto CultureAndRegionInfoBuilder chamando o método LoadDataFromCultureInfo e passando um objeto CultureInfo com valores de propriedade semelhantes ao seu novo objeto.
   • Preencha as propriedades regionais do objeto CultureAndRegionInfoBuilder chamando o método LoadDataFromRegionInfo e passando um objeto RegionInfo que representa a região de sua cultura personalizada.

3. Modifique as propriedades do objeto CultureAndRegionInfoBuilder conforme necessário.

4. Se você estiver planejando registrar a cultura personalizada em uma rotina separada, chame o método Save. Isso gera um arquivo XML que você pode carregar e registrar em uma rotina de instalação de cultura personalizada separada.

Registrar uma cultura personalizada

Se você estiver desenvolvendo um aplicativo de registro para uma cultura personalizada separada do aplicativo que cria a cultura, chame o método CreateFromLdml para carregar o arquivo XML que contém a definição da cultura personalizada e instanciar o objeto CultureAndRegionInfoBuilder. Para lidar com o registro, chame o método Register. Para que o registro seja bem-sucedido, o aplicativo que registra a cultura personalizada deve estar em execução com privilégios administrativos no sistema de destino; caso contrário, a chamada para Register gera uma exceção UnauthorizedAccessException.

Aviso

Os dados de cultura podem ser diferentes entre sistemas. Se você estiver usando a classe CultureAndRegionInfoBuilder para criar uma cultura personalizada uniforme em vários sistemas e estiver criando sua cultura personalizada carregando dados de objetos existentes CultureInfo e RegionInfo e personalizando-os, você deverá desenvolver dois utilitários diferentes. O primeiro cria a cultura personalizada e a salva em um arquivo XML. O segundo usa o método CreateFromLdml para carregar a cultura personalizada de um arquivo XML e registrá-la no computador de destino.

O processo de registro executa as seguintes tarefas:

• Cria um arquivo .nlp que contém as informações definidas no CultureAndRegionInfoBuilder objeto.
• Armazena o arquivo .nlp no diretório do sistema %windir%\Globalization no computador de destino. Isso permite que as configurações da cultura personalizada persistam entre as sessões. (O CultureAndRegionInfoBuilder método requer privilégios administrativos porque o arquivo .nlp é armazenado em um diretório do sistema.)
• Prepara o .NET para pesquisar o diretório do sistema %windir%\Globalization em vez de um cache interno na próxima vez que houver uma solicitação para criar sua nova cultura personalizada.

Quando uma cultura personalizada é registrada com êxito, ela é indistinguível das culturas predefinidas pelo .NET. A cultura personalizada fica disponível até que uma chamada para o método remova o CultureAndRegionInfoBuilderarquivo .nlp do computador local.

Criar uma instância de uma cultura personalizada

Você pode criar uma instância da cultura personalizada de uma das seguintes maneiras:

• Invocando o construtor CultureInfo.CultureInfo com o nome da cultura.
• Chamando o método CultureInfo.CreateSpecificCulture com o nome da cultura.
• Chamando o método CultureInfo.GetCultureInfo com o nome da cultura.

Além disso, a matriz de objetos CultureInfo que é retornada pelo método CultureInfo.GetCultures inclui a cultura personalizada.