about_Character_Encoding

  • Artigo

Descrição breve

Descreve como o PowerShell usa a codificação de caracteres para entrada e saída de dados de cadeia de caracteres.

Descrição longa

Unicode é um padrão mundial de codificação de caracteres. O sistema usa Unicode exclusivamente para manipulação de caracteres e cadeias de caracteres. Para obter uma descrição detalhada de todos os aspectos do Unicode, consulte O padrão Unicode.

O Windows oferece suporte a Unicode e conjuntos de caracteres tradicionais. Os conjuntos de caracteres tradicionais, como páginas de código do Windows, usam valores de 8 bits ou combinações de valores de 8 bits para representar os caracteres usados em um idioma específico ou configurações de região geográfica.

O PowerShell usa um caractere Unicode definido por padrão. No entanto, vários cmdlets têm um parâmetro Encoding que pode especificar a codificação para um conjunto de caracteres diferente. Esse parâmetro permite que você escolha a codificação de caracteres específica necessária para a interoperabilidade com outros sistemas e aplicativos.

Os cmdlets a seguir têm o parâmetro Encoding :

  • Microsoft.PowerShell.Management
    • Add-Content
    • Get-Content
    • Set-Content
  • Microsoft.PowerShell.Utility
    • Export-Clixml
    • Export-Csv
    • Export-PSSession
    • Format-Hex
    • Import-Csv
    • Out-File
    • Select-String
    • Send-MailMessage

A marca de ordem de bytes

A marca de ordem de bytes (BOM) é uma assinatura Unicode nos primeiros bytes de um arquivo ou fluxo de texto que indica qual codificação Unicode usada para os dados. Para obter mais informações, consulte a documentação de marca de pedido de byte.

No Windows PowerShell, qualquer codificação Unicode, exceto UTF7, sempre cria uma BOM. O PowerShell (v6 e superior) tem como padrão para utf8NoBOM todas as saídas de texto.

Para obter melhor compatibilidade geral, evite usar listas técnicas em arquivos UTF-8. Plataformas Unix e utilitários Unix-heritage também usados em plataformas Windows não suportam BOMs.

Da mesma forma, UTF7 a codificação deve ser evitada. UTF-7 não é uma codificação Unicode padrão e é escrito sem uma BOM em todas as versões do PowerShell.

Criar scripts do PowerShell em uma plataforma semelhante ao Unix ou usar um editor de plataforma cruzada no Windows, como o Visual Studio Code, resulta em um arquivo codificado usando UTF8NoBOM. Esses arquivos funcionam bem no PowerShell, mas podem quebrar no Windows PowerShell se o arquivo contiver caracteres não-Ascii.

Se você precisar usar caracteres não-Ascii em seus scripts, salve-os como UTF-8 com BOM. Sem a BOM, o Windows PowerShell interpreta incorretamente seu script como sendo codificado na página de código "ANSI" herdada. Por outro lado, arquivos que têm a lista técnica UTF-8 podem ser problemáticos em plataformas do tipo Unix. Muitas ferramentas Unix como cat, sed, awke alguns editores como gedit não sabem como tratar a lista técnica.

Codificação de caracteres no Windows PowerShell

No PowerShell 5.1, o parâmetro Encoding oferece suporte aos seguintes valores:

  • Ascii Usa o conjunto de caracteres Ascii (7 bits).
  • BigEndianUnicode Usa UTF-16 com a ordem de bytes big-endian.
  • BigEndianUTF32 Usa UTF-32 com a ordem de bytes big-endian.
  • Byte Codifica um conjunto de caracteres em uma sequência de bytes.
  • Default Usa a codificação que corresponde à página de código ativo do sistema (geralmente ANSI).
  • Oem Usa a codificação que corresponde à página de código OEM atual do sistema.
  • String Igual a Unicode.
  • Unicode Usa UTF-16 com a ordem de bytes little-endian.
  • Unknown Igual a Unicode.
  • UTF32 Usa UTF-32 com a ordem de bytes little-endian.
  • UTF7 Usa UTF-7.
  • UTF8 Usa UTF-8 (com BOM).

Em geral, o Windows PowerShell usa a codificação Unicode UTF-16LE por padrão. No entanto, a codificação padrão usada por cmdlets no Windows PowerShell não é consistente.

Observação

Usar qualquer codificação Unicode, exceto UTF7, sempre cria uma BOM.

Para cmdlets que gravam saída em arquivos:

  • Out-File e os operadores > de redirecionamento e >> criar UTF-16LE, que difere notavelmente de Set-Content e Add-Content.

  • New-ModuleManifest e Export-CliXml também criar arquivos UTF-16LE.

  • Quando o arquivo de destino estiver vazio ou não existir Set-Content e Add-Content use Default codificação. Default é a codificação especificada pela página de código herdado ANSI da localidade do sistema ativo.

  • Export-Csv cria Ascii arquivos, mas usa codificação diferente ao usar o parâmetro Append (veja abaixo).

  • Export-PSSession cria arquivos UTF-8 com BOM por padrão.

  • New-Item -Type File -Value cria um arquivo UTF-8 sem BOM.

  • Send-MailMessage usa Ascii codificação por padrão.

  • Start-Transcript cria Utf8 arquivos com uma lista técnica. Quando o parâmetro Append é usado, a codificação pode ser diferente (veja abaixo).

