UTF32Encoding.GetPreamble Metoda

Odwołanie

Definicja

Przestrzeń nazw:: System.Text

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

Zestaw:: System.Text.Encoding.Extensions.dll

Zestaw:: mscorlib.dll

Zestaw:: netstandard.dll

Ważne

Niektóre informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany przed wydaniem. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Zwraca znacznik kolejności bajtów Unicode zakodowany w formacie UTF-32, jeśli UTF32Encoding obiekt jest skonfigurowany do podawania jednego.

public:
 override cli::array <System::Byte> ^ GetPreamble();

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Zwraca

Byte[]

Tablica bajtów zawierająca znak kolejności bajtów Unicode, jeśli UTF32Encoding obiekt jest skonfigurowany do podawania. W przeciwnym razie ta metoda zwraca tablicę bajtów o zerowej długości.

Przykłady

Poniższy przykład kodu pobiera i wyświetla znacznik kolejności bajtów dla różnych UTF32Encoding wystąpień.

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

Poniższy przykład tworzy wystąpienie dwóch UTF32Encoding obiektów, z których pierwszy nie udostępnia modelu BOM, a drugi z nich. Następnie wywołuje metodę GetPreamble , aby zapisać model BOM w pliku przed zapisaniem ciągu zakodowanego w formacie UTF-32. Jak pokazano w danych wyjściowych z przykładu, plik, który zapisuje bajty z drugiego kodera, ma cztery bajty więcej niż pierwszy.

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.

Możesz również porównać pliki przy użyciu fc polecenia w oknie konsoli lub sprawdzić pliki w edytorze tekstów, który zawiera tryb widoku szesnastkowego. Należy pamiętać, że po otwarciu pliku w edytorze obsługującym protokół UTF-32 model BOM nie jest wyświetlany.

Uwagi

Obiekt UTF32Encoding może zapewnić prefiks, który jest tablicą bajtów, które mogą być poprzedzone sekwencją bajtów wynikających z procesu kodowania. Wstępne tworzenie sekwencji zakodowanych bajtów za pomocą znaku kolejności bajtów (punkty kodu U+0000 U+FEFF) pomaga dekoderowi określić kolejność bajtów i format transformacji lub UTF. Znak kolejności bajtów Unicode (BOM) jest serializowany w następujący sposób (w formacie szesnastkowym):

Kolejność bajtów big endian: 00 00 FE FF
Mała kolejność bajtów endian: FF FE 00 00

Można utworzyć UTF32Encoding wystąpienie obiektu, którego GetPreamble metoda zwraca prawidłowy obiekt BOM w następujący sposób:

Przez pobranie UTF32Encoding obiektu zwróconego Encoding.UTF32 przez właściwość .
Wywołując konstruktor bez UTF32Encoding() parametrów w celu utworzenia UTF32Encoding wystąpienia obiektu.
true Podając jako wartość argumentu byteOrderMark dla UTF32Encoding konstruktorów i UTF32Encoding .

Zalecamy użycie modelu BOM, ponieważ zapewnia niemal pewną identyfikację kodowania plików, które w przeciwnym razie utraciły odwołanie do UTF32Encoding obiektu, na przykład nieotagowane lub nieprawidłowo oznakowane dane internetowe lub losowe pliki tekstowe przechowywane, gdy firma nie ma międzynarodowych problemów lub innych danych. Często można uniknąć problemów z użytkownikami, jeśli dane są stale i prawidłowo oznakowane.

W przypadku standardów zapewniających typ kodowania model BOM jest nieco nadmiarowy. Można go jednak użyć do ułatwienia serwerowi wysyłania poprawnego nagłówka kodowania. Alternatywnie można go użyć jako rezerwowego w przypadku utraty kodowania.

Istnieją pewne wady korzystania z modelu BOM. Na przykład wiedza na temat ograniczania pól bazy danych korzystających z modelu BOM może być trudna. Łączenie plików może być również problemem, na przykład gdy pliki są scalane w taki sposób, że niepotrzebny znak może znajdować się w środku danych. Pomimo kilku wad stosowanie modelu BOM jest jednak zdecydowanie zalecane.

Aby uzyskać więcej informacji na temat kolejności bajtów i znacznika kolejności bajtów, zobacz Standard Unicode na stronie głównej Unicode.