UTF8Encoding.GetPreamble Metoda

Definicja

Przestrzeń nazw:

System.Text

Zestaw:

System.Text.Encoding.Extensions.dll

Źródło:

UTF8Encoding.cs

Zwraca znak kolejności bajtów Unicode zakodowany w formacie UTF-8, jeśli UTF8Encoding obiekt kodowania jest skonfigurowany do podawania.

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 znacznik kolejności bajtów Unicode, jeśli obiekt kodowania jest skonfigurowany do podawania UTF8Encoding . W przeciwnym razie ta metoda zwraca tablicę bajtów o zerowej długości.

Przykłady

W poniższym przykładzie użyto GetPreamble metody , aby zwrócić znak kolejności bajtów Unicode zakodowany w formacie UTF-8. Zwróć uwagę, że konstruktor bez parametrów dla parametrów UTF8Encoding nie stanowi preambuły.

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

Poniższy przykład tworzy wystąpienie dwóch UTF8Encoding obiektów, pierwszy przez wywołanie konstruktora bez UTF8Encoding() parametrów, który nie udostępnia modelu BOM, a drugi przez wywołanie UTF8Encoding(Boolean) konstruktora z argumentem encoderShouldEmitUTF8Identifier ustawionym na true. Następnie wywołuje GetPreamble metodę zapisu BOM do pliku przed zapisaniem ciągu zakodowanego w formacie UF8. 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-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.

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, który obsługuje protokół UTF-8, model BOM nie jest wyświetlany.

Uwagi

UTF8Encoding Obiekt może zapewnić preambułę, która jest tablicą bajtów, która może być poprzedzona sekwencją bajtów, które wynikają z procesu kodowania. Prefakcja sekwencji zakodowanych bajtów z znakiem kolejności bajtów (punkt kodu U+FEFF) pomaga dekoderowi określić kolejność bajtów i format przekształcenia lub UTF. Znak kolejności bajtów Unicode (BOM) jest serializowany jako 0xEF 0xBB 0xBF. Należy pamiętać, że standard Unicode nie wymaga ani nie zaleca użycia modelu BOM dla strumieni zakodowanych w formacie UTF-8.

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

• Po pobraniu obiektu zwróconego UTF8EncodingEncoding.UTF8 przez właściwość.

• UTF8Encoding Wywołując konstruktor z parametrem encoderShouldEmitUTF8Identifier i ustawiając jego wartość na true.

Wszystkie inne UTF8Encoding obiekty są skonfigurowane tak, aby zwracały pustą tablicę, a nie prawidłową BOM.

Model BOM zapewnia niemal pewną identyfikację kodowania plików, które w przeciwnym razie straciły odwołanie do ich kodowania, takie jak nieotagowane lub nieprawidłowo oznakowane dane internetowe lub losowe pliki tekstowe przechowywane, gdy firma nie miała międzynarodowych problemów. Często problemy użytkowników mogą być unikane, jeśli dane są konsekwentnie 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 używania 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, aby niepotrzebny znak mógł znajdować się w środku danych. Pomimo kilku wad, jednak stosowanie modelu BOM jest zdecydowanie zalecane.

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

Ważne

Aby upewnić się, że zakodowane bajty są prawidłowo dekodowane, gdy są zapisywane jako plik lub jako strumień, można prefiks początku strumienia zakodowanych bajtów z preambułą. Należy pamiętać, że GetBytes metoda nie poprzedza obiektu BOM sekwencją zakodowanych bajtów; dostarczanie obiektu BOM na początku odpowiedniego strumienia bajtów jest obowiązkiem dewelopera.