UTF8Encoding.GetPreamble Metodo

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

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Restituisce

Matrice di byte contenente il byte order mark Unicode, se l'oggetto di codifica UTF8Encoding è configurato per fornirne uno. In caso contrario, questo metodo restituisce una matrice di byte di lunghezza zero.

Esempio

Nell'esempio seguente viene usato il metodo per restituire il contrassegno dell'ordine GetPreamble di byte Unicode codificato in formato UTF-8. Si noti che il costruttore senza parametri per UTF8Encoding non fornisce un preambolo.

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

L'esempio seguente crea un'istanza di due UTF8Encoding oggetti, il primo chiamando il costruttore senza UTF8Encoding() parametri, che non fornisce una boma e il secondo chiamando il costruttore con il UTF8Encoding(Boolean) relativo encoderShouldEmitUTF8Identifier argomento impostato su true. Chiama quindi il metodo per scrivere la GetPreamble BOM in un file prima di scrivere una stringa codificata con codifica UF8. Come illustrato dall'output della console nell'esempio, il file che salva i byte dal secondo codificatore ha tre byte superiori al primo.

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.

È anche possibile confrontare i file usando il fc comando in una finestra della console oppure è possibile esaminare i file in un editor di testo che include una modalità visualizzazione hex. Si noti che quando il file viene aperto in un editor che supporta UTF-8, la bom non viene visualizzata.

Commenti

L'oggetto UTF8Encoding può fornire un preambolo, ovvero una matrice di byte che può essere preceduta dalla sequenza di byte risultante dal processo di codifica. La prefazione di una sequenza di byte codificati con un contrassegno ordine di byte (punto di codice U+FEFF) consente al decodificatore di determinare l'ordine di byte e il formato di trasformazione o UTF. Il contrassegno dell'ordine di byte Unicode (BOM) viene serializzato come 0xEF 0xBB 0xBF. Si noti che lo standard Unicode non richiede né consiglia l'uso di un BOM per i flussi codificati UTF-8.

È possibile creare un'istanza di un oggetto il cui GetPreamble metodo restituisce una UTF8Encoding BOM valida nei modi seguenti:

• Recuperando l'oggetto UTF8EncodingEncoding.UTF8 restituito dalla proprietà .

• Chiamando un costruttore con un UTF8EncodingencoderShouldEmitUTF8Identifier parametro e impostandone il valore impostato su true.

Tutti gli altri UTF8Encoding oggetti sono configurati per restituire una matrice vuota anziché una BOM valida.

La BOM fornisce quasi certamente un'identificazione di una codifica per i file che altrimenti hanno perso un riferimento alla loro codifica, ad esempio dati Web non contrassegnati o non contrassegnati in modo errato o file di testo casuali archiviati quando un'azienda non ha problemi internazionali. Spesso i problemi utente potrebbero essere evitati se i dati vengono contrassegnati in modo coerente e corretto.

Per gli standard che forniscono un tipo di codifica, un BOM è piuttosto ridondante. Tuttavia, può essere utilizzato per consentire a un server di inviare l'intestazione di codifica corretta. In alternativa, può essere utilizzato come fallback in caso contrario, la codifica andrà persa.

L'utilizzo di un BOM presenta alcuni svantaggi. Ad esempio, sapere come limitare i campi del database che utilizzano un BOM può essere difficile. Anche la concatenazione di file può costituire un problema, ad esempio quando i file vengono uniti in modo tale che un carattere non necessario possa finire nel mezzo dei dati. Nonostante i pochi svantaggi, tuttavia, l'utilizzo di un BOM è altamente consigliato.

Per ulteriori informazioni sull'ordine dei byte e sulla byte order mark, vedere lo standard Unicode nella Home Page Unicode.

Si applica a