UnicodeEncoding.GetPreamble Methode

Referenz

Definition

Namespace:: System.Text

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

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Gibt eine im UTF-16-Format codierte Unicode-Bytereihenfolgemarkierung zurück, wenn der Konstruktor für diese Instanz die Bereitstellung einer Bytereihenfolgemarkierung anfordert.

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

Byte[]

Ein Bytearray, das die Unicode-Bytereihenfolgemarkierung enthält, wenn das UnicodeEncoding-Objekt dafür konfiguriert ist, eine bereitzustellen. Andernfalls gibt diese Methode ein Bytearray mit der Länge Null zurück.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie sie die GetPreamble Methode zum Abrufen der Unicode-Bytereihenfolge in big endian oder little endian byte order for an instance of a 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

Im folgenden Beispiel werden zwei UnicodeEncoding Objekte instanziiert, die erste, die keine BOM bereitstellt und die zweite. 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, weist 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 mit dem Befehl in einem Konsolenfenster vergleichen oder die Dateien in einem Text-Editor überprüfen, der fc einen Hex-Ansichtsmodus enthält. Beachten Sie, dass beim Öffnen der Datei in einem Editor, der UTF-16-Codierung unterstützt, die BOM nicht angezeigt wird.

Hinweise

Das UnicodeEncoding Objekt kann eine Präamble bereitstellen, die ein Bytearray ist, das zur Sequenz von Bytes präfixiert werden kann, die aus dem Codierungsprozess resultiert. Durch das Vorfacieren einer Sequenz codierter Bytes mit einem Bytereihenfolgezeichen (Codepunkt U+FEFF) kann der Decoder die Bytereihenfolge und das Transformationsformat oder UTF bestimmen. Die Unicode-Byte Reihenfolge Markierung (BOM) wird wie folgt serialisiert (in Hexadezimal):

Big endian byte order: FE FF
Klein-Endian-Bytereihenfolge: FF FE

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

Durch Abrufen des UnicodeEncoding von der Encoding.Unicode Encoding.BigEndianUnicode Eigenschaft zurückgegebenen Objekts.
Durch Aufrufen des parameterlosen Konstruktors zum Instanziieren UnicodeEncoding() eines UnicodeEncoding Objekts.
Durch Angeben true des Werts des byteOrderMark Arguments an die UnicodeEncoding(Boolean, Boolean) oder UnicodeEncoding(Boolean, Boolean, Boolean) Konstruktoren.

Wir empfehlen, dass Sie das BOM verwenden, da es fast bestimmte Identifizierung einer Codierung für Dateien bereitstellt, die andernfalls einen Verweis auf ihre Codierung verloren haben, z. B. nicht markierte oder falsch markierte Webdaten oder zufällige Textdateien, die gespeichert wurden, wenn ein Unternehmen keine internationalen Bedenken hat. Häufig werden Benutzerprobleme vermieden, wenn Daten konsistent und ordnungsgemäß gekennzeichnet sind.

Bei Standards, die einen Codierungstyp bereitstellen, ist eine BOM etwas redundant. Sie kann jedoch verwendet werden, um einem Server zu helfen, den richtigen Codierungs Header zu senden. Alternativ kann es als Fall Back für den Fall verwendet werden, dass die Codierung andernfalls verloren geht.

Es gibt einige Nachteile bei der Verwendung einer BOM. Beispielsweise kann das Einschränken der Datenbankfelder, die eine BOM verwenden, schwierig sein. Die Verkettung von Dateien kann auch ein Problem darstellen, z. b. 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 einer BOM dringend empfohlen.