Para comandos que acrescentam a um arquivo existente:

  • Out-File -Append e o >> operador de redirecionamento não faz nenhuma tentativa de corresponder à codificação do conteúdo do arquivo de destino existente. Em vez disso, eles usam a codificação padrão, a menos que o parâmetro Encoding seja usado. Você deve usar a codificação original dos arquivos ao anexar conteúdo.

  • Na ausência de um parâmetro de codificação explícito, Add-Content detecta a codificação existente e aplica-a automaticamente ao novo conteúdo. Se o conteúdo existente não tiver BOM, Default a codificação ANSI será usada. O comportamento de Add-Content é o mesmo no PowerShell (v6 e superior), exceto que a codificação padrão é Utf8.

  • Export-Csv -Append corresponde à codificação existente quando o arquivo de destino contém uma BOM. Na ausência de uma lista técnica, ele usa Utf8 codificação.

  • Start-Transcript -Append corresponde à codificação existente de arquivos que incluem uma lista técnica. Na ausência de uma BOM, o padrão é Ascii codificação. Essa codificação pode resultar em perda de dados ou corrupção de caracteres quando os dados na transcrição contêm caracteres multibyte.

Para cmdlets que leem dados de cadeia de caracteres na ausência de uma lista técnica:

  • Get-Content e Import-PowerShellDataFile usa a Default codificação ANSI. ANSI também é o que o mecanismo do PowerShell usa quando lê o código-fonte dos arquivos.

  • Import-Csv, Import-CliXmle Select-String assumir Utf8 na ausência de uma lista técnica.

Codificação de caracteres no PowerShell

No PowerShell (v7.1 e superior), o parâmetro Encoding oferece suporte aos seguintes valores:

  • ascii: Usa a codificação para o conjunto de caracteres ASCII (7 bits).
  • ansi: Usa a codificação para a página de código ANSI da cultura atual. Essa opção foi adicionada ao PowerShell 7.4.
  • bigendianunicode: Codifica no formato UTF-16 usando a ordem de bytes big-endian.
  • bigendianutf32: Codifica no formato UTF-32 usando a ordem de bytes big-endian.
  • oem: Usa a codificação padrão para MS-DOS e programas de console.
  • unicode: Codifica no formato UTF-16 usando a ordem de bytes little-endian.
  • utf7: Codifica no formato UTF-7.
  • utf8: Codifica no formato UTF-8 (sem BOM).
  • utf8BOM: Codifica no formato UTF-8 com Byte Order Mark (BOM)
  • utf8NoBOM: Codifica no formato UTF-8 sem Byte Order Mark (BOM)
  • utf32: Codifica no formato UTF-32 usando a ordem de bytes little-endian.

O padrão do PowerShell é para utf8NoBOM todas as saídas.

A partir do PowerShell 6.2, o parâmetro Encoding também permite IDs numéricos de páginas de código registradas (como -Encoding 1251) ou nomes de cadeia de caracteres de páginas de código registradas (como -Encoding "windows-1251"). Para obter mais informações, consulte a documentação do .NET para Encoding.CodePage.

A partir do PowerShell 7.4, você pode usar o Ansi valor do parâmetro Encoding para passar a ID numérica para a página de código ANSI da cultura atual sem precisar especificá-la manualmente.

Alterando a codificação padrão

O PowerShell tem duas variáveis padrão que podem ser usadas para alterar o comportamento de codificação padrão.

  • $PSDefaultParameterValues
  • $OutputEncoding

Para obter mais informações, consulte about_Preference_Variables.

A partir do PowerShell 5.1, os operadores de redirecionamento (> e >>) chamam o Out-File cmdlet. Portanto, você pode definir a codificação padrão deles usando a $PSDefaultParameterValues variável de preferência, conforme mostrado neste exemplo:

$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'

Use a instrução a seguir para alterar a codificação padrão de todos os cmdlets que têm o parâmetro Encoding .

$PSDefaultParameterValues['*:Encoding'] = 'utf8'

Importante

Colocar esse comando em seu perfil do PowerShell torna a preferência uma configuração global de sessão que afeta todos os comandos e scripts que não especificam explicitamente uma codificação.

Da mesma forma, você deve incluir esses comandos em seus scripts ou módulos que você deseja se comportar da mesma maneira. O uso desses comandos garante que os cmdlets se comportem da mesma maneira, mesmo quando executados por outro usuário, em um computador diferente ou em uma versão diferente do PowerShell.

A variável $OutputEncoding automática afeta a codificação que o PowerShell usa para se comunicar com programas externos. Ele não tem efeito sobre a codificação que os operadores de redirecionamento de saída e cmdlets do PowerShell usam para salvar em arquivos.

Confira também