Globalização e ICU do .NET

  • Artigo

Antes do .NET 5, as APIs de globalização do .NET usavam diferentes bibliotecas subjacentes em diferentes plataformas. No Unix, as APIs usaram Componentes Internacionais para Unicode (ICU) e, no Windows, usaram o NLS (National Language Support). Isso resultou em algumas diferenças comportamentais em um várias APIs de globalização ao executar aplicativos em diferentes plataformas. Diferenças de comportamento eram evidentes nessas áreas:

  • Culturas e dados de cultura
  • Invólucro de cadeia de caracteres
  • Classificação e pesquisa
  • Chaves de classificação
  • Normalização de cadeia de caracteres
  • Suporte a nomes de domínio internacionalizados (IDN)
  • Nome de exibição de fuso horário no Linux

A partir do .NET 5, os desenvolvedores têm mais controle sobre qual biblioteca subjacente é usada, permitindo que os aplicativos evitem diferenças entre plataformas.

Observação

Os dados de cultura que impulsionam o comportamento da biblioteca de UTI geralmente são mantidos pelo Common Locale Data Repository (CLDR), não pelo runtime.

ICU no Windows

Agora, o Windows incorpora uma versão icu.dll pré-instalada como parte de seus recursos que é automaticamente aplicada a tarefas de globalização. Essa modificação permite que o .NET aproveite essa biblioteca de ICU para seu suporte à globalização. Nos casos em que a biblioteca de ICU não está disponível ou não pode ser carregada, como é o caso das versões mais antigas do Windows, o .NET 5 e as versões subsequentes são revertidos para usar a implementação baseada em NLS.

A tabela a seguir mostra quais versões do .NET são capazes de carregar a biblioteca de ICU em diferentes versões de cliente e servidor do Windows:

Versão do .NET Versão do Windows
.NET 5 ou .NET 6 Cliente Windows 10 versão 1903 ou posterior
.NET 5 ou .NET 6 Windows Server 2022 ou posterior
.NET 7 ou posterior Cliente Windows 10 versão 1703 ou posterior
.NET 7 ou posterior Windows Server 2019 ou posterior

Observação

O .NET 7 e versões posteriores têm a capacidade de carregar a ICU em versões mais antigas do Windows, ao contrário do .NET 6 e .NET 5.

Observação

Mesmo ao usar a ICU, os membros CurrentCulture, CurrentUICulture e CurrentRegion ainda usam APIs do sistema operacional Windows para respeitar as configurações do usuário.

Diferenças de comportamento

Se você atualizar seu aplicativo para usar o .NET 5 ou posterior como destino, poderá ver alterações em seu aplicativo mesmo que não perceba que está usando instalações de globalização. Esta seção lista uma das alterações comportamentais que você pode ver, mas há outras também.

String.IndexOf

Considere o código a seguir que chama String.IndexOf(String) para localizar o índice do caractere nulo \0 em uma cadeia de caracteres.

const string greeting = "Hel\0lo";
Console.WriteLine($"{greeting.IndexOf("\0")}");
Console.WriteLine($"{greeting.IndexOf("\0", StringComparison.CurrentCulture)}");
Console.WriteLine($"{greeting.IndexOf("\0", StringComparison.Ordinal)}");
  • No .NET Core 3.1 e versões anteriores no Windows, o snippet é imprime 3 em cada uma das três linhas.
  • Para .NET 5 e versões posteriores em execução nas versões do Windows listadas na tabela de seção ICU no Windows, o snippet é impresso 0, 0, e 3 (para a pesquisa ordinal).

Por padrão, String.IndexOf(String) executa uma pesquisa linguística com reconhecimento de cultura. A UTI considera que o caractere nulo \0 é um caractere de peso zero e, portanto, o caractere não é encontrado na cadeia de caracteres ao usar uma pesquisa linguística no .NET 5 e posterior. No entanto, o NLS não considera o caractere nulo \0 como um caractere de peso zero, e uma pesquisa linguística no .NET Core 3.1 e anterior localiza o caractere na posição 3. Uma pesquisa ordinal localiza o caractere na posição 3 em todas as versões do .NET.

