UTF8Encoding.GetPreamble Método

Definição

Retorna uma marca de ordem de byte Unicode codificada no formato UTF-8, se o objeto de codificação UTF8Encoding é configurado para fornecer um.Returns a Unicode byte order mark encoded in UTF-8 format, if the UTF8Encoding encoding object is configured to supply one.

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.A byte array containing the Unicode byte order mark, if the UTF8Encoding encoding object is configured to supply one. Caso contrário, esse método retorna uma matriz de bytes de tamanho zero.Otherwise, this method returns a zero-length byte array.

Exemplos

O exemplo a seguir usa o método GetPreamble para retornar a marca de ordem de byte Unicode codificada no formato UTF-8.The following example uses the GetPreamble method to return the Unicode byte order mark encoded in UTF-8 format. Observe que o construtor sem parâmetros para UTF8Encoding não fornece um preâmbulo.Notice that the parameterless constructor for UTF8Encoding does not provide a preamble.

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 instancia dois objetos UTF8Encoding, o primeiro chamando o construtor de UTF8Encoding() sem parâmetros, que não fornece uma BOM e o segundo chamando o Construtor UTF8Encoding(Boolean) com seu argumento encoderShouldEmitUTF8Identifier definido como true.The following example instantiates two UTF8Encoding objects, the first by calling the parameterless UTF8Encoding() constructor, which does not provide a BOM, and the second by calling the UTF8Encoding(Boolean) constructor with its encoderShouldEmitUTF8Identifier argument set to true. Em seguida, ele chama o método GetPreamble para gravar a BOM em um arquivo antes de gravar uma cadeia de caracteres codificada em UF8.It then calls the GetPreamble method to write the BOM to a file before writing a UF8-encoded string. Como a saída do console do exemplo mostra, o arquivo que salva os bytes do segundo codificador tem mais três bytes do que o primeiro.As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first.

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 comando fc em uma janela de console ou pode inspecionar os arquivos em um editor de texto que inclui um modo de exibição Hex.You can also compare the files by using the fc command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Observe que, quando o arquivo é aberto em um editor que dá suporte a UTF-8, a BOM não é exibida.Note that when the file is opened in an editor that supports UTF-8, the BOM is not displayed.

Comentários

O objeto UTF8Encoding pode fornecer um preâmbulo, que é uma matriz de bytes que pode ser prefixada para a sequência de bytes resultante do processo de codificação.The UTF8Encoding object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes that result from the encoding process. Pretendo 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.Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format, or UTF. A BOM (marca de ordem de byte) Unicode é serializada como 0xEF 0xBB 0xBF.The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Observe que o padrão Unicode não requer nem recomenda o uso de uma BOM para fluxos codificados em UTF-8.Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams.

Você pode criar uma instância de um objeto UTF8Encoding cujo método GetPreamble retorna uma BOM válida das seguintes maneiras:You can instantiate a UTF8Encoding object whose GetPreamble method returns a valid BOM in the following ways:

  • Recuperando o objeto UTF8Encoding retornado pela propriedade Encoding.UTF8.By retrieving the UTF8Encoding object returned by the Encoding.UTF8 property.

  • Chamando um construtor de UTF8Encoding com um parâmetro encoderShouldEmitUTF8Identifier e definindo seu valor definido como true.By calling a UTF8Encoding constructor with a encoderShouldEmitUTF8Identifier parameter and setting its value set to true.

Todos os outros objetos UTF8Encoding são configurados para retornar uma matriz vazia em vez de uma BOM válida.All other UTF8Encoding objects are configured to return an empty array rather than a valid BOM.

A BOM fornece uma certa identificação de uma codificação para arquivos que, de outra forma, perderam uma referência à sua codificação, como dados da Web não marcados ou marcados incorretamente ou arquivos de texto aleatórios armazenados quando um negócio não teve preocupações internacionais.The BOM provide nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Geralmente, problemas de usuário podem ser evitados se os dados estiverem marcados de forma consistente e apropriada.Often user problems might be avoided if data is consistently and properly tagged.

Para padrões que fornecem um tipo de codificação, uma BOM é um pouco redundante.For standards that provide an encoding type, a BOM is somewhat redundant. No entanto, ele pode ser usado para ajudar um servidor a enviar o cabeçalho de codificação correto.However, it can be used to help a server send the correct encoding header. Como alternativa, ele pode ser usado como um fallback, caso a codificação seja perdida.Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

Há algumas desvantagens em usar uma BOM.There are some disadvantages to using a BOM. Por exemplo, saber como limitar os campos de banco de dados que usam uma BOM pode ser difícil.For example, knowing how to limit the database fields that use a BOM can be difficult. 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.Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. No entanto, apesar das poucas desvantagens, o uso de uma BOM é altamente recomendável.In spite of the few disadvantages, however, the use of a BOM is highly recommended.

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.For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

Importante

Para garantir que os bytes codificados sejam decodificados corretamente quando eles são salvos como um arquivo ou como um fluxo, você pode prefixar o início de um fluxo de bytes codificados com um preâmbulo.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Observe que o método GetBytes não precede uma BOM para uma sequência de bytes codificados; fornecer uma BOM no início de um fluxo de bytes apropriado é a responsabilidade do desenvolvedor.Note that the GetBytes method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility.

Aplica-se a