UnicodeEncoding.GetPreamble Método

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Retornos

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

Exemplos

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

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 um BOM e o segundo deles. Em seguida, ele chama o GetPreamble método para gravar o BOM em um arquivo antes de escrever uma cadeia de caracteres codificada por 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 bytes (ponto de código U+FEFF) ajuda o decodificador a determinar a ordem de bytes e o formato de transformação ou UTF. A marca de ordem de bytes Unicode (BOM) é serializada da seguinte maneira (em hexadecimal):

• Ordem de bytes de big endian: FE FF

• Ordem de byte de endian pequeno: FF FE

Você pode criar uma instância de um UnicodeEncoding objeto cujo GetPreamble método retorna um BOM válido das seguintes maneiras:

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

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

• Fornecendo true como o valor do byteOrderMark argumento para os construtores ou UnicodeEncoding(Boolean, Boolean, Boolean) construtoresUnicodeEncoding(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 marcados incorretamente ou não marcados ou arquivos de texto aleatórios armazenados quando uma empresa não tinha preocupações internacionais. Muitas vezes, 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, um 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 de outra forma.

Há algumas desvantagens em usar um BOM. Por exemplo, saber como limitar os campos de banco de dados que usam um 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 acabar no meio dos dados. Apesar das poucas desvantagens, no entanto, o uso de um BOM é altamente recomendado.