Você pode executar as regras de análise de código CA1307: especifique StringComparison para clareza e CA1309: use o StringComparison ordinal para localizar sites de chamada em seu código em que a comparação de cadeia de caracteres não é especificada ou não é ordinal.

Para obter mais informações, consulte Alterações de comportamento ao comparar cadeias de caracteres no .NET 5+.

String.EndsWith

const string foo = "abc";

Console.WriteLine(foo.EndsWith("\0"));
Console.WriteLine(foo.EndsWith("c"));
Console.WriteLine(foo.EndsWith("\0", StringComparison.CurrentCulture));
Console.WriteLine(foo.EndsWith("\0", StringComparison.Ordinal));
Console.WriteLine(foo.EndsWith('\0'));

Importante

No .NET 5+ em execução nas versões do Windows listadas na tabela ICU no Windows, o trecho de código anterior imprime:

True
True
True
False
False

Para evitar esse comportamento, use a sobrecarga de parâmetro char ou StringComparison.Oridinal.

String.StartsWith

const string foo = "abc";

Console.WriteLine(foo.StartsWith("\0"));
Console.WriteLine(foo.StartsWith("a"));
Console.WriteLine(foo.StartsWith("\0", StringComparison.CurrentCulture));
Console.WriteLine(foo.StartsWith("\0", StringComparison.Ordinal));
Console.WriteLine(foo.StartsWith('\0'));

Importante

No .NET 5+ em execução nas versões do Windows listadas na tabela ICU no Windows, o trecho de código anterior imprime:

True
True
True
False
False

Para evitar esse comportamento, use a sobrecarga de parâmetro char ou StringComparison.Oridinal.

TimeZoneInfo.FindSystemTimeZoneById

A ICU fornece a flexibilidade para criar instâncias TimeZoneInfo usando IDs de fuso horário IANA, mesmo quando o aplicativo está em execução no Windows. Da mesma forma, você pode criar instâncias TimeZoneInfo com IDs de fuso horário do Windows, mesmo quando executadas em plataformas que não sejam do Windows. No entanto, é importante observar que essa funcionalidade não está disponível ao usar o modo NLS ou o modo invariável de globalização.

APIs dependentes da ICU

O .NET introduziu APIs que dependem da ICU. Essas APIs só podem ser bem-sucedidas ao usar a ICU. Estes são alguns exemplos:

Nas versões do Windows listadas na tabela de seção ICU no Windows, as APIs mencionadas terão êxito de forma consistente. No entanto, em versões mais antigas do Windows, essas APIs falharão consistentemente. Nesses casos, você pode habilitar o recurso de ICU local do aplicativo para garantir o sucesso dessas APIs. Em plataformas que não sejam do Windows, essas APIs sempre terão êxito, independentemente da versão.

Além disso, é crucial que os aplicativos garantam que elas não estejam em execução no modo invariável de globalização ou no modo NLS para garantir o sucesso dessas APIs.

Usar NLS em vez de ICU

O uso da ICU em vez do NLS pode resultar em diferenças comportamentais com algumas operações relacionadas à globalização. Para voltar a usar o NLS, um desenvolvedor pode recusar a implementação da ICU. Os aplicativos podem habilitar o modo invariável usando um dos seguintes métodos:

  • No arquivo de projeto:

    <ItemGroup>
  <RuntimeHostConfigurationOption Include="System.Globalization.UseNls" Value="true" />
</ItemGroup>

  • No arquivo runtimeconfig.json:

    {
  "runtimeOptions": {
     "configProperties": {
       "System.Globalization.UseNls": true
      }
  }
}

  • Definindo a variável de ambiente DOTNET_SYSTEM_GLOBALIZATION_USENLS para o valor true ou 1.

Observação

Um valor definido no projeto ou no arquivo runtimeconfig.json tem precedência sobre a variável de ambiente.

