UnicodeEncoding.GetPreamble Metoda

Definicja

Namespace:

System.Text

Zestawów:

netstandard.dll, System.Text.Encoding.Extensions.dll

Źródło:

UnicodeEncoding.cs

Zwraca znacznik kolejności bajtów Unicode zakodowany w formacie UTF-16, jeśli konstruktor dla tego wystąpienia żąda znaku kolejności bajtów.

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 UnicodeEncoding obiekt jest skonfigurowany do podawania. W przeciwnym razie ta metoda zwraca tablicę bajtów o zerowej długości.

Przykłady

W poniższym przykładzie pokazano, jak użyć GetPreamble metody w celu pobrania znacznika kolejności bajtów Unicode w kolejności bajtów UnicodeEncodingbig endian lub little endian dla wystąpienia klasy .

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

Poniższy przykład tworzy wystąpienie dwóch UnicodeEncoding 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 Unicode. Jak pokazuje dane wyjściowe konsoli z przykładu, plik, który zapisuje bajty z drugiego kodera, ma trzy 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-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.

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 kodowanie UTF-16 model BOM nie jest wyświetlany.

Uwagi

Obiekt UnicodeEncoding może zapewnić prefiks, który jest tablicą bajtów, która może być poprzedzona sekwencją bajtów wynikających z procesu kodowania. Wstępne tworzenie sekwencji zakodowanych bajtów za pomocą znaku kolejności bajtów (punkt kodu 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: FE FF

• Mała kolejność bajtów endian: FF FE

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

• Przez pobranie UnicodeEncoding obiektu zwróconego Encoding.Unicode przez właściwość lub Encoding.BigEndianUnicode .

• Wywołując konstruktor bez UnicodeEncoding() parametrów w celu utworzenia UnicodeEncoding wystąpienia obiektu.

• true Podając jako wartość argumentu byteOrderMark konstruktorom UnicodeEncoding(Boolean, Boolean) lub UnicodeEncoding(Boolean, Boolean, Boolean) .

Zalecamy użycie modelu BOM, ponieważ zapewnia niemal pewną identyfikację kodowania plików, które w przeciwnym razie utraciły odwołanie do ich kodowania, takie jak nieotagowane lub nieprawidłowo oznakowane dane internetowe lub losowe pliki tekstowe przechowywane, gdy firma nie ma międzynarodowych problemów. 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.

Ważne

Aby upewnić się, że zakodowane bajty są prawidłowo dekodowane, należy prefiks początku strumienia zakodowanych bajtów z prefiksem. Należy pamiętać, że GetBytes metoda nie poprzedza modelu BOM sekwencją zakodowanych bajtów. Dostarczanie modelu BOM na początku odpowiedniego strumienia bajtów jest obowiązkiem dewelopera.