UTF8Encoding.GetPreamble UTF8Encoding.GetPreamble UTF8Encoding.GetPreamble UTF8Encoding.GetPreamble Method

定義

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 、2つのオブジェクトをインスタンス化UTF8Encoding()します。最初のオブジェクトは、BOM を提供しないパラメーターなしUTF8Encoding(Boolean)のコンストラクターをencoderShouldEmitUTF8Identifier呼び出し、2番目のオブジェクトの引数をに設定してコンストラクターを呼び出します 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を呼び出して、UF8 エンコードされた文字列を書き込む前に BOM をファイルに書き込みます。It then calls the GetPreamble method to write the BOM to a file before writing a UF8-encoded string. この例のコンソール出力に示されているように、2番目のエンコーダーからバイトを保存するファイルには、最初のエンコーダーよりも3バイトが含まれています。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コマンドを使用してファイルを比較したり、16進数の表示モードを含むテキストエディターでファイルを検査したりすることもできます。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 0Xef 0Xef としてシリアル化されます。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.

次の方法でUTF8Encoding有効なGetPreamble BOM を返すメソッドを持つオブジェクトをインスタンス化できます。You can instantiate a UTF8Encoding object whose GetPreamble method returns a valid BOM in the following ways:

  • プロパティによって返されるオブジェクトを取得するUTF8EncodingEncoding.UTF8By retrieving the UTF8Encoding object returned by the Encoding.UTF8 property.

  • パラメーターをtrue UTF8Encoding encoderShouldEmitUTF8Identifier使用してコンストラクターを呼び出し、その値をに設定します。By 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.

適用対象