UnicodeEncoding.GetPreamble Método

Definición

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 byte[] GetPreamble ();

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 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);
        }
    }
}

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.

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:

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

Producto Versiones
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0