UnicodeEncoding.GetPreamble メソッド

定義

このインスタンスのコンストラクターでバイト順マークを要求した場合は、UTF-16 形式でエンコードされた Unicode バイト順マークを返します。

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

戻り値

Byte[]

Unicode のバイト順マークが格納されたバイト配列を提供するように UnicodeEncoding オブジェクトが構成されている場合には、そうしたバイト配列。 それ以外の場合、このメソッドは長さがゼロのバイト配列を返します。

次の例では、 メソッドを使用して、 のインスタンスのビッグ エンディアンまたはリトル エンディアンのバイト順で Unicode バイト順マークを取得する方法 GetPreamble を示します UnicodeEncoding

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^byteOrderMark;
   byteOrderMark = Encoding::Unicode->GetPreamble();
   Console::WriteLine( "Default (little-endian) Unicode Preamble:" );
   IEnumerator^ myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine( "\n" );
   UnicodeEncoding^ bigEndianUnicode = gcnew UnicodeEncoding( true,true );
   byteOrderMark = bigEndianUnicode->GetPreamble();
   Console::WriteLine( "Big-endian Unicode Preamble:" );
   myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }
}
using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        Byte[] byteOrderMark;
        
        byteOrderMark = Encoding.Unicode.GetPreamble();
        Console.WriteLine("Default (little-endian) Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine("\n");

        UnicodeEncoding bigEndianUnicode = new UnicodeEncoding(true, true);
        byteOrderMark = bigEndianUnicode.GetPreamble();
        Console.WriteLine("Big-endian Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
    }
}
Imports System.Text

Class UnicodeEncodingExample
    
    Public Shared Sub Main()
        Dim byteOrderMark() As Byte
        Dim b As Byte
        
        byteOrderMark = Encoding.Unicode.GetPreamble()
        Console.WriteLine("Default (little-endian) Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine(ControlChars.NewLine)
        
        Dim bigEndianUnicode As New UnicodeEncoding(True, True)
        byteOrderMark = bigEndianUnicode.GetPreamble()
        Console.WriteLine("Big-endian Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
    End Sub
End Class

次の例では、2 つの オブジェクトをインスタンス化します。1 つ目は BOM を提供しません。2 つ目のオブジェクトは UnicodeEncoding インスタンス化します。 次に、 メソッドを GetPreamble 呼び出して BOM をファイルに書き込み、その後、Unicode でエンコードされた文字列を書き込む必要があります。 例のコンソール出力に示すように、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-16 encoding.";

      // Write a file using a Unicode encoding object without a BOM.
      var enc = new UnicodeEncoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UnicodeEncoding(! BitConverter.IsLittleEndian, 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 116 bytes to .\NoPreamble.txt.
//
//       Preamble has 2 bytes
//       Wrote 118 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-16 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UnicodeEncoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UnicodeEncoding(Not BitConverter.IsLittleEndian, 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 116 bytes to .\NoPreamble.txt.
'
'       Preamble has 2 bytes
'       Wrote 118 bytes to .\Preamble.txt.

コンソール ウィンドウで コマンドを使用してファイルを比較したり、16 進ビュー モードを含むテキスト エディターでファイル fc を調べることもできます。 UTF-16 エンコードをサポートするエディターでファイルを開いた場合、BOM は表示されません。

注釈

オブジェクトはプリアンブルを提供できます。プリアンブルは、エンコード プロセスに起因するバイト シーケンスの前に付け可能なバイト UnicodeEncoding 配列です。 エンコードされたバイトのシーケンスの前にバイト順マーク (コード ポイント U+FEFF) を付けるのは、デコーダーがバイト順と変換形式または UTF を決定するのに役立ちます。 Unicode バイト順マーク (BOM) は、次のようにシリアル化されます (16 進数)。

  • ビッグ エンディアンのバイト順: FE FF

  • リトル エンディアンのバイト順: FF FE

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

BOM は、エンコードへの参照を失ったファイル (タグ付けされていない Web データや不適切にタグ付けされた Web データや、ビジネスに国際的な懸念がない場合に格納されたランダム テキスト ファイルなど) のエンコーディングをほぼ確実に識別できるので、使用をお勧めします。 多くの場合、データが一貫して適切にタグ付けされている場合は、ユーザーの問題が回避される可能性があります。

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

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

重要

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

適用対象