UnicodeEncoding.GetPreamble Methode

Definition

Gibt eine im UTF-16-Format codierte Unicode-Bytereihenfolgemarkierung zurück, wenn der Konstruktor für diese Instanz die Bereitstellung einer Bytereihenfolgemarkierung anfordert.Returns a Unicode byte order mark encoded in UTF-16 format, if the constructor for this instance requests a byte order mark.

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.A byte array containing the Unicode byte order mark, if the UnicodeEncoding 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 veranschaulicht, wie die GetPreamble -Methode verwendet wird, um die Unicode-Byte Reihenfolge Markierung in Big Endian oder Little-Endian- UnicodeEncodingByte Reihenfolge für eine-Instanz abzurufen.The following example demonstrates how to use the GetPreamble method to retrieve the Unicode byte order mark in big endian or 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, wobei das erste-Objekt keine BOM bereitstellt und das zweite-Objekt.The following example instantiates two UnicodeEncoding objects, the first of which does not provide a BOM, and the second of which does. Anschließend wird die GetPreamble -Methode aufgerufen, um die BOM in eine Datei zu schreiben, bevor eine Unicode-codierte Zeichenfolge geschrieben wird.It then calls the GetPreamble method to write the BOM to a file before writing a Unicode-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-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 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-16-Codierung unterstützt.Note that when the file is opened in an editor that supports UTF-16 encoding, the BOM is not displayed.

Hinweise

Das UnicodeEncoding -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 UnicodeEncoding object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes resulting 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 oder UTF festlegen.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 wie folgt serialisiert (in Hexadezimal):The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal):

  • Big-Endian-Byte Reihenfolge: FE FFBig endian byte order: FE FF

  • Little-Endian-Byte Reihenfolge: FF FELittle endian byte order: FF FE

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

Es wird empfohlen, die BOM zu verwenden, da Sie eine 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 Zufalls Textdateien, die gespeichert wurden, wenn ein Unternehmen nicht über internationale Probleme.We recommended that you use the BOM, since it provides 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.

Wichtig

Um sicherzustellen, dass die codierten Bytes ordnungsgemäß decodiert werden, sollten Sie dem Anfang eines Streams codierter Bytes eine Präambel vorangestellt sein.To ensure that the encoded bytes are decoded properly, you should 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: