UTF8Encoding.GetPreamble 方法

定義

如果設定 UTF8Encoding 編碼物件提供編碼方式,則會傳回以 UTF-8 格式編碼的 Unicode 位元組順序標記。Returns a Unicode byte order mark encoded in UTF-8 format, if the UTF8Encoding encoding object is configured to supply one.

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 位元組順序標記的位元組陣列。A byte array containing the Unicode byte order mark, if the UTF8Encoding encoding object is configured to supply one. 否則,這個方法會傳回長度為零的位元組陣列。Otherwise, this method returns a zero-length byte array.

範例

下列範例會使用 GetPreamble 方法,傳回以 UTF-8 格式編碼的 Unicode 位元組順序標記。The following example uses the GetPreamble method to return the Unicode byte order mark encoded in UTF-8 format. 請注意,UTF8Encoding 的無參數函數不會提供前序。Notice that the parameterless constructor for UTF8Encoding does not provide a preamble.

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 物件,第一個方法是呼叫無參數的 UTF8Encoding() 函式,這不提供 BOM,而第二個是呼叫 UTF8Encoding(Boolean) 的函式,並將其 encoderShouldEmitUTF8Identifier 引數設定為 trueThe following example instantiates two UTF8Encoding objects, the first by calling the parameterless UTF8Encoding() constructor, which does not provide a BOM, and the second by calling the UTF8Encoding(Boolean) constructor with its encoderShouldEmitUTF8Identifier argument set to true. 然後,它會先呼叫 GetPreamble 方法,將 BOM 寫入檔案,然後再寫入 UF8 編碼的字串。It then calls the GetPreamble method to write the BOM to a file before writing a UF8-encoded string. 如範例的主控台輸出所示,儲存第二個編碼器之位元組的檔案,比第一個會有三個位元組。As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first.

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] 命令來比較檔案,也可以在包含十六進位視圖模式的文字編輯器中檢查檔案。You can also compare the files by using the fc command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. 請注意,在支援 UTF-8 的編輯器中開啟檔案時,不會顯示 BOM。Note that when the file is opened in an editor that supports UTF-8, the BOM is not displayed.

備註

UTF8Encoding 物件可以提供後序,這是一個位元組陣列,可以在編碼程式所產生的位元組序列前面加上。The UTF8Encoding object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes that result from the encoding process. 在編碼的位元組序列前面加上位順序標記(代碼點 U + FEFF),可協助此解碼器判斷位元組順序和轉換格式,或 UTF。Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format, or UTF. Unicode 位元組順序標記(BOM)會序列化為 0xEF 0xBB 0xBF。The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. 請注意,Unicode 標準不需要也不建議針對 UTF-8 編碼資料流程使用 BOM。Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams.

您可以利用下列方式,將其 GetPreamble 方法傳回有效 BOM 的 UTF8Encoding 物件具現化:You can instantiate a UTF8Encoding object whose GetPreamble method returns a valid BOM in the following ways:

  • 藉由抓取 Encoding.UTF8 屬性所傳回的 UTF8Encoding 物件。By retrieving the UTF8Encoding object returned by the Encoding.UTF8 property.

  • 藉由使用 encoderShouldEmitUTF8Identifier 參數呼叫 UTF8Encoding 的函式,並將其值設定為 trueBy calling a UTF8Encoding constructor with a encoderShouldEmitUTF8Identifier parameter and setting its value set to true.

所有其他 UTF8Encoding 物件都會設定為傳回空的陣列,而不是有效的 BOM。All other UTF8Encoding objects are configured to return an empty array rather than a valid BOM.

BOM 針對檔案的編碼方式提供幾乎特定的識別,否則會遺失其編碼的參考,例如未標記或標示錯誤的 web 資料,或在企業沒有國際疑慮時儲存的隨機文字檔。The BOM provide nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. 如果資料一致且正確地加上標籤,通常可以避免使用者的問題。Often user problems might be avoided if data is consistently and properly tagged.

針對提供編碼類型的標準,BOM 有點重複。For standards that provide an encoding type, a BOM is somewhat redundant. 不過,它可以用來協助伺服器傳送正確的編碼標頭。However, it can be used to help a server send the correct encoding header. 或者,也可以在編碼方式遺失時,做為回退使用。Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

使用 BOM 有一些缺點。There are some disadvantages to using a BOM. 例如,知道如何限制使用 BOM 的資料庫欄位可能會很棘手。For example, knowing how to limit the database fields that use a BOM can be difficult. 檔案的串連可能也是問題,例如,合併檔案時,不必要的字元可能會在資料中間結束。Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. 不過,儘管有幾個缺點,但強烈建議使用 BOM。In spite of the few disadvantages, however, the use of a BOM is highly recommended.

如需位元組順序和位元組順序標記的詳細資訊,請參閱unicode 首頁的 unicode 標準。For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

重要

為確保編碼的位元組會在儲存為檔案或資料流程時正確解碼,您可以在編碼的位元組資料流程開頭加上前置字元。To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. 請注意,GetBytes 方法不會在編碼的位元組序列前面加上 BOM;在適當的位元組資料流程開頭提供 BOM,是開發人員的責任。Note that the GetBytes method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility.

適用於