UnicodeEncoding.GetPreamble メソッド

public:
 override cli::array <System::Byte> ^ GetPreamble();

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

戻り値

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

例

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

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 つの UnicodeEncoding オブジェクトをインスタンス化します。1 つ目は BOM を提供せず、2 つ目は BOM を提供しません。 次に、 メソッドを GetPreamble 呼び出して、Unicode エンコード文字列を書き込む前に BOM をファイルに書き込みます。 この例のコンソール出力に示すように、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.

コンソール ウィンドウで コマンドを使用してファイルを fc 比較することも、16 進表示モードを含むテキスト エディターでファイルを検査することもできます。 UTF-16 エンコードをサポートするエディターでファイルを開くと、BOM は表示されないことに注意してください。

注釈

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

• ビッグ エンディアン バイトオーダー: FE FF

• リトル エンディアン バイトオーダー: FF FE

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

• または Encoding.BigEndianUnicode プロパティによって返されるオブジェクトをEncoding.Unicode取得UnicodeEncodingします。

• パラメーターなしの UnicodeEncoding() コンストラクターを呼び出して オブジェクトを UnicodeEncoding インスタンス化します。

• または UnicodeEncoding(Boolean, Boolean, Boolean) コンストラクターに引数のbyteOrderMark値として をUnicodeEncoding(Boolean, Boolean)指定trueします。

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

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

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

適用対象