Para obter mais informações, consulte Configurações de runtime.

Determinar se seu aplicativo está usando a ICU

O snippet de código a seguir pode ajudá-lo a determinar se seu aplicativo está em execução com bibliotecas de ICU (e não NLS).

public static bool ICUMode()
{
    SortVersion sortVersion = CultureInfo.InvariantCulture.CompareInfo.Version;
    byte[] bytes = sortVersion.SortId.ToByteArray();
    int version = bytes[3] << 24 | bytes[2] << 16 | bytes[1] << 8 | bytes[0];
    return version != 0 && version == sortVersion.FullVersion;
}

Para determinar a versão do .NET, use RuntimeInformation.FrameworkDescription.

ICU local do aplicativo

Cada versão de ICU pode trazer correções de bugs, bem como dados cldr (Common Locale Data Repository) atualizados que descrevem os idiomas mundiais. Migrar entre versões da ICU pode afetar sutilmente o comportamento do aplicativo quando se trata de operações relacionadas à globalização. Para ajudar os desenvolvedores de aplicativos a garantir a consistência em todas as implantações, o .NET 5 e versões posteriores permitem que aplicativos no Windows e no Unix carreguem e usem sua própria cópia de ICU.

Os aplicativos podem aceitar um modo de implementação de ICU local do aplicativo de uma das seguintes maneiras:

  • No arquivo de projeto, defina o valor RuntimeHostConfigurationOption apropriado:

    <ItemGroup>
  <RuntimeHostConfigurationOption Include="System.Globalization.AppLocalIcu" Value="<suffix>:<version> or <version>" />
</ItemGroup>

  • Ou no arquivo runtimeconfig.json, defina o valor de runtimeOptions.configProperties apropriado:

    {
  "runtimeOptions": {
     "configProperties": {
       "System.Globalization.AppLocalIcu": "<suffix>:<version> or <version>"
     }
  }
}

  • Ou definindo a variável de ambiente DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU para o valor <suffix>:<version> ou <version>.

    <suffix>: sufixo opcional de menos de 36 caracteres de comprimento, seguindo as convenções de empacotamento de ICU pública. Ao criar uma ICU personalizada, você pode personalizá-la para produzir os nomes de lib e os nomes de símbolo exportados para conter um sufixo, por exemplo, libicuucmyapp, em que myapp é o sufixo.

    <version>: uma versão válida da ICU, por exemplo, 67.1. Essa versão é usada para carregar os binários e obter os símbolos exportados.

Quando uma dessas opções estiver definida, você poderá adicionar um Microsoft.ICU.ICU4C.RuntimePackageReference ao seu projeto que corresponde à version configurada e isso é tudo o que é necessário.

Como outra opção, para carregar uma ICU quando a opção local do aplicativo é definida, o .NET usa o método NativeLibrary.TryLoad, que investiga vários caminhos. Primeiro, o método tenta localizar a biblioteca na propriedade NATIVE_DLL_SEARCH_DIRECTORIES, que é criada pelo host dotnet com base no arquivo deps.json do aplicativo. Para obter mais informações, consulte Investigação padrão.

Para aplicativos independentes, nenhuma ação especial é exigida pelo usuário, além de verificar se a ICU está no diretório do aplicativo (para aplicativos autossuficientes, o diretório de trabalho é padrão NATIVE_DLL_SEARCH_DIRECTORIES).

Se você estiver consumindo ICU por meio de um pacote NuGet, isso funcionará em aplicativos dependentes de estrutura. O NuGet resolve os ativos nativos e os inclui no arquivo deps.json e no diretório de saída do aplicativo no diretório runtimes. O .NET o carrega de lá.

Para aplicativos dependentes de estrutura (não independentes) em que a ICU é consumida a partir de uma compilação local, você deve executar etapas adicionais. O .NET SDK ainda não tem um recurso para binários nativos "soltos" a serem incorporados em deps.json (consulte Esse problema do SDK). Em vez disso, você pode habilitar isso adicionando informações adicionais ao arquivo de projeto do aplicativo. Por exemplo:

