UTF32Encoding.GetPreamble Methode

Referenz

Definition

Namespace:: System.Text

Assemblys:: mscorlib.dll, System.Text.Encoding.Extensions.dll

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 Unicode-Bytereihenfolgemarkierung im UTF-32-Format zurück, wenn das UTF32Encoding-Objekt dafür konfiguriert ist, eine solche bereitzustellen.

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 UTF32Encoding-Objekt dafür konfiguriert ist, eine bereitzustellen. Andernfalls gibt diese Methode ein Bytearray mit der Länge Null zurück.

Beispiele

Im folgenden Codebeispiel wird das Bytereihenfolgezeichen für verschiedene UTF32Encoding Instanzen abgerufen und angezeigt.

using namespace System;
using namespace System::Text;

void PrintHexBytes( array<Byte>^bytes );

int main()
{
   
   // Create instances of UTF32Encoding, with the byte order mark and without.
   UTF32Encoding ^ u32LeNone = gcnew UTF32Encoding;
   UTF32Encoding ^ u32BeNone = gcnew UTF32Encoding( true,false );
   UTF32Encoding ^ u32LeBom = gcnew UTF32Encoding( false,true );
   UTF32Encoding ^ u32BeBom = gcnew UTF32Encoding( true,true );
   
   // Display the preamble for each instance.
   PrintHexBytes( u32LeNone->GetPreamble() );
   PrintHexBytes( u32BeNone->GetPreamble() );
   PrintHexBytes( u32LeBom->GetPreamble() );
   PrintHexBytes( u32BeBom->GetPreamble() );
}

void PrintHexBytes( array<Byte>^bytes )
{
   if ( (bytes == nullptr) || (bytes->Length == 0) )
      Console::WriteLine( "<none>" );
   else
   {
      for ( int i = 0; i < bytes->Length; i++ )
         Console::Write( "{0:X2} ", bytes[ i ] );
      Console::WriteLine();
   }
}

/* 
This example displays the following output:
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

using System;
using System.Text;

public class SamplesUTF32Encoding
{
   public static void Main()
   {
      // Create instances of UTF32Encoding, with the byte order mark and without.
      UTF32Encoding u32LeNone = new UTF32Encoding();
      UTF32Encoding u32BeNone = new UTF32Encoding( true, false );
      UTF32Encoding u32LeBom  = new UTF32Encoding( false, true );
      UTF32Encoding u32BeBom  = new UTF32Encoding( true, true );

      // Display the preamble for each instance.
      PrintHexBytes( u32LeNone.GetPreamble() );
      PrintHexBytes( u32BeNone.GetPreamble() );
      PrintHexBytes( u32LeBom.GetPreamble() );
      PrintHexBytes( u32BeBom.GetPreamble() );
   }

   public static void PrintHexBytes( byte[] bytes )
   {

      if (( bytes == null ) || ( bytes.Length == 0 ))
        {
            Console.WriteLine( "<none>" );
        }
        else  {
         for ( int i = 0; i < bytes.Length; i++ )
            Console.Write( "{0:X2} ", bytes[i] );
         Console.WriteLine();
      }
   }
}
/*
This example displays the following output.
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

Imports System.Text

Public Class SamplesUTF32Encoding   
   Public Shared Sub Main()
      ' Create instances of UTF32Encoding, with the byte order mark and without.
      Dim u32LeNone As New UTF32Encoding()
      Dim u32BeNone As New UTF32Encoding(True, False)
      Dim u32LeBom As New UTF32Encoding(False, True)
      Dim u32BeBom As New UTF32Encoding(True, True)

      ' Display the preamble for each instance.
      PrintHexBytes(u32LeNone.GetPreamble())
      PrintHexBytes(u32BeNone.GetPreamble())
      PrintHexBytes(u32LeBom.GetPreamble())
      PrintHexBytes(u32BeBom.GetPreamble())
   End Sub

   Public Shared Sub PrintHexBytes(bytes() As Byte)
      If bytes Is Nothing OrElse bytes.Length = 0 Then
         Console.WriteLine("<none>")
      Else
         Dim i As Integer
         For i = 0 To bytes.Length - 1
            Console.Write("{0:X2} ", bytes(i))
         Next i
         Console.WriteLine()
      End If
   End Sub
End Class
'This example displays the following output:
'       FF FE 00 00
'       FF FE 00 00
'       00 00 FE FF

Im folgenden Beispiel werden zwei UTF32Encoding Objekte instanziiert, die erste Instanziierung, die keine BOM bereitstellt und die zweite instanziiert. Anschließend wird die Methode aufgerufen, um die GetPreamble BOM in eine Datei zu schreiben, bevor eine UTF-32-codierte Zeichenfolge geschrieben wird. Wie die Ausgabe aus dem Beispiel gezeigt wird, weist die Datei, die die Bytes aus dem zweiten Encoder speichert, vier weitere Bytes auf, die zuerst gespeichert werden.

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-32 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF32Encoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF32Encoding(! 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 232 bytes to .\NoPreamble.txt.
//
//       Preamble has 4 bytes
//       Wrote 236 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-32 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF32Encoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF32Encoding(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 232 bytes to NoPreamble.txt.
'
'       Preamble has 4 bytes
'       Wrote 236 bytes to Preamble.txt.

Sie können die Dateien auch mithilfe des fc Befehls in einem Konsolenfenster vergleichen oder die Dateien in einem Text-Editor überprüfen, der einen Hex-Ansichtsmodus enthält. Beachten Sie, dass beim Öffnen der Datei in einem Editor, der UTF-32 unterstützt, die BOM nicht angezeigt wird.

Hinweise

Das UTF32Encoding Objekt kann ein Präamble bereitstellen, das ein Array von Bytes ist, das der Sequenz von Bytes vorangestellt werden kann, die sich aus dem Codierungsprozess ergeben. Durch das Präfacieren einer Sequenz codierter Bytes mit einem Bytereihenfolgezeichen (Codepunkte U+0000 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: 00 00 FE FF
Kleiner endischer Byteauftrag: FF FE 00 00 00

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

Durch Abrufen des objekts, das UTF32Encoding von der Encoding.UTF32 Eigenschaft zurückgegeben wird.
Durch Aufrufen des parameterlosen UTF32Encoding() Konstruktors zum Instanziieren eines UTF32Encoding Objekts.
Durch Angeben true des Werts des byteOrderMark Arguments an die UTF32Encoding und UTF32Encoding Konstruktoren.

Es wird empfohlen, die BOM zu verwenden, da sie nahezu bestimmte Identifizierung einer Codierung für Dateien bereitstellt, die sonst einen Verweis auf das UTF32Encoding Objekt verloren haben, z. B. ungestrichene oder nicht falsch markierte Webdaten oder zufällige Textdateien, die gespeichert sind, wenn ein Unternehmen keine internationalen Bedenken oder andere Daten hat. Häufig können Benutzerprobleme vermieden werden, wenn Daten konsistent und ordnungsgemäß markiert 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.