UTF8Encoding.GetPreamble UTF8Encoding.GetPreamble UTF8Encoding.GetPreamble UTF8Encoding.GetPreamble Method

Definición

Devuelve una marca de orden de bytes Unicode codificada en formato UTF-8, si el objeto de codificación UTF8Encoding está configurado para proporcionarla.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()

Devoluciones

Byte[]

Una matriz de bytes que contiene la marca de orden de bytes Unicode, si el objeto de codificación UTF8Encoding está configurado para proporcionarla.A byte array containing the Unicode byte order mark, if the UTF8Encoding encoding object is configured to supply one. De lo contrario, este método devuelve una matriz de bytes de longitud cero.Otherwise, this method returns a zero-length byte array.

Ejemplos

En el ejemplo siguiente se GetPreamble usa el método para devolver la marca de orden de bytes Unicode codificada en formato UTF-8.The following example uses the GetPreamble method to return the Unicode byte order mark encoded in UTF-8 format. Observe que el constructor sin parámetros para UTF8Encoding no proporciona un 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

En el ejemplo siguiente se crean UTF8Encoding instancias de dos objetos, el primero mediante una UTF8Encoding() llamada al constructor sin parámetros, que no proporciona una marca Bom y el segundo UTF8Encoding(Boolean) llamando al constructor encoderShouldEmitUTF8Identifier con su argumento establecido en 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. A continuación, llama GetPreamble al método para escribir la marca Bom en un archivo antes de escribir una cadena codificada en UF8.It then calls the GetPreamble method to write the BOM to a file before writing a UF8-encoded string. Como muestra la salida de la consola del ejemplo, el archivo que guarda los bytes del segundo codificador tiene tres bytes más que el primero.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.

También puede comparar los archivos mediante el fc comando en una ventana de la consola o puede inspeccionar los archivos en un editor de texto que incluye un modo de vista hexadecimal.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. Tenga en cuenta que cuando el archivo se abre en un editor que admite UTF-8, no se muestra la marca BOM.Note that when the file is opened in an editor that supports UTF-8, the BOM is not displayed.

Comentarios

El UTF8Encoding objeto puede proporcionar un preámbulo, que es una matriz de bytes que se puede anteponer a la secuencia de bytes resultante del proceso de codificación.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. Delante de 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 los bytes y el formato de transformación, o 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. La marca de orden de bytes Unicode (BOM) se serializa como 0xEF 0xBB 0xBF.The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Tenga en cuenta que el estándar Unicode no requiere ni recomienda el uso de una BOM para secuencias con codificación UTF-8.Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams.

Puede crear instancias de un UTF8Encoding objeto cuyo GetPreamble método devuelva una marca Bom válida de las maneras siguientes:You can instantiate a UTF8Encoding object whose GetPreamble method returns a valid BOM in the following ways:

  • Recuperando el UTF8Encoding objeto devuelto por la Encoding.UTF8 propiedad.By retrieving the UTF8Encoding object returned by the Encoding.UTF8 property.

  • Llamando a un UTF8Encoding constructor con un encoderShouldEmitUTF8Identifier parámetro y estableciendo su valor establecido en true.By calling a UTF8Encoding constructor with a encoderShouldEmitUTF8Identifier parameter and setting its value set to true.

Todos los UTF8Encoding demás objetos se configuran para devolver una matriz vacía en lugar de una marca Bom válida.All other UTF8Encoding objects are configured to return an empty array rather than a valid BOM.

La marca BOM proporciona casi cierta identificación de una codificación para los archivos que, de otro modo, 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 tiene problemas internacionales.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. A menudo se pueden evitar problemas de usuario si los datos se etiquetan de forma coherente y adecuada.Often user problems might be avoided if data is consistently and properly tagged.

En el caso de los estándares que proporcionan un tipo de codificación, una BOM es algo redundante.For standards that provide an encoding type, a BOM is somewhat redundant. Sin embargo, se puede usar para ayudar a un servidor a enviar el encabezado de codificación correcto.However, it can be used to help a server send the correct encoding header. Como alternativa, se puede usar como reserva en caso de que, de lo contrario, se pierda la codificación.Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

El uso de una marca BOM tiene algunas desventajas.There are some disadvantages to using a BOM. Por ejemplo, saber cómo limitar los campos de base de datos que usan una marca BOM puede ser difícil.For example, knowing how to limit the database fields that use a BOM can be difficult. 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.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. Sin embargo, a pesar de los pocos inconvenientes, se recomienda encarecidamente el uso de una marca BOM.In spite of the few disadvantages, however, the use of a BOM is highly recommended.

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

Importante

Para asegurarse de que los bytes codificados se descodifican correctamente cuando se guardan como un archivo o como un flujo, puede prefijar el principio de una secuencia de bytes codificados con un 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. Tenga en cuenta GetBytes que el método no antepone una marca Bom a una secuencia de bytes codificados; proporcionar una marca Bom al principio de un flujo de bytes adecuado es responsabilidad del desarrollador.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.

Se aplica a