UTF8Encoding.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 dos bytes Unicode, se o UTF8Encoding objeto codificador estiver configurado para fornecer um. Caso contrário, este método devolve um array de bytes de comprimento zero.

Exemplos

O exemplo seguinte utiliza o GetPreamble método para devolver a marca de ordem dos bytes Unicode codificada no formato UTF-8. Note que o construtor sem parâmetros para UTF8Encoding não fornece um preâmbulo.

using System;
using System.Text;

class Example
{
    public static void Main()
    {
        // The default constructor does not provide a preamble.
        UTF8Encoding UTF8NoPreamble = new UTF8Encoding();
        UTF8Encoding UTF8WithPreamble = new UTF8Encoding(true);

        Byte[] preamble;

        preamble = UTF8NoPreamble.GetPreamble();
        Console.WriteLine("UTF8NoPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
        Console.WriteLine();
        
        preamble = UTF8WithPreamble.GetPreamble();
        Console.WriteLine("UTF8WithPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
    }

    public static void ShowArray(Byte[] bytes)
    {
        foreach (var b in bytes)
            Console.Write("{0:X2} ", b);

        Console.WriteLine();
    }
}
// The example displays the following output:
//    UTF8NoPreamble
//     preamble length: 0
//     preamble:
//
//    UTF8WithPreamble
//     preamble length: 3
//     preamble: EF BB BF

Imports System.Text

Module Example
    Public Sub Main()
        ' The default constructor does not provide a preamble.
        Dim UTF8NoPreamble As New UTF8Encoding()
        Dim UTF8WithPreamble As New UTF8Encoding(True)
        
        Dim preamble() As Byte
        
        preamble = UTF8NoPreamble.GetPreamble()
        Console.WriteLine("UTF8NoPreamble")
        Console.WriteLine(" preamble length: {0}", preamble.Length)
        Console.Write(" preamble: ")
        ShowArray(preamble)
        Console.WriteLine()
        
        preamble = UTF8WithPreamble.GetPreamble()
        Console.WriteLine("UTF8WithPreamble")
        Console.WriteLine(" preamble length: {0}", preamble.Length)
        Console.Write(" preamble: ")
        ShowArray(preamble)
    End Sub

    Public Sub ShowArray(bytes As Byte())
        For Each b In  bytes
            Console.Write("{0:X2} ", b)
        Next
        Console.WriteLine()
    End Sub
End Module
' The example displays the following output:
'    UTF8NoPreamble
'     preamble length: 0
'     preamble:
'
'    UTF8WithPreamble
'     preamble length: 3
'     preamble: EF BB BF

O exemplo seguinte instancia dois UTF8Encoding objetos, o primeiro chamando o construtor sem UTF8Encoding() parâmetros, que não fornece uma lista de materiais (BOM), e o segundo chamando o UTF8Encoding(Boolean) construtor com o seu encoderShouldEmitUTF8Identifier argumento definido para true. Depois, chama o GetPreamble método para escrever a lista de materiais num ficheiro antes de escrever uma cadeia codificada em UF8. 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-8 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF8Encoding();
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile("NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF8Encoding(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 57 bytes to NoPreamble.txt.
//
//       Preamble has 3 bytes
//       Wrote 60 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-8 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF8Encoding()
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF8Encoding(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 57 bytes to NoPreamble.txt.
'
'       Preamble has 3 bytes
'       Wrote 60 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 UTF-8, a lista de materiais não é apresentada.

Observações

O UTF8Encoding objeto pode fornecer um preâmbulo, que é um array de bytes que pode ser prefixado para a sequência de bytes resultantes do processo de codificação. Introduzir uma sequência de bytes codificados com uma marca de ordem dos 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 como 0xEF 0xBB 0xBF. Note-se que o Padrão Unicode não exige nem recomenda o uso de uma lista de materiais para fluxos codificados em UTF-8.

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

• Recuperando o UTF8Encoding objeto devolvido pela Encoding.UTF8 propriedade.

• Ao chamar um UTF8Encoding construtor com um encoderShouldEmitUTF8Identifier parâmetro e definir o seu valor para true.

Todos os outros UTF8Encoding objetos estão configurados para devolver um array vazio em vez de uma lista de materiais válida.

A BOM fornece uma identificação quase certa de uma codificação para ficheiros que, de outra forma, teriam perdido uma 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.

Para obter mais informações sobre a ordem de bytes e a marca de ordem de bytes, consulte O padrão Unicode na home page Unicode.