<ItemGroup>
  <IcuAssemblies Include="icu\*.so*" />
  <RuntimeTargetsCopyLocalItems Include="@(IcuAssemblies)" AssetType="native" CopyLocal="true"
    DestinationSubDirectory="runtimes/linux-x64/native/" DestinationSubPath="%(FileName)%(Extension)"
    RuntimeIdentifier="linux-x64" NuGetPackageId="System.Private.Runtime.UnicodeData" />
</ItemGroup>

Isso deve ser feito para todos os binários de UTI para os runtimes com suporte. Além disso, os metadados NuGetPackageId no grupo de itens RuntimeTargetsCopyLocalItems precisam corresponder a um pacote NuGet que o projeto realmente faz referência.

Comportamento do macOS

o macOS tem um comportamento diferente para resolver bibliotecas dinâmicas dependentes dos comandos de carga especificados no arquivo Mach-O em comparação com o carregador do Linux. No carregador do Linux, o .NET pode tentar libicudata, libicuuc e libicui18n (nessa ordem) atender ao grafo de dependência da ICU. No entanto, no macOS, isso não funciona. Ao criar a ICU no macOS, você, por padrão, obtém uma biblioteca dinâmica com esses comandos de carga em libicuuc. O snippet a seguir é um exemplo.

~/ % otool -L /Users/santifdezm/repos/icu-build/icu/install/lib/libicuuc.67.1.dylib
/Users/santifdezm/repos/icu-build/icu/install/lib/libicuuc.67.1.dylib:
 libicuuc.67.dylib (compatibility version 67.0.0, current version 67.1.0)
 libicudata.67.dylib (compatibility version 67.0.0, current version 67.1.0)
 /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1281.100.1)
 /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 902.1.0)

Esses comandos fazem referência apenas ao nome das bibliotecas dependentes para os outros componentes da ICU. O carregador executa a pesquisa seguindo as convenções dlopen, o que envolve ter essas bibliotecas nos diretórios do sistema ou definir os env vars LD_LIBRARY_PATH ou ter ICU no diretório no nível do aplicativo. Se você não puder definir LD_LIBRARY_PATH ou garantir que os binários de ICU estejam no diretório no nível do aplicativo, você precisará fazer algum trabalho extra.

Há algumas diretivas para o carregador, como @loader_path, que dizem ao carregador para pesquisar essa dependência no mesmo diretório que o binário com esse comando de carga. Há duas maneiras de fazer isso:

  • install_name_tool -change

    Execute os seguintes comandos:

    install_name_tool -change "libicudata.67.dylib" "@loader_path/libicudata.67.dylib" /path/to/libicuuc.67.1.dylib
install_name_tool -change "libicudata.67.dylib" "@loader_path/libicudata.67.dylib" /path/to/libicui18n.67.1.dylib
install_name_tool -change "libicuuc.67.dylib" "@loader_path/libicuuc.67.dylib" /path/to/libicui18n.67.1.dylib

  • ICU do patch para produzir os nomes de instalação com @loader_path

    Antes de executar autoconf (./runConfigureICU), altere estas linhas para:

    LD_SONAME = -Wl,-compatibility_version -Wl,$(SO_TARGET_VERSION_MAJOR) -Wl,-current_version -Wl,$(SO_TARGET_VERSION) -install_name @loader_path/$(notdir $(MIDDLE_SO_TARGET))

ICU no WebAssembly

Uma versão da ICU está disponível especificamente para cargas de trabalho do WebAssembly. Essa versão fornece compatibilidade de globalização com perfis de área de trabalho. Para reduzir o tamanho do arquivo de dados da ICU de 24 MB para 1,4 MB (ou ~0,3 MB se compactado com Brotli), essa carga de trabalho tem algumas limitações.

A APIs a seguir não têm suporte:

As seguintes APIs têm suporte com limitações:

Além disso, há suporte para menos localidades. A lista com suporte pode ser encontrada no repositório dotnet/icu.