UnicodeEncoding.GetPreamble Metodo

Riferimento

Definizione

Spazio dei nomi:: System.Text

Assembly:: System.Text.Encoding.Extensions.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Importante

Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Restituisce un byte order mark e Unicode codificato in formato UTF-16, se il costruttore per questa istanza ne ha richiesto la presenza.

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

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Restituisce

Byte[]

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

Esempio

Nell'esempio seguente viene illustrato come usare il metodo per recuperare il GetPreamble contrassegno di byte Unicode in ordine di byte big endian o little endian per un'istanza di .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

L'esempio seguente crea un'istanza di due UnicodeEncoding oggetti, il primo dei quali non fornisce una distinta base e il secondo di cui esegue l'operazione. Chiama quindi il GetPreamble metodo per scrivere la distinta base in un file prima di scrivere una stringa con codifica Unicode. Come illustrato nell'output della console dell'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-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.

È anche possibile confrontare i file usando il fc comando in una finestra della console oppure esaminare i file in un editor di testo che include una modalità Visualizzazione esadecimale. Si noti che quando il file viene aperto in un editor che supporta la codifica UTF-16, la distinta base non viene visualizzata.

Commenti

L'oggetto UnicodeEncoding 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 byte order mark (punto di codice U+FEFF) consente al decodificatore di determinare l'ordine dei byte e il formato di trasformazione o UTF. Il byte order mark Unicode (BOM) viene serializzato come indicato di seguito (in esadecimale):

Ordine dei byte big endian: FE FF
Ordine dei byte little endian: FF FE

È possibile creare un'istanza di un UnicodeEncoding oggetto il cui GetPreamble metodo restituisce un BOM valido nei modi seguenti:

Recuperando l'oggetto UnicodeEncoding restituito dalla Encoding.Unicode proprietà o Encoding.BigEndianUnicode .
Chiamando il costruttore senza UnicodeEncoding() parametri per creare un'istanza di un UnicodeEncoding oggetto .
Specificando true come valore dell'argomento byteOrderMark ai UnicodeEncoding(Boolean, Boolean) costruttori o UnicodeEncoding(Boolean, Boolean, Boolean) .

È consigliabile usare la distinta base, poiché fornisce quasi certamente un'identificazione di una codifica per i file che altrimenti hanno perso un riferimento alla loro codifica, ad esempio dati Web senza tag o file di testo casuali con tag o file di testo casuali archiviati quando un'azienda non ha problemi internazionali. Spesso è possibile evitare problemi utente se i dati sono 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.