共用方式為


UTF8Encoding.GetPreamble 方法

定義

如果設定 UTF8Encoding 編碼物件提供編碼方式,則會傳回以 UTF-8 格式編碼的 Unicode 位元組順序標記。

public:
 override cli::array <System::Byte> ^ GetPreamble();
public override byte[] GetPreamble ();
override this.GetPreamble : unit -> byte[]
Public Overrides Function GetPreamble () As Byte()

傳回

Byte[]

如果設定 UTF8Encoding 編碼物件提供編碼方式,則為包含 Unicode 位元組順序標記的位元組陣列。 否則,這個方法會傳回長度為零的位元組陣列。

範例

下列範例會 GetPreamble 使用 方法來傳回以 UTF-8 格式編碼的 Unicode 位元組順序標記。 請注意,的 UTF8Encoding 無參數建構函式不提供前置詞。

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

下列範例會藉由呼叫無參數建構函式來具現化兩 UTF8Encoding 個物件,第一個物件不會提供 BOM,而第二個物件是呼叫 UTF8Encoding(Boolean) 建構函式,其 encoderShouldEmitUTF8Identifier 引數設定為 trueUTF8Encoding() 然後它會呼叫 GetPreamble 方法,以將 BOM 寫入檔案,再撰寫 UF8 編碼的字串。 如範例的主控台輸出所示,儲存第二個編碼器位元組的檔案比第一個編碼器還多三個位元組。

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.

您也可以在主控台視窗中使用 fc 命令來比較檔案,或者您可以在包含十六進位檢視模式的文字編輯器中檢查檔案。 請注意,當檔案在支援 UTF-8 的編輯器中開啟時,不會顯示 BOM。

備註

UTF8Encoding物件可以提供前置詞,這是位元組陣列,可前置詞至編碼程式所產生的位元組序列。 將一連串編碼的位元組加上位元組順序標記, (個字碼點 U+FEFF) 可協助解碼器判斷位元組順序和轉換格式,或 UTF。 Unicode 位元組順序標記 (BOM) 序列化為0xEF 0xBB 0xBF。 請注意,Unicode 標準不需要也不建議針對 UTF-8 編碼資料流程使用 BOM。

您可以透過下列方式具現化 UTF8Encoding 方法傳回有效 BOM 的物件 GetPreamble

  • 藉由擷 UTF8Encoding 取 屬性所 Encoding.UTF8 傳回的物件。

  • 藉由呼叫 UTF8Encoding 具有 參數的 encoderShouldEmitUTF8Identifier 建構函式,並將其值設定為 true

所有其他 UTF8Encoding 物件都會設定為傳回空陣列,而不是有效的 BOM。

BOM 為檔案提供幾乎特定編碼的識別,否則會遺失其編碼的參考,例如未標記或未正確標記的 Web 資料,或當企業沒有國際考慮時儲存的隨機文字檔。 如果資料一致且已正確標記,通常可能會避免使用者問題。

對於提供編碼類型的標準,BOM 有點備援。 不過,它可以用來協助伺服器傳送正確的編碼標頭。 或者,當編碼遺失時,它可以用來做為後援。

使用 BOM 有一些缺點。 例如,瞭解如何限制使用 BOM 的資料庫欄位可能很困難。 檔案串連也可能是問題,例如,當檔案合併時,可能會讓不必要的字元最終出現在資料中間。 不過,雖然有幾個缺點,但強烈建議使用 BOM。

如需位元組順序和位元組順序標記的詳細資訊,請參閱 Unicode 首頁上的 Unicode標準。

重要

為了確保編碼的位元組在儲存為檔案或資料流程時正確解碼,您可以將編碼位元組的開頭加上前置詞。 請注意,方法 GetBytes 不會在編碼位元組序列前面加上 BOM;在適當的位元組資料流程開頭提供 BOM 是開發人員的責任。

適用於