Encoding.GetPreamble (Método) (System.Text)

GetPreamble (Método)

Contraer todo

Filtro de idioma

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Microsoft Visual Studio 2005/.NET Framework 2.0

Biblioteca de clases de .NET Framework

Encoding..::.GetPreamble (Método)

Cuando se reemplaza en una clase derivada, devuelve una secuencia de bytes que especifica la codificación utilizada.

Espacio de nombres: System.Text
Ensamblado: mscorlib (en mscorlib.dll)

Sintaxis

Visual Basic (Declaración)

Public Overridable Function GetPreamble As Byte()

Visual Basic (Uso)

Dim instance As Encoding
Dim returnValue As Byte()

returnValue = instance.GetPreamble()

public virtual byte[] GetPreamble()

Visual C++

public:
virtual array<unsigned char>^ GetPreamble()

public byte[] GetPreamble()

JScript

public function GetPreamble() : byte[]

Valor devuelto

Tipo: array< System..::.Byte >[]()[]

Una matriz de bytes que contiene una secuencia de bytes que especifica la codificación utilizada.

O bien

Una matriz de bytes de longitud cero, si no se requiere un preámbulo.

Comentarios

Opcionalmente, el objeto Encoding proporciona un preámbulo que es una matriz de bytes que se puede anteponer a la secuencia de bytes resultante del proceso de codificación. Si el preámbulo contiene una marca de orden de bytes (en Unicode, el punto de código U+FEFF), ayudará al descodificador a determinar el orden de bytes y el formato de la transformación o UTF.

La marca de orden de bytes Unicode (BOM) se serializa de la siguiente manera (en hexadecimal):

UTF-8: EF BB BF
El orden de bytes big endian de UTF-16: FE FF
El orden de bytes little endian de UTF-16: FF FE
El orden de bytes big endian de UTF-32: 00 00 FE FF
El orden de bytes little endian de UTF-32: FF FE 00 00

Se recomienda que use BOM en las aplicaciones, ya que proporciona cierta identificación de una codificación para los archivos que han perdido de otro modo la referencia al objeto Encoding, por ejemplo, datos de web sin etiqueta o incorrectamente etiquetados o archivos de texto aleatorios almacenados cuando un negocio no tenía intereses internacionales u otros datos. A menudo se podrían evitar problemas al usuario si los datos se etiquetan de forma consistente y correcta, preferentemente en UTF-8 o UTF-16.

Para los estándares que proporcionan un tipo de codificación, BOM es redundante en cierto modo. Sin embargo, se puede usar como ayuda para que un servidor envíe el encabezado de codificación correcto. Opcionalmente, se puede usar como reserva por si se pierde la codificación de algún modo.

El uso de BOM tiene ciertos inconvenientes. Por ejemplo, puede resultar difícil saber cómo limitar los campos de la base de datos que usan BOM. La concatenación de archivos también puede ser un problema, por ejemplo, cuando los archivos se combinan de modo que un carácter innecesario queda en medio de los datos. No obstante, a pesar de ciertos inconvenientes, se recomienda encarecidamente usar BOM.

Para obtener más información sobre el orden de bytes y la marca de orden de bytes, vea The Unicode Standard en Unicode home page

Precaución:
Para garantizar la correcta descodificación de los bytes codificados, éstos deben llevar un preámbulo como prefijo en la aplicación. No obstante, la mayoría de las codificaciones no proporcionan un preámbulo. Para garantizar la correcta descodificación de los bytes codificados, debe usar en la aplicación una codificación Unicode (es decir, UTF8Encoding, UnicodeEncoding o UTF32Encoding) con un preámbulo.

Precaución:

Para garantizar la correcta descodificación de los bytes codificados, éstos deben llevar un preámbulo como prefijo en la aplicación. No obstante, la mayoría de las codificaciones no proporcionan un preámbulo. Para garantizar la correcta descodificación de los bytes codificados, debe usar en la aplicación una codificación Unicode (es decir, UTF8Encoding, UnicodeEncoding o UTF32Encoding) con un preámbulo.

Ejemplos

