UTF8Encoding.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-Bytereihenfolgemarkierung enthält, wenn das UTF8Encoding-Codierungsobjekt dafür konfiguriert ist, eine bereitzustellen. Andernfalls gibt diese Methode ein Bytearray mit der Länge Null zurück.

Beispiele

Im folgenden Beispiel wird die GetPreamble -Methode verwendet, um die Im UTF-8-Format codierte Unicode-Bytereihenfolge zurückzugeben. Beachten Sie, dass der parameterlose Konstruktor für UTF8Encoding keine Präambel bereitstellt.

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

Im folgenden Beispiel werden zwei UTF8Encoding -Objekte instanziiert: das erste durch Aufrufen des parameterlosen UTF8Encoding() Konstruktors, der keine BOM bereitstellt, und das zweite durch Aufrufen des UTF8Encoding(Boolean) Konstruktors, dessen encoderShouldEmitUTF8Identifier Argument auf truefestgelegt ist. Anschließend wird die GetPreamble -Methode aufgerufen, um die BoM vor dem Schreiben einer UF8-codierten Zeichenfolge in eine Datei zu schreiben. Wie die Konsolenausgabe aus dem Beispiel zeigt, enthält die Datei, die die Bytes aus dem zweiten Encoder speichert, drei Bytes mehr als der 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-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.

Sie können die Dateien auch mit dem fc Befehl in einem Konsolenfenster vergleichen, oder Sie können die Dateien in einem Text-Editor überprü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-8 unterstützt.

Hinweise

Das UTF8Encoding -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 ergeben. Das Vorabfacieren einer Sequenz codierter Bytes mit einer Bytereihenfolgenmarkierung (Codepunkt U+FEFF) hilft dem Decoder, die Bytereihenfolge und das Transformationsformat (UTF) zu bestimmen. Die Unicode-Bytereihenfolgenmarkierung (Unicode Byte Order Mark, BOM) wird als 0xEF 0xBB 0xBF serialisiert. Beachten Sie, dass der Unicode-Standard weder die Verwendung einer BOM für UTF-8-codierte Streams erfordert noch empfiehlt.

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

• Durch Abrufen des UTF8Encoding von der Encoding.UTF8 -Eigenschaft zurückgegebenen Objekts.

• Indem Sie einen UTF8Encoding Konstruktor mit einem encoderShouldEmitUTF8Identifier Parameter aufrufen und dessen Wert auf truefestlegen.

Alle anderen UTF8Encoding Objekte sind so konfiguriert, dass sie anstelle einer gültigen BoM ein leeres Array zurückgeben.

Die BOM bietet nahezu eine bestimmte Identifizierung einer Codierung für Dateien, 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 hatte. Häufig können Benutzerprobleme vermieden werden, 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.

Weitere Informationen zur Byte Reihenfolge und zur Byte Reihenfolge-Markierung finden Sie im Unicode-Standard auf der Unicode-Homepage.

Gilt für: