UTF32Encoding.GetPreamble Método

Definición

Espacio de nombres:

System.Text

Ensamblados:

netstandard.dll, System.Text.Encoding.Extensions.dll

Source:

UTF32Encoding.cs

Devuelve una marca de orden de bytes Unicode codificada en formato UTF-32, si el UTF32Encoding objeto está configurado para proporcionar uno.

public:
 override cli::array <System::Byte> ^ GetPreamble();

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Devoluciones

Byte[]

Matriz de bytes que contiene la marca de orden de bytes Unicode, si el UTF32Encoding objeto está configurado para proporcionar uno. De lo contrario, este método devuelve una matriz de bytes de longitud cero.

Ejemplos

En el ejemplo de código siguiente se recupera y se muestra la marca de orden de bytes para instancias diferentes UTF32Encoding .

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

En el ejemplo siguiente se crean instancias de dos UTF32Encoding objetos, el primero de los cuales no proporciona una lista de materiales y la segunda de los cuales sí. A continuación, llama al GetPreamble método para escribir la boM en un archivo antes de escribir una cadena con codificación UTF-32. Como se muestra en la salida del ejemplo, el archivo que guarda los bytes del segundo codificador tiene cuatro bytes más que el primero.

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.

También puede comparar los archivos mediante el fc comando en una ventana de consola, o bien puede inspeccionar los archivos en un editor de texto que incluya un modo de vista hexadecimal. Tenga en cuenta que, cuando el archivo se abre en un editor que admite UTF-32, no se muestra la lista de materiales.

Comentarios

El UTF32Encoding objeto puede proporcionar un preámbulo, que es una matriz de bytes que se puede prefijar a la secuencia de bytes resultante del proceso de codificación. Anteponer una secuencia de bytes codificados con una marca de orden de bytes (puntos de código U+0000 U+FEFF) ayuda al descodificador a determinar el orden de bytes y el formato de transformación, o UTF. La marca de orden de bytes Unicode (BOM) se serializa de la siguiente manera (en hexadecimal):

• Orden de bytes big endian: 00 00 FE FF

• Pequeño orden de bytes endian: FF FE 00 00

Puede crear una instancia de un UTF32Encoding objeto cuyo GetPreamble método devuelve una lista de materiales válida de las maneras siguientes:

• Recuperando el UTF32Encoding objeto devuelto por la Encoding.UTF32 propiedad .

• Al llamar al constructor sin UTF32Encoding() parámetros para crear una instancia de un UTF32Encoding objeto.

• Al proporcionar true como valor del byteOrderMark argumento a los UTF32Encoding constructores y UTF32Encoding .

Se recomienda usar la lista de materiales, ya que proporciona casi cierta identificación de una codificación para los archivos que, de lo contrario, han perdido referencia al UTF32Encoding objeto, por ejemplo, datos web sin etiquetar o etiquetar incorrectamente, o archivos de texto aleatorios almacenados cuando una empresa no tenía problemas internacionales u otros datos. A menudo, es posible que se eviten problemas de usuario si los datos se etiquetan de forma coherente y correcta.

En el caso de los estándares que proporcionan un tipo de codificación, una boM es algo redundante. Sin embargo, se puede usar para ayudar a un servidor a enviar el encabezado de codificación correcto. Como alternativa, se puede usar como reserva en caso de que se pierda la codificación.

Hay algunas desventajas en el uso de una lista de materiales. Por ejemplo, saber cómo limitar los campos de base de datos que usan una lista de materiales puede ser difícil. La concatenación de archivos también puede ser un problema, por ejemplo, cuando los archivos se combinan de forma que un carácter innecesario pueda acabar en medio de los datos. Sin embargo, a pesar de las pocas desventajas, se recomienda encarecidamente el uso de una lista de materiales.

Para obtener más información sobre el orden de bytes y la marca de orden de bytes, vea El estándar Unicode en la página principal de Unicode.

Importante

Para asegurarse de que los bytes codificados están descodificados correctamente, debe prefijar los bytes codificados con un preámbulo. Tenga en cuenta que el GetBytes método no antepone una lista de materiales a una secuencia de bytes codificados; proporcionar una BOM al principio de una secuencia de bytes adecuada es responsabilidad del desarrollador.