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 、2つのオブジェクトをインスタンス化UTF8Encoding()します。最初のオブジェクトは、BOM を提供しないパラメーターなしUTF8Encoding(Boolean)のコンストラクターをencoderShouldEmitUTF8Identifier呼び出し、2番目のオブジェクトの引数をに設定してコンストラクターを呼び出します true。次に、メソッドを GetPreamble 呼び出して BOM をファイルに書き込み、UF8 でエンコードされた文字列を書き込みます。この例のコンソール出力に示すように、2 番目のエンコーダーからのバイトを保存するファイルのバイト数は、最初のエンコーダーより 3 バイト多くなります。

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 進表示モードを含むテキストエディターでファイルを検査することもできます。 UTF-8 をサポートするエディターでファイルを開くと、BOM は表示されないことに注意してください。

注釈

オブジェクトは UTF8Encoding プリアンブルを提供できます。これは、エンコードプロセスの結果として生成されるバイトシーケンスの前に付けることができるバイト配列です。エンコードされたバイトのシーケンスをバイト順マーク (コードポイント U +FEFF) で前置すると、デコーダーがバイト順と変換形式 (UTF) を決定するのに役立ちます。 Unicode バイトオーダーマーク (BOM) は、0xEF 0xBB 0xBFとしてシリアル化されます。 Unicode 標準では、UTF-8 でエンコードされたストリームに BOM を使用する必要も推奨もされていない点に注意してください。

メソッドが有効な BOM を UTF8Encoding 返すオブジェクト GetPreamble は、次の方法でインスタンス化できます。

プロパティによって返されるオブジェクトを UTF8Encoding 取得します Encoding.UTF8 。
パラメーターを使用してコンストラクターを UTF8Encoding 呼び出し、 encoderShouldEmitUTF8Identifier その値をに設定します true。

他 UTF8Encoding のすべてのオブジェクトは、有効な BOM ではなく空の配列を返すように構成されます。

BOM は、タグ付けされていない、または不適切にタグ付けされた Web データや、企業が国際的な懸念を抱いていないときに保存されたランダムなテキストファイルなど、エンコードへの参照を失ったファイルのエンコードのほぼ特定の識別を提供します。多くの場合、データが一貫して適切にタグ付けされている場合は、ユーザーの問題が回避される可能性があります。

エンコードの種類を提供する標準の場合、BOM はやや冗長です。ただし、このメソッドを使用して、サーバーが正しいエンコードヘッダーを送信できるようにすることができます。または、エンコードが失われた場合にフォールバックとして使用することもできます。

BOM の使用にはいくつかの欠点があります。たとえば、BOM を使用するデータベースフィールドを制限する方法を理解することは困難です。ファイルの連結も問題になることがあります。たとえば、不要な文字がデータの途中で終了するような方法でファイルをマージする場合などです。ただし、いくつかの欠点がありますが、BOM を使用することを強くお勧めします。

バイト順とバイト順マークの詳細については、unicodeホームページの unicode 標準を参照してください。

重要

エンコードされたバイトがファイルまたはストリームとして保存されるときに正しくデコードされるようにするには、エンコードされたバイトのストリームの先頭にプリアンブルを付けます。メソッドは GetBytes 、エンコードされたバイトシーケンスの先頭に BOM を付加しないことに注意してください。適切なバイトストリームの先頭に BOM を指定するのは開発者の責任です。

適用対象

次の方法で共有

UTF8Encoding.GetPreamble メソッド

定義

戻り値

例

注釈

適用対象

その他のリソース