UTF8Encoding.GetPreamble Método

Referência

Definição

Namespace:: System.Text

Assembly:: System.Text.Encoding.Extensions.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Importante

Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Retorna uma marca de ordem de byte Unicode codificada no formato UTF-8, se o objeto de codificação UTF8Encoding é configurado para fornecer um.

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 de codificação UTF8Encoding é configurado para fornecer um. Caso contrário, esse método retorna uma matriz de bytes de tamanho zero.

Exemplos

O exemplo a seguir usa o GetPreamble método para retornar a marca de ordem de byte Unicode codificada no formato UTF-8. Observe que o construtor sem parâmetros não UTF8Encoding fornece um preâmbulo.

using namespace System;
using namespace System::Text;
using namespace System::Collections;

void ShowArray(array<Byte>^ bytes)
{
   for each (Byte b in bytes)
      Console::Write( "{0:X2} ", b);

   Console::WriteLine();
}

int main()
{
   // The default constructor does not provide a preamble.
   UTF8Encoding^ UTF8NoPreamble = gcnew UTF8Encoding;
   UTF8Encoding^ UTF8WithPreamble = gcnew UTF8Encoding( true );
   array<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 );
}
// The example displays the following output:
//       UTF8NoPreamble
//        preamble length: 0
//        preamble:
//
//       UTF8WithPreamble
//        preamble length: 3
//        preamble: EF BB BF

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 a seguir cria uma instância de dois UTF8Encoding objetos, o primeiro chamando o construtor sem UTF8Encoding() parâmetros, que não fornece um BOM, e o segundo chamando o UTF8Encoding(Boolean) construtor com seu encoderShouldEmitUTF8Identifier argumento definido como true. Em seguida, ele chama o GetPreamble método para gravar o BOM em um arquivo antes de gravar uma cadeia de caracteres codificada em UF8. 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-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.

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 a UTF-8, o BOM não é exibido.

Comentários

O UTF8Encoding 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 byte e o formato de transformação, ou UTF. A marca de ordem de byte Unicode (BOM) é serializada como 0xEF 0xBB 0xBF. Observe que o Padrão Unicode não requer nem recomenda o uso de um BOM para fluxos codificados utf-8.

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

Recuperando o UTF8Encoding objeto retornado pela Encoding.UTF8 propriedade.
Chamando um UTF8Encoding construtor com um encoderShouldEmitUTF8Identifier parâmetro e definindo seu valor definido como true.

Todos os outros UTF8Encoding objetos são configurados para retornar uma matriz vazia em vez de uma BOM válida.

O BOM 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. 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, 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.

Para obter mais informações sobre a ordem de bytes e a marca de ordem de byte, consulte o padrão Unicode na Home Page Unicode.