UTF8Encoding.GetPreamble Methode

Definition

Gibt eine Unicode-Bytereihenfolgemarkierung im UTF-8-Format zurück, wenn das UTF8Encoding-Codierungsobjekt dafür konfiguriert ist, eine bereitzustellen.Returns a Unicode byte order mark encoded in UTF-8 format, if the UTF8Encoding encoding object is configured to supply one.

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 UTF8Encoding-Codierungsobjekt dafür konfiguriert ist, eine bereitzustellen.A byte array containing the Unicode byte order mark, if the UTF8Encoding encoding object is configured to supply one. Andernfalls gibt diese Methode ein Bytearray mit der Länge Null zurück.Otherwise, this method returns a zero-length byte array.

Beispiele

Im folgenden Beispiel wird die GetPreamble -Methode verwendet, um die im UTF-8-Format codierte Unicode-Byte Reihenfolge Markierung zurückzugeben.The following example uses the GetPreamble method to return the Unicode byte order mark encoded in UTF-8 format. Beachten Sie, dass der Parameter lose Konstruktor UTF8Encoding für keine Präambel bereitstellt.Notice that the parameterless constructor for UTF8Encoding does not provide a preamble.

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 UTF8Encoding Beispiel werden zwei-Objekte instanziiert, der erste durch Aufrufen des Parameter losen UTF8Encoding() Konstruktors, der keine BOM bereitstellt, und der zweite, indem der UTF8Encoding(Boolean) -Konstruktor aufgerufen encoderShouldEmitUTF8Identifier wird, dessen Argument auf festgelegt ist. true.The following example instantiates two UTF8Encoding objects, the first by calling the parameterless UTF8Encoding() constructor, which does not provide a BOM, and the second by calling the UTF8Encoding(Boolean) constructor with its encoderShouldEmitUTF8Identifier argument set to true. Anschließend wird die GetPreamble -Methode aufgerufen, um die BOM in eine Datei zu schreiben, bevor eine UF8-codierte Zeichenfolge geschrieben wird.It then calls the GetPreamble method to write the BOM to a file before writing a UF8-encoded string. Wie die Konsolenausgabe aus dem Beispiel zeigt, hat die Datei, die die Bytes aus dem zweiten Encoder speichert, drei weitere Bytes als die erste.As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first.

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 untersuchen, der einen Hex-Ansichtsmodus enthält.You can also compare the files by using the fc command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Beachten Sie, dass die BOM nicht angezeigt wird, wenn die Datei in einem Editor geöffnet wird, der UTF-8 unterstützt.Note that when the file is opened in an editor that supports UTF-8, the BOM is not displayed.

Hinweise

Das UTF8Encoding -Objekt kann eine Präambel bereitstellen, bei der es sich um ein Bytearray handelt, dem die Byte Sequenz vorangestellt werden kann, die sich aus dem Codierungsprozess ergibt.The UTF8Encoding object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes that result from the encoding process. Wenn eine Sequenz codierter Bytes mit einer Byte Reihenfolge-Markierung (Codepunkt U + FEFF) vorangestellt ist, kann der Decoder die Byte Reihenfolge und das Transformations Format (UTF) bestimmen.Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format, or UTF. Die Unicode-Byte Reihenfolge Markierung (BOM) wird als 0xEF 0xBB 0xBF serialisiert.The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Beachten Sie, dass der Unicode-Standard weder erfordert noch die Verwendung einer BOM für UTF-8-codierte Streams empfiehlt.Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams.

Sie können ein UTF8Encoding -Objekt instanziieren GetPreamble , dessen Methode eine gültige BOM auf folgende Weise zurückgibt:You can instantiate a UTF8Encoding object whose GetPreamble method returns a valid BOM in the following ways:

  • Durch Abrufen des- UTF8Encoding Objekts, das von Encoding.UTF8 der-Eigenschaft zurückgegeben wird.By retrieving the UTF8Encoding object returned by the Encoding.UTF8 property.

  • Durch Aufrufen eines UTF8Encoding Konstruktors mit einem encoderShouldEmitUTF8Identifier Parameter und Festlegen seines Werts, der trueauf festgelegt ist.By calling a UTF8Encoding constructor with a encoderShouldEmitUTF8Identifier parameter and setting its value set to true.

Alle anderen UTF8Encoding Objekte werden so konfiguriert, dass Sie ein leeres Array und keine gültige BOM zurückgeben.All other UTF8Encoding objects are configured to return an empty array rather than a valid BOM.

Die BOM bietet fast eine bestimmte Identifizierung einer Codierung für Dateien, 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 nicht über internationale Belange verfügte.The BOM provide nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Häufig können Benutzer Probleme vermieden werden, wenn die Daten konsistent und ordnungsgemäß gekennzeichnet sind.Often user problems might be avoided if data is consistently and properly tagged.

Bei Standards, die einen Codierungstyp bereitstellen, ist eine BOM etwas redundant.For standards that provide an encoding type, a BOM is somewhat redundant. Sie kann jedoch verwendet werden, um einem Server zu helfen, den richtigen Codierungs Header zu senden.However, it can be used to help a server send the correct encoding header. Alternativ kann es als Fall Back für den Fall verwendet werden, dass die Codierung andernfalls verloren geht.Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

Es gibt einige Nachteile bei der Verwendung einer BOM.There are some disadvantages to using a BOM. Beispielsweise kann das Einschränken der Datenbankfelder, die eine BOM verwenden, schwierig sein.For example, knowing how to limit the database fields that use a BOM can be difficult. 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.Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. Trotz der wenigen Nachteile wird die Verwendung einer BOM dringend empfohlen.In spite of the few disadvantages, however, the use of a BOM is highly recommended.

Weitere Informationen zur Byte Reihenfolge und zur Byte Reihenfolge-Markierung finden Sie im Unicode-Standard auf der Unicode-Homepage.For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

Wichtig

Um sicherzustellen, dass die codierten Bytes ordnungsgemäß decodiert werden, wenn Sie als Datei oder als Stream gespeichert werden, können Sie dem Anfang eines Streams codierter Bytes eine Präambel als Präfix voranstellen.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Beachten Sie, GetBytes dass die-Methode einer Sequenz codierter Bytes keine BOM voranstellt. die Bereitstellung einer BOM am Anfang eines entsprechenden Bytestreams ist die Verantwortung des Entwicklers.Note that the GetBytes method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility.

Gilt für: