UnicodeEncoding.GetPreamble Methode

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Gibt zurück

Ein Bytearray, das die Unicode-Bytereihenfolgemarke enthält, wenn das UnicodeEncoding Objekt so konfiguriert ist, dass eins angegeben wird. Andernfalls gibt diese Methode ein Bytearray der Länge Null zurück.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie GetPreamble die Methode verwendet wird, um die Unicode-Bytereihenfolge in einer Instanz eines UnicodeEncodingByte-Elements in big endian oder little endian byte order abzurufen.

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

Im folgenden Beispiel werden zwei UnicodeEncoding Objekte instanziiert, von denen der erste keine BOM bereitstellt und die zweite instanziiert. Anschließend wird die Methode aufgerufen, um die GetPreamble BOM in eine Datei zu schreiben, bevor eine Unicode-codierte Zeichenfolge geschrieben wird. Wie die Konsolenausgabe aus dem Beispiel zeigt, hat die Datei, die die Bytes aus dem zweiten Encoder speichert, drei mehr Bytes als die erste.

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.

Sie können die Dateien auch mithilfe des fc Befehls in einem Konsolenfenster vergleichen, oder Sie können die Dateien in einem Text-Editor prüfen, der einen Hex-Ansichtsmodus enthält. Beachten Sie, dass die BOM nicht angezeigt wird, wenn die Datei in einem Editor geöffnet wird, der UTF-16-Codierung unterstützt.

Hinweise

Das UnicodeEncoding Objekt kann eine Präambel bereitstellen, bei der es sich um ein Bytearray handelt, das der Sequenz von Bytes vorangestellt werden kann, die sich aus dem Codierungsprozess ergibt. Durch das Voranstellen einer Sequenz codierter Bytes mit einem Bytereihenfolgezeichen (Codepunkt U+FEFF) kann der Decoder die Bytereihenfolge und das Transformationsformat oder UTF bestimmen. Das Unicode-Bytereihenfolgezeichen (BOM) wird wie folgt serialisiert (hexadezimal):

• Big endian byte order: FE FF

• Little endian byte order: FF FE

Sie können ein UnicodeEncoding Objekt instanziieren, dessen GetPreamble Methode eine gültige BOM auf folgende Weise zurückgibt:

• Durch Abrufen des objekts, das UnicodeEncoding von der Eigenschaft Encoding.BigEndianUnicode oder der Encoding.Unicode Eigenschaft zurückgegeben wird.

• Durch Aufrufen des parameterlosen UnicodeEncoding() Konstruktors zum Instanziieren eines UnicodeEncoding Objekts.

• Durch Angabe true des Werts des byteOrderMark Arguments an die UnicodeEncoding(Boolean, Boolean) Konstruktoren.UnicodeEncoding(Boolean, Boolean, Boolean)

Es wird empfohlen, die BOM zu verwenden, da sie nahezu bestimmte Identifizierung einer Codierung für Dateien bereitstellt, die andernfalls einen Verweis auf ihre Codierung verloren haben, z. B. nicht markierte oder nicht ordnungsgemäß markierte Webdaten oder zufällige Textdateien, die gespeichert wurden, wenn ein Unternehmen keine internationalen Bedenken hatte. Häufig können Benutzerprobleme vermieden werden, wenn Daten konsistent und ordnungsgemäß markiert sind.

Für Standards, die einen Codierungstyp bereitstellen, ist eine BOM etwas redundant. Es kann jedoch verwendet werden, um einem Server zu helfen, den richtigen Codierungsheader zu senden. Alternativ kann sie als Fallback verwendet werden, falls die Codierung andernfalls verloren geht.

Es gibt einige Nachteile bei der Verwendung einer BOM. Beispielsweise kann es schwierig sein, die Datenbankfelder zu beschränken, die eine BOM verwenden. Die Verkettung von Dateien kann beispielsweise auch ein Problem sein, wenn Dateien so zusammengeführt werden, dass ein unnötiges Zeichen in der Mitte der Daten enden kann. Trotz der wenigen Nachteile wird die Verwendung eines BOM jedoch dringend empfohlen.