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()

Devoluções

Um array de bytes contendo a marca de ordem de bytes Unicode, se o UnicodeEncoding objeto estiver configurado para fornecer uma. Caso contrário, este método devolve um array de bytes de comprimento zero.

Exemplos

O exemplo seguinte demonstra como usar o GetPreamble método para recuperar a marca de ordem de bytes Unicode em 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 seguinte instancia dois UnicodeEncoding objetos, o primeiro dos quais não fornece uma lista de materiais (BOM), e o segundo que fornece. Depois, chama o GetPreamble método para escrever a lista de materiais num ficheiro antes de escrever uma cadeia codificada em Unicode. Como mostra a saída da consola do exemplo, o ficheiro que guarda 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.

Também pode comparar os ficheiros usando o fc comando numa janela de consola, ou pode inspecionar os ficheiros num editor de texto que inclua um modo Hex View. Note que, quando o ficheiro é aberto num editor que suporta codificação UTF-16, a lista de materiais não é exibida.

Observações

O UnicodeEncoding objeto pode fornecer um preâmbulo, que é um array de bytes que pode ser prefixado para a sequência de bytes resultante do processo de codificação. Antecipar uma sequência de bytes codificados com uma marca de ordem de bytes (ponto de código U+FEFF) ajuda o descodificador a determinar a ordem dos bytes e o formato de transformação ou UTF. A marca de ordem dos bytes Unicode (BOM) é serializada da seguinte forma (em hexadecimal):

• Ordem dos bytes big endian: FE FF

• Little endian ordem dos bytes: FF FE

Pode instanciar um UnicodeEncoding objeto cujo GetPreamble método devolve uma lista de materiais válida das seguintes formas:

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

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

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

Recomendamos que utilize a lista de comandos, pois fornece uma identificação quase certa de uma codificação para ficheiros que, de outra forma, perderam a referência à sua codificação, como dados web não etiquetados ou incorretamente ou ficheiros de texto aleatórios armazenados quando uma empresa não tinha preocupações internacionais. Muitas vezes, os problemas do utilizador podem ser evitados se os dados forem etiquetados de forma consistente e adequada.

Para normas que fornecem um tipo de codificação, uma BOM é algo redundante. No entanto, pode ser usado para ajudar um servidor a enviar o cabeçalho de codificação correto. Alternativamente, pode ser usado como plano B caso a codificação se perca.

Existem algumas desvantagens em usar uma lista de materiais (BOM). Por exemplo, saber como limitar os campos da base de dados que utilizam uma lista de materiais pode ser difícil. A concatenação de ficheiros também pode ser um problema, por exemplo, quando os ficheiros são fundidos de tal forma que um carácter desnecessário pode acabar no meio dos dados. Apesar das poucas desvantagens, a utilização de uma lista de materiais é altamente recomendada.