En el ejemplo de código siguiente se determina el orden de bytes de la codificación basándose en el preámbulo.

Visual Basic

Imports System
Imports System.Text

Namespace GetPreambleExample
   Class GetPreambleExampleClass
      Shared Sub Main()
         Dim [unicode] As Encoding = Encoding.Unicode

         ' Get the preamble for the Unicode encoder. 
         ' In this case the preamble contains the byte order mark (BOM).
         Dim preamble As Byte() = [unicode].GetPreamble()

         ' Make sure a preamble was returned 
         ' and is large enough to contain a BOM.
         If preamble.Length >= 2 Then
            If preamble(0) = &HFE And preamble(1) = &HFF Then
               Console.WriteLine("The Unicode encoder is encoding in big-endian order.")
            Else
               If preamble(0) = &HFF And preamble(1) = &HFE Then
                  Console.WriteLine("The Unicode encoder is encoding in little-endian order.")
               End If
            End If
         End If
      End Sub
   End Class
End Namespace

using System;
using System.Text;

namespace GetPreambleExample
{
   class GetPreambleExampleClass
   {
      static void Main()
      {
         Encoding unicode = Encoding.Unicode;

         // Get the preamble for the Unicode encoder. 
         // In this case the preamble contains the byte order mark (BOM).
         byte[] preamble = unicode.GetPreamble();

         // Make sure a preamble was returned 
         // and is large enough to containa BOM.
         if(preamble.Length >= 2)
         {
            if(preamble[0] == 0xFE && preamble[1] == 0xFF)
            {
               Console.WriteLine("The Unicode encoder is encoding in big-endian order.");
            }
            else if(preamble[0] == 0xFF && preamble[1] == 0xFE)
            {
               Console.WriteLine("The Unicode encoder is encoding in little-endian order.");
            }
         }
      }
   }
}

Visual C++

using namespace System;
using namespace System::Text;
int main()
{
   Encoding^ unicode = Encoding::Unicode;

   // Get the preamble for the Unicode encoder. 
   // In this case the preamblecontains the Byte order mark (BOM).
   array<Byte>^preamble = unicode->GetPreamble();

   // Make sure a preamble was returned 
   // and is large enough to containa BOM.
   if ( preamble->Length >= 2 )
   {

      // if (preamble->Item[0] == 0xFE && preamble->Item[1] == 0xFF) 
      if ( preamble[ 0 ] == 0xFE && preamble[ 1 ] == 0xFF )
      {
         Console::WriteLine( "The Unicode encoder is encoding in big-endian order." );
      }
      // else if (preamble->Item[0] == 0xFF && preamble->Item[1] == 0xFE) 
      else

      // else if (preamble->Item[0] == 0xFF && preamble->Item[1] == 0xFE) 
      if ( preamble[ 0 ] == 0xFF && preamble[ 1 ] == 0xFE )
      {
         Console::WriteLine( "The Unicode encoder is encoding in little-endian order." );
      }
   }
}

package GetPreambleExample; 

import System.*;
import System.Text.*;

class GetPreambleExampleClass
{
    public static void main(String[] args)
    {
        Encoding unicode = Encoding.get_Unicode();

        // Get the preamble for the Unicode encoder. 
        // In this case the preamble contains the byte order mark (BOM).
        ubyte preamble[] = unicode.GetPreamble();

        // Make sure a preamble was returned 
        // and is large enough to containa BOM.
        if(preamble.length >= 2) {
            if(preamble[0] == 0xFE && preamble[1] == 0xFF) {
                Console.WriteLine("The Unicode encoder is "
                + "encoding in big-endian order.");
            }
            else {
                if(preamble[0] == 0xFF && preamble[1] == 0xFE) {
                    Console.WriteLine("The Unicode encoder is" 
                    + " encoding in little-endian order.");
                }
            }
        }
    } //main
} //GetPreambleExampleClass

Plataformas

Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile para Smartphone, Windows Mobile para Pocket PC, Xbox 360

.NET Framework y .NET Compact Framework no admiten todas las versiones de cada plataforma. Para obtener una lista de las versiones compatibles, vea Requisitos de sistema de .NET Framework.

Información de versión