UTF8Encoding.GetPreamble 方法

參考

定義

命名空間:: System.Text

組件:: System.Text.Encoding.Extensions.dll

組件:: mscorlib.dll

組件:: netstandard.dll

來源:: UTF8Encoding.cs

來源:: UTF8Encoding.cs

來源:: UTF8Encoding.cs

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如果設定 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 引數設定為 true 。 UTF8Encoding() 然後它會呼叫 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 是開發人員的責任。

適用於

共用方式為

UTF8Encoding.GetPreamble 方法

定義

傳回

範例

備註

適用於

其他資源