UnicodeEncoding.GetPreamble Metode

Referensi

Definisi

Ruang nama:: System.Text

Rakitan:: System.Text.Encoding.Extensions.dll

Rakitan:: mscorlib.dll

Rakitan:: netstandard.dll

Sumber:: UnicodeEncoding.cs

Sumber:: UnicodeEncoding.cs

Sumber:: UnicodeEncoding.cs

Penting

Beberapa informasi terkait produk prarilis yang dapat diubah secara signifikan sebelum dirilis. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Mengembalikan tanda urutan byte Unicode yang dikodekan dalam format UTF-16, jika konstruktor untuk instans ini meminta tanda urutan byte.

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 objek dikonfigurasi UnicodeEncoding untuk menyediakannya. Jika tidak, metode ini mengembalikan array byte panjang nol.

Contoh

Contoh berikut menunjukkan cara menggunakan GetPreamble metode untuk mengambil tanda urutan byte Unicode dalam urutan byte big endian atau little endian untuk instans UnicodeEncoding.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^byteOrderMark;
   byteOrderMark = Encoding::Unicode->GetPreamble();
   Console::WriteLine( "Default (little-endian) Unicode Preamble:" );
   IEnumerator^ myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine( "\n" );
   UnicodeEncoding^ bigEndianUnicode = gcnew UnicodeEncoding( true,true );
   byteOrderMark = bigEndianUnicode->GetPreamble();
   Console::WriteLine( "Big-endian Unicode Preamble:" );
   myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }
}

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

Contoh berikut membuat instans dua UnicodeEncoding objek, yang pertama tidak menyediakan BOM, dan yang kedua. Kemudian memanggil GetPreamble metode untuk menulis BOM ke file sebelum menulis string yang dikodekan Unicode. 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-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.

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

Keterangan

Objek UnicodeEncoding dapat memberikan preamble, yang merupakan array byte yang dapat diawali dengan urutan byte yang dihasilkan dari proses pengodean. Mengawali 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 berikut (dalam heksadesimal):

Urutan byte big endian: FE FF
Urutan byte little endian: FF FE

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

Dengan mengambil objek yang UnicodeEncoding dikembalikan oleh Encoding.Unicode properti atau Encoding.BigEndianUnicode .
Dengan memanggil konstruktor tanpa UnicodeEncoding() parameter untuk membuat instans UnicodeEncoding objek.
Dengan memasok true sebagai nilai byteOrderMark argumen ke UnicodeEncoding(Boolean, Boolean) konstruktor atau UnicodeEncoding(Boolean, Boolean, Boolean) .

Kami menyarankan agar Anda menggunakan BOM, karena memberikan identifikasi yang hampir pasti dari pengodean untuk file yang sebaliknya telah kehilangan referensi ke pengodeannya, seperti data web yang tidak ditandai atau tidak ditandai dengan benar atau file teks acak yang disimpan ketika bisnis tidak memiliki masalah 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. Meskipun ada beberapa kelemahan, namun, penggunaan BoM sangat disarankan.

Penting

Untuk memastikan bahwa byte yang dikodekan didekode dengan benar, Anda harus mengawali awal aliran byte yang dikodekan dengan awalan byte yang dikodekan dengan awalan. Perhatikan bahwa GetBytes metode ini tidak mendahului BOM ke urutan byte yang dikodekan; memasok BOM di awal aliran byte yang sesuai adalah tanggung jawab pengembang.

Berlaku untuk