UTF32Encoding.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 UTF32Encoding objeto estiver configurado para fornecer uma. Caso contrário, este método devolve um array de bytes de comprimento zero.

Exemplos

O exemplo de código seguinte recupera e mostra a marca de ordem dos bytes para diferentes UTF32Encoding instâncias.

using System;
using System.Text;

public class SamplesUTF32Encoding
{
   public static void Main()
   {
      // Create instances of UTF32Encoding, with the byte order mark and without.
      UTF32Encoding u32LeNone = new UTF32Encoding();
      UTF32Encoding u32BeNone = new UTF32Encoding( true, false );
      UTF32Encoding u32LeBom  = new UTF32Encoding( false, true );
      UTF32Encoding u32BeBom  = new UTF32Encoding( true, true );

      // Display the preamble for each instance.
      PrintHexBytes( u32LeNone.GetPreamble() );
      PrintHexBytes( u32BeNone.GetPreamble() );
      PrintHexBytes( u32LeBom.GetPreamble() );
      PrintHexBytes( u32BeBom.GetPreamble() );
   }

   public static void PrintHexBytes( byte[] bytes )
   {

      if (( bytes == null ) || ( bytes.Length == 0 ))
        {
            Console.WriteLine( "<none>" );
        }
        else  {
         for ( int i = 0; i < bytes.Length; i++ )
            Console.Write( "{0:X2} ", bytes[i] );
         Console.WriteLine();
      }
   }
}
/*
This example displays the following output.
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

Imports System.Text

Public Class SamplesUTF32Encoding   
   Public Shared Sub Main()
      ' Create instances of UTF32Encoding, with the byte order mark and without.
      Dim u32LeNone As New UTF32Encoding()
      Dim u32BeNone As New UTF32Encoding(True, False)
      Dim u32LeBom As New UTF32Encoding(False, True)
      Dim u32BeBom As New UTF32Encoding(True, True)

      ' Display the preamble for each instance.
      PrintHexBytes(u32LeNone.GetPreamble())
      PrintHexBytes(u32BeNone.GetPreamble())
      PrintHexBytes(u32LeBom.GetPreamble())
      PrintHexBytes(u32BeBom.GetPreamble())
   End Sub

   Public Shared Sub PrintHexBytes(bytes() As Byte)
      If bytes Is Nothing OrElse bytes.Length = 0 Then
         Console.WriteLine("<none>")
      Else
         Dim i As Integer
         For i = 0 To bytes.Length - 1
            Console.Write("{0:X2} ", bytes(i))
         Next i
         Console.WriteLine()
      End If
   End Sub
End Class
'This example displays the following output:
'       FF FE 00 00
'       FF FE 00 00
'       00 00 FE FF

O exemplo seguinte instancia dois UTF32Encoding objetos, o primeiro dos quais não fornece uma BOM e o segundo fornece. Depois, chama o GetPreamble método para escrever a lista de materiais num ficheiro antes de escrever uma cadeia codificada em UTF-32. Como mostra a saída do exemplo, o ficheiro que guarda os bytes do segundo codificador tem quatro 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-32 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF32Encoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF32Encoding(! 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 232 bytes to .\NoPreamble.txt.
//
//       Preamble has 4 bytes
//       Wrote 236 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-32 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF32Encoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF32Encoding(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 232 bytes to NoPreamble.txt.
'
'       Preamble has 4 bytes
'       Wrote 236 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-32, a lista de materiais não é exibida.

Observações

O UTF32Encoding objeto pode fornecer um preâmbulo, que é um array de bytes que pode ser prefixado à sequência de bytes resultante do processo de codificação. Antecipar uma sequência de bytes codificados com uma marca de ordem de bytes (pontos de código U+0000 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: 00 00 FE FF

• Little endian ordem dos bytes: FF FE 00 00

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

• Recuperando o UTF32Encoding objeto devolvido pela Encoding.UTF32 propriedade.

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

• Fornecendo true como valor do byteOrderMark argumento aos UTF32Encoding construtores e UTF32Encoding .

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 ao UTF32Encoding objeto, por exemplo, dados web não etiquetados ou mal etiquetados, ou ficheiros de texto aleatórios armazenados quando uma empresa não tinha preocupações internacionais ou outros dados. 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.