UTF8Encoding.GetPreamble Metode

Definisi

Ruang nama:

System.Text

Rakitan:

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

Sumber:

UTF8Encoding.cs

Mengembalikan tanda urutan byte Unicode yang dikodekan dalam format UTF-8, jika UTF8Encoding objek pengodean dikonfigurasi untuk menyediakannya.

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Mengembalikan

Byte[]

Array byte yang berisi tanda urutan byte Unicode, jika UTF8Encoding objek pengodean dikonfigurasi untuk menyediakannya. Jika tidak, metode ini mengembalikan array byte panjang nol.

Contoh

Contoh berikut menggunakan GetPreamble metode untuk mengembalikan tanda urutan byte Unicode yang dikodekan dalam format UTF-8. Perhatikan bahwa konstruktor tanpa parameter untuk UTF8Encoding tidak menyediakan preamble.

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

Contoh berikut membuat instans dua UTF8Encoding objek, yang pertama dengan memanggil konstruktor tanpa UTF8Encoding() parameter, yang tidak menyediakan BOM, dan yang kedua dengan memanggil UTF8Encoding(Boolean) konstruktor dengan argumennya encoderShouldEmitUTF8Identifier diatur ke true. Kemudian memanggil GetPreamble metode untuk menulis BOM ke file sebelum menulis string yang dikodekan UF8. Seperti yang ditunjukkan oleh output konsol dari contoh, file yang menyimpan byte dari encoder kedua memiliki tiga byte lebih banyak daripada yang pertama.

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.

Anda juga dapat membandingkan file dengan menggunakan fc perintah di jendela konsol, atau Anda dapat memeriksa file di editor teks yang menyertakan mode Tampilan Hex. Perhatikan bahwa ketika file dibuka di editor yang mendukung UTF-8, BOM tidak ditampilkan.

Keterangan

Objek UTF8Encoding dapat memberikan awalan, yang merupakan array byte yang dapat diawali dengan urutan byte yang dihasilkan dari proses pengodean. Prefacing urutan byte yang dikodekan dengan tanda urutan byte (titik kode U+FEFF) membantu dekoder menentukan urutan byte dan format transformasi, atau UTF. Tanda urutan byte Unicode (BOM) diserialisasikan sebagai 0xEF 0xBB 0xBF. Perhatikan bahwa Standar Unicode tidak memerlukan atau merekomendasikan penggunaan BOM untuk aliran yang dikodekan UTF-8.

Anda dapat membuat UTF8Encoding instans objek yang metodenya GetPreamble mengembalikan BOM yang valid dengan cara berikut:

• Dengan mengambil objek yang UTF8Encoding dikembalikan oleh Encoding.UTF8 properti .

• Dengan memanggil UTF8Encoding konstruktor dengan encoderShouldEmitUTF8Identifier parameter dan mengatur nilainya diatur ke true.

Semua objek lain UTF8Encoding dikonfigurasi untuk mengembalikan array kosong daripada BOM yang valid.

BOM memberikan identifikasi yang hampir pasti tentang pengodean untuk file yang jika tidak kehilangan referensi ke pengodeannya, seperti data web yang tidak diberi tag atau tidak benar atau file teks acak yang disimpan ketika bisnis tidak memiliki kekhawatiran internasional. Seringkali masalah pengguna mungkin dihindari jika data ditandai dengan konsisten dan benar.

Untuk standar yang menyediakan jenis pengodean, BOM agak berlebihan. Namun, ini dapat digunakan untuk membantu server mengirim header pengodean yang benar. Atau, ini dapat digunakan sebagai fallback jika pengodean hilang.

Ada beberapa kelemahan menggunakan BOM. Misalnya, mengetahui cara membatasi bidang database yang menggunakan BOM bisa sulit. Penggabungan file juga dapat menjadi masalah, misalnya, ketika file digabungkan sewaktu-waktu sehingga karakter yang tidak perlu dapat berakhir di tengah data. Terlepas dari beberapa kelemahan, namun, penggunaan BOM sangat disarankan.

Untuk informasi selengkapnya tentang urutan byte dan tanda urutan byte, lihat Standar Unicode di halaman beranda unicode .

Penting

Untuk memastikan bahwa byte yang dikodekan didekodekan dengan benar saat disimpan sebagai file atau sebagai aliran, Anda dapat mengawali awalan aliran byte yang dikodekan dengan dapat dimulalui. Perhatikan bahwa GetBytes metode ini tidak menambahkan BOM ke urutan byte yang dikodekan; memasok BOM di awal aliran byte yang sesuai adalah tanggung jawab pengembang.