UnicodeEncoding.GetPreamble Método

Referencia

Definición

Espacio de nombres:: System.Text

Ensamblado:: System.Text.Encoding.Extensions.dll

Ensamblado:: mscorlib.dll

Ensamblado:: netstandard.dll

Source:: UnicodeEncoding.cs

Source:: UnicodeEncoding.cs

Source:: UnicodeEncoding.cs

Importante

Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

Devuelve una marca de orden de bytes Unicode codificada en formato UTF-16 si el constructor empleado para esta instancia solicita una marca de orden de bytes.

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 objeto UnicodeEncoding está configurado para proporcionar una. De lo contrario, este método devuelve una matriz de bytes de longitud cero.

Ejemplos

En el ejemplo siguiente se muestra cómo usar el GetPreamble método para recuperar la marca de orden de bytes Unicode en big endian o el orden de bytes little endian para una instancia de .UnicodeEncoding

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^byteOrderMark;
   byteOrderMark = Encoding::Unicode->GetPreamble();
   Console::WriteLine( "Default (little-endian) Unicode Preamble:" );
   IEnumerator^ myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine( "\n" );
   UnicodeEncoding^ bigEndianUnicode = gcnew UnicodeEncoding( true,true );
   byteOrderMark = bigEndianUnicode->GetPreamble();
   Console::WriteLine( "Big-endian Unicode Preamble:" );
   myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }
}

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        Byte[] byteOrderMark;
        
        byteOrderMark = Encoding.Unicode.GetPreamble();
        Console.WriteLine("Default (little-endian) Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine("\n");

        UnicodeEncoding bigEndianUnicode = new UnicodeEncoding(true, true);
        byteOrderMark = bigEndianUnicode.GetPreamble();
        Console.WriteLine("Big-endian Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
    }
}

Imports System.Text

Class UnicodeEncodingExample
    
    Public Shared Sub Main()
        Dim byteOrderMark() As Byte
        Dim b As Byte
        
        byteOrderMark = Encoding.Unicode.GetPreamble()
        Console.WriteLine("Default (little-endian) Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine(ControlChars.NewLine)
        
        Dim bigEndianUnicode As New UnicodeEncoding(True, True)
        byteOrderMark = bigEndianUnicode.GetPreamble()
        Console.WriteLine("Big-endian Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
    End Sub
End Class

En el ejemplo siguiente se crean instancias de dos UnicodeEncoding objetos, el primero de los cuales no proporciona una lista de materiales y el segundo de los cuales lo hace. A continuación, llama al GetPreamble método para escribir la boM en un archivo antes de escribir una cadena codificada unicode. Como se muestra en la salida de la consola del ejemplo, el archivo que guarda los bytes del segundo codificador tiene tres 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-16 encoding.";

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

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

      ' Use BOM.
      enc = New UnicodeEncoding(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 116 bytes to .\NoPreamble.txt.
'
'       Preamble has 2 bytes
'       Wrote 118 bytes to .\Preamble.txt.

También puede comparar los archivos mediante el fc comando en una ventana de consola, o 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 la codificación UTF-16, no se muestra la BOM.

Comentarios

El UnicodeEncoding 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 (punto de código 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 como se indica a continuación (en hexadecimal):

Orden de bytes big endian: FE FF
Orden de bytes little endian: FF FE

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

Recuperando el UnicodeEncoding objeto devuelto por la Encoding.Unicode propiedad o Encoding.BigEndianUnicode .
Llamando al constructor sin UnicodeEncoding() parámetros para crear una instancia de un UnicodeEncoding objeto.
true Proporcionando como valor del byteOrderMark argumento a los UnicodeEncoding(Boolean, Boolean) constructores o UnicodeEncoding(Boolean, Boolean, Boolean) .

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 una referencia a su codificación, como datos web no etiquetados o etiquetados incorrectamente o archivos de texto aleatorios almacenados cuando una empresa no tenía problemas internacionales. A menudo, es posible que se eviten problemas de usuario si los datos están etiquetados 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, de lo contrario, se pierda la codificación.

El uso de una marca BOM tiene algunas desventajas. Por ejemplo, saber cómo limitar los campos de base de datos que usan una marca BOM puede ser difícil. La concatenación de archivos también puede ser un problema, por ejemplo, cuando los archivos se combinan de manera que un carácter innecesario puede acabar en el medio de los datos. Sin embargo, a pesar de los pocos inconvenientes, se recomienda encarecidamente el uso de una marca BOM.

Importante

Para asegurarse de que los bytes codificados se descodifican correctamente, debe anteponer el principio de una secuencia de 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.

Se aplica a

UnicodeEncoding.GetPreamble Método

Definición

Devoluciones

Ejemplos

Comentarios

Se aplica a

Comentarios

Recursos adicionales