UnicodeEncoding.GetPreamble Método

Definição

Namespace:

System.Text

Assembly:

System.Text.Encoding.Extensions.dll

Origem:

UnicodeEncoding.cs

Retorna uma marca de ordem de byte Unicode codificada no formato UTF-16 se o construtor dessa instância solicita uma marca de ordem de byte.

public:
 override cli::array <System::Byte> ^ GetPreamble();

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Retornos

Byte[]

Uma matriz de bytes que contém a marca de ordem de byte Unicode se o objeto UnicodeEncoding é configurado para fornecer uma. Caso contrário, esse método retorna uma matriz de bytes de tamanho zero.

Exemplos

O exemplo a seguir demonstra como usar o GetPreamble método para recuperar a marca de ordem de byte Unicode na ordem de bytes big endian ou little endian para uma instância de um UnicodeEncoding.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^byteOrderMark;
   byteOrderMark = Encoding::Unicode->GetPreamble();
   Console::WriteLine( "Default (little-endian) Unicode Preamble:" );
   IEnumerator^ myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine( "\n" );
   UnicodeEncoding^ bigEndianUnicode = gcnew UnicodeEncoding( true,true );
   byteOrderMark = bigEndianUnicode->GetPreamble();
   Console::WriteLine( "Big-endian Unicode Preamble:" );
   myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }
}

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        Byte[] byteOrderMark;
        
        byteOrderMark = Encoding.Unicode.GetPreamble();
        Console.WriteLine("Default (little-endian) Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine("\n");

        UnicodeEncoding bigEndianUnicode = new UnicodeEncoding(true, true);
        byteOrderMark = bigEndianUnicode.GetPreamble();
        Console.WriteLine("Big-endian Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
    }
}

Imports System.Text

Class UnicodeEncodingExample
    
    Public Shared Sub Main()
        Dim byteOrderMark() As Byte
        Dim b As Byte
        
        byteOrderMark = Encoding.Unicode.GetPreamble()
        Console.WriteLine("Default (little-endian) Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine(ControlChars.NewLine)
        
        Dim bigEndianUnicode As New UnicodeEncoding(True, True)
        byteOrderMark = bigEndianUnicode.GetPreamble()
        Console.WriteLine("Big-endian Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
    End Sub
End Class

O exemplo a seguir cria uma instância de dois UnicodeEncoding objetos, o primeiro dos quais não fornece uma BOM e o segundo deles. Em seguida, ele chama o GetPreamble método para gravar o BOM em um arquivo antes de gravar uma cadeia de caracteres codificada em Unicode. Como mostra a saída do console do exemplo, o arquivo que salva os bytes do segundo codificador tem três bytes a mais do que o primeiro.

using System;
using System.IO;
using System.Text;

public class Example
{
   public static void Main()
   {
      String s = "This is a string to write to a file using UTF-16 encoding.";

      // Write a file using a Unicode encoding object without a BOM.
      var enc = new UnicodeEncoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UnicodeEncoding(! BitConverter.IsLittleEndian, true);
      WriteToFile(@".\Preamble.txt", enc, bytes);
   }

   private static void WriteToFile(String fn, Encoding enc, Byte[] bytes)
   {
      var fs = new FileStream(fn, FileMode.Create);
      Byte[] preamble = enc.GetPreamble();
      fs.Write(preamble, 0, preamble.Length);
      Console.WriteLine("Preamble has {0} bytes", preamble.Length);
      fs.Write(bytes, 0, bytes.Length);
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn);
      fs.Close();
      Console.WriteLine();
   }
}
// The example displays the following output:
//       Preamble has 0 bytes
//       Wrote 116 bytes to .\NoPreamble.txt.
//
//       Preamble has 2 bytes
//       Wrote 118 bytes to .\Preamble.txt.

Imports System.IO
Imports System.Text

Module Example
   Public Sub Main()
      Dim s As String = "This is a string to write to a file using UTF-16 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UnicodeEncoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UnicodeEncoding(Not BitConverter.IsLittleEndian, True)
      WriteToFile("Preamble.txt", enc, bytes)
   End Sub

   Private Sub WriteToFile(fn As String, enc As Encoding, bytes As Byte())
      Dim fs As New FileStream(fn, FileMode.Create)
      Dim preamble() As Byte = enc.GetPreamble()
      fs.Write(preamble, 0, preamble.Length)
      Console.WriteLine("Preamble has {0} bytes", preamble.Length)
      fs.Write(bytes, 0, bytes.Length)
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn)
      fs.Close()
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'       Preamble has 0 bytes
'       Wrote 116 bytes to .\NoPreamble.txt.
'
'       Preamble has 2 bytes
'       Wrote 118 bytes to .\Preamble.txt.

Você também pode comparar os arquivos usando o fc comando em uma janela do console ou inspecionar os arquivos em um editor de texto que inclui um modo de Exibição Hex. Observe que quando o arquivo é aberto em um editor que dá suporte à codificação UTF-16, o BOM não é exibido.

Comentários

O UnicodeEncoding objeto pode fornecer um preâmbulo, que é uma matriz de bytes que pode ser prefixada na sequência de bytes resultantes do processo de codificação. A pré-criação de uma sequência de bytes codificados com uma marca de ordem de byte (ponto de código U+FEFF) ajuda o decodificador a determinar a ordem de bytes e o formato de transformação ou UTF. A BOM (marca de ordem de byte) Unicode é serializada da seguinte maneira (em hexadecimal):

• Ordem de bytes big endian: FE FF

• Ordem de byte do pequeno endian: FF FE

Você pode instanciar um UnicodeEncoding objeto cujo GetPreamble método retorna uma BOM válida das seguintes maneiras:

• Recuperando o UnicodeEncoding objeto retornado pela Encoding.Unicode propriedade ou Encoding.BigEndianUnicode .

• Chamando o construtor sem UnicodeEncoding() parâmetros para instanciar um UnicodeEncoding objeto .

• Fornecendo true como o valor do byteOrderMark argumento para os UnicodeEncoding(Boolean, Boolean) construtores ou UnicodeEncoding(Boolean, Boolean, Boolean) .

Recomendamos que você use o BOM, pois ele fornece quase certa identificação de uma codificação para arquivos que, de outra forma, perderam uma referência à codificação, como dados da Web não marcados ou marcados incorretamente ou arquivos de texto aleatórios armazenados quando uma empresa não tinha preocupações internacionais. Geralmente, os problemas do usuário podem ser evitados se os dados forem marcados de forma consistente e correta.

Para padrões que fornecem um tipo de codificação, uma BOM é um pouco redundante. No entanto, ele pode ser usado para ajudar um servidor a enviar o cabeçalho de codificação correto. Como alternativa, ele pode ser usado como um fallback, caso a codificação seja perdida.

Há algumas desvantagens em usar uma BOM. Por exemplo, saber como limitar os campos de banco de dados que usam uma BOM pode ser difícil. A concatenação de arquivos também pode ser um problema, por exemplo, quando os arquivos são mesclados de forma que um caractere desnecessário possa terminar no meio dos dados. No entanto, apesar das poucas desvantagens, o uso de uma BOM é altamente recomendável.

Importante

Para garantir que os bytes codificados sejam decodificados corretamente, você deve prefixar o início de um fluxo de bytes codificados com um preâmbulo. Observe que o GetBytes método não prepara uma BOM para uma sequência de bytes codificados; fornecer uma BOM no início de um fluxo de bytes apropriado é responsabilidade do desenvolvedor.