programming/netfx/tips/unicode_encoding_bom/index.wiki.txt

-[[programming/netfx/tips/encoding_fallback]]

-[[programming/netfx/environment/1_process#LocaleAndCulture_DefaultEncoding]]

|~引数&var{encoding};に指定する値|~BOM出力|h

|(指定なし)|なし|

|``Encoding.UTF8``|あり|

|``Encoding.Default`` (.NET Core/.NET 5以降)|なし|

|``UTF8Encoding(&var{encoderShouldEmitUTF8Identifier};: ''true'')``|あり|

|``UTF8Encoding(&var{encoderShouldEmitUTF8Identifier};: ''false'')``|なし|

$samplecode(lang=c#-9.0,copyright-year=2020,StreamWriterコンストラクタの引数encodingとBOM出力のありなし)

  // StreamWriterが出力したバイト列を16進形式で表示

  Console.WriteLine(BitConverter.ToString(stream.ToArray()));

Imports System

Imports System.IO

Imports System.Text

Class Sample

  Shared Sub Main()

    ' 引数encodingに指定する値を変えてStreamWriterを作成する

    For Each createStreamWriter In New Func(Of Stream, StreamWriter)() {

      Function(s) New StreamWriter(s), ' encodingの指定なし

      Function(s) New StreamWriter(s, encoding := Encoding.UTF8),

      Function(s) New StreamWriter(s, encoding := Encoding.Default), ' ⚠.NET FrameworkのEncoding.DefaultはUTF-8ではなくShift_JIS等のANSIコードページとなる

      Function(s) New StreamWriter(s, encoding := New UTF8Encoding(encoderShouldEmitUTF8Identifier := True)),

      Function(s) New StreamWriter(s, encoding := New UTF8Encoding(encoderShouldEmitUTF8Identifier := False))

    }

      Using stream As New MemoryStream()

        Const text As String = "日本語"

        Using writer = createStreamWriter(stream)

          writer.Write(text)

        End Using

        ' StreamWriterが出力したバイト列を16進形式で表示

        Console.WriteLine(BitConverter.ToString(stream.ToArray()))

      End Using

    Next

  End Sub

End Class

}}

$samplecode

#prompt(emphasize=brace){{

E6-97-A5-E6-9C-AC-E8-AA-9E

$samplecode$

UTF-8以外の場合も同様の動作となる。　BOMあり/なしで分類すると次のようになる。　Encodingクラスのプロパティとして用意されているものは、&msdn(netfx,member,System.Text.Encoding.Default){Encoding.Default};を除くと''すべてBOMあり''となる。

|*StreamWriterコンストラクタの引数&var{encoding};とBOM出力のありなし

|~エンコーディング|>|~引数&var{encoding};に指定する値|h

|~|~BOMあり|~BOMなし|h

|~UTF-8|``Encoding.UTF8``&br;``UTF8Encoding(&var{encoderShouldEmitUTF8Identifier};: ''true'')``|``Encoding.Default`` (.NET Core/.NET 5以降)&br;``UTF8Encoding(&var{encoderShouldEmitUTF8Identifier};: ''false'')``|

|~UTF-16&br;Little Endian|``Encoding.Unicode``&br;``UnicodeEncoding(&var{bigEndian};: false, &var{byteOrderMark};: ''true'')``|``UnicodeEncoding(&var{bigEndian};: false, &var{byteOrderMark};: ''false'')``|

|~UTF-16&br;Big Endian|``Encoding.BigEndianUnicode``&br;``UnicodeEncoding(&var{bigEndian};: true, &var{byteOrderMark};: ''true'')``|``UnicodeEncoding(&var{bigEndian};: true, &var{byteOrderMark};: ''false'')``|

|~UTF-32&br;Little Endian|``Encoding.UTF32``&br;``UTF32Encoding(&var{bigEndian};: false, &var{byteOrderMark};: ''true'')``|``UTF32Encoding(&var{bigEndian};: false, &var{byteOrderMark};: ''false'')``|

|~UTF-32&br;Big Endian|``UTF32Encoding(&var{bigEndian};: true, &var{byteOrderMark};: ''true'')``|``UTF32Encoding(&var{bigEndian};: true, &var{byteOrderMark};: ''false'')``|

&msdn(netfx,type,System.Text.Encoding){Encodingクラス};および派生クラスでは、そのエンコーディングでのBOMを表すバイト列(以降'''preamble'''と表記)を取得することができる。　preambleは、&msdn(netfx,member,System.Text.Encoding.Preamble){Preambleプロパティ};(.NET Standard 2.1/.NET Core 2.1以降)あるいは&msdn(netfx,member,System.Text.Encoding.GetPreamble){GetPreambleメソッド};(.NET Framework 1.1以降)から取得できる。　これらはどちらも同じ内容のバイト列を返す。

この動作をより具体的に述べると次のようになる。　StreamWriterは、ストリームへの最初の書き込みを行う前にまずEncodingからpreambleを取得し、その内容をストリームへ書き込む。　このとき、''preambleに何らかのバイト列が設定されていれば、それがBOMとして書き込まれる''ことになる。　preambleとして空の配列が設定されている場合は、当然ストリームには何も書き込まれないため、結果としてBOMは書き込まれないことになる。

$blockquote(cite=https://msdn.microsoft.com/ja-jp/vstudio/aa569610.aspx#Question2,cite-title=.NET Framework Developer Center:System.System.IO に関する FAQ - テキスト ファイルのエンコード方式を調べる方法はありますか。)

StreamWriter クラスも Encoding::GetPreamble() メソッドを呼び出し、テキスト ファイルの先頭にこのバイト列を書き込みます。これは優れた機能です。ユーザーがテキスト ファイルのエンコード方式をはっきり特定できるからです。ただし、弊社の多くの開発者は C 言語の知識を持っているため、テキスト ファイルの先頭に UTF-8 の Unicode BOM があると混乱してしまいました。また、Unicode に対応していないエディタ (vi、以前のバージョンの Emacs など) では扱いにくいこともあります。このため、StreamWriter クラスで既定で使用される UTF8Encoding では、GetPreamble メソッドから空のバイト列が返されます。UTF-8 ファイルに Unicode BOM を書き込むには、コード内で Encoding.UTF8 を明示的に指定します。

UTF8Encodingと同様に、UTF-16を扱う&msdn(netfx,type,System.Text.UnicodeEncoding){UnicodeEncodingクラス};・UTF-32を扱う&msdn(netfx,type,System.Text.UTF32Encoding){UTF32Encodingクラス};の場合も、コンストラクタの引数&var{byteOrderMark};でpreambleとして設定するバイト列をBOMとするか空のバイト列とするかを指定することができる。　BOMが定義されないShift_JISなどのEncodingでは、preambleは空のバイト列となる。

StreamWriter以外のクラスやメソッドを使った書き込みの場合も、Encodingのpreambleを書き込む動作になっていれば、それによってBOM出力のありなしが決まる。　([[#System.IO.File.WriteAllText]]、[[#System.Xml]])

一方、BinaryWriterはEncodingを指定できるものの、preambleは無視される(書き込まれない)ため、常にBOMなしで出力される。　([[#System.IO.BinaryWriter]])

なお、&msdn(netfx,member,System.Text.Encoding.GetBytes){Encoding.GetBytesメソッド};などの文字列からバイト列等に変換するメソッドでは、preambleを含まない結果を返す。　(常にBOMなしとなる)

**EncodingがBOMあり/なしかどうか知る方法

あるEncodingがBOMを出力するかどうかは、Preambleプロパティ・GetPreambleメソッドが返すpreambleの内容・長さによって判断できる。　そのため、これを調べることによって、EncodingやStreamWriterがBOMを出力するかどうか事前に知ることができる。

$samplecode(lang=c#,copyright-year=2020,EncodingがBOMを出力するかどうか調べる)

      Encoding.UTF8,            // UTF-8 BOM

      Encoding.Default,         // UTF-8 non-BOM

      new UTF8Encoding(true),   // UTF-8 BOM

      new UTF8Encoding(false),  // UTF-8 non-BOM

      Encoding.Unicode,                   // UTF-16 Little Endian BOM

      new UnicodeEncoding(false, false),  // UTF-16 Little Endian non-BOM

      shift_jis,                // Shift_JIS

    };

  static readonly Encoding shift_jis =

#if NETFRAMEWORK

    Encoding.GetEncoding("shift_jis");

#else

    // `dotnet add sample.csproj package System.Text.Encoding.CodePages`

    CodePagesEncodingProvider.Instance.GetEncoding("shift_jis");

#endif

#code{{

Option Infer On

Imports System

Imports System.IO

Imports System.Text

Class Sample

  Shared Sub Main()

    Dim encodings = New Encoding() {

      Encoding.UTF8,            ' UTF-8 BOM

      Encoding.Default,         ' UTF-8 non-BOM

      New UTF8Encoding(True),   ' UTF-8 BOM

      New UTF8Encoding(False),  ' UTF-8 non-BOM

      Encoding.Unicode,                   ' UTF-16 Little Endian BOM

      New UnicodeEncoding(False, False),  ' UTF-16 Little Endian non-BOM

      shift_jis                 ' Shift_JIS

    }

      Console.WriteLine(

        "{0,12} {1,3} <{2}>",

        encoding.WebName, ' encodingのweb nameを表示

        If(preamble.Length = 0, String.Empty, "BOM"), ' preambleの長さからBOMのありなしを判定

        BitConverter.ToString(preamble) ' preambleの内容を表示

      )

    Next

  End Sub

#If NETFRAMEWORK Then

    Shared ReadOnly shift_jis As Encoding = Encoding.GetEncoding("shift_jis")

#Else

    ' `dotnet add sample.vbproj package System.Text.Encoding.CodePages`

    Shared ReadOnly shift_jis As Encoding = CodePagesEncodingProvider.Instance.GetEncoding("shift_jis")

#End If

End Class

}}

$samplecode

#prompt{{

       utf-8 BOM <EF-BB-BF>

       utf-8     <>

       utf-8 BOM <EF-BB-BF>

       utf-8     <>

      utf-16 BOM <FF-FE>

      utf-16     <>

   shift_jis     <>

$samplecode$

&msdn(netfx,type,System.IO.StreamReader){StreamReader};では、コンストラクタの引数&var{detectEncodingFromByteOrderMarks};に``true``を指定すると、ストリーム先頭のBOMから文字コードの自動判別を行うようになる。

$samplecode(lang=c#,copyright-year=2020,StreamReader.CurrentEncodingプロパティからストリームのpreambleの取得を試行する(すべてBOMありとなる))

      new UTF8Encoding(encoderShouldEmitUTF8Identifier: true),

      new UTF8Encoding(encoderShouldEmitUTF8Identifier: false),

      new UnicodeEncoding(bigEndian: true, byteOrderMark: true),

      new UnicodeEncoding(bigEndian: true, byteOrderMark: false),

      new UnicodeEncoding(bigEndian: false, byteOrderMark: true),

      new UnicodeEncoding(bigEndian: false, byteOrderMark: false),

      new UTF32Encoding(bigEndian: true, byteOrderMark: true),

      new UTF32Encoding(bigEndian: true, byteOrderMark: false),

      new UTF32Encoding(bigEndian: false, byteOrderMark: true),

      new UTF32Encoding(bigEndian: false, byteOrderMark: false),

      shift_jis,

    };

    const string text = "日本語";

    foreach (var encoding in encodings) {

      // 各種Encoding+BOMあり/なしでMemoryStreamに書き込む

      Console.Write($"{encoding.WebName,12} {(encoding.Preamble.Length == 0 ? string.Empty : "BOM"),3} => ");

        reader.Peek(); // 自動判別されたEncodingを参照するには、まずPeek/Readを行う必要がある

        // 自動判別されたEncodingを参照する

        var e = reader.CurrentEncoding;

        Console.WriteLine($"{e.WebName,12} {(e.Preamble.Length == 0 ? string.Empty : "BOM"),3}");

  static readonly Encoding shift_jis =

#if NETFRAMEWORK

    Encoding.GetEncoding("shift_jis");

#else

    // `dotnet add sample.csproj package System.Text.Encoding.CodePages`

    CodePagesEncodingProvider.Instance.GetEncoding("shift_jis");

#endif

}

}}

$samplecode(lang=vb)

#code{{

Option Infer On

Imports System

Imports System.IO

Imports System.Text

Class Sample

  Shared Sub Main()

    Dim encodings = New Encoding() {

      New UTF8Encoding(encoderShouldEmitUTF8Identifier := True),

      New UTF8Encoding(encoderShouldEmitUTF8Identifier := False),

      New UnicodeEncoding(bigEndian := True, byteOrderMark := True),

      New UnicodeEncoding(bigEndian := True, byteOrderMark := False),

      New UnicodeEncoding(bigEndian := False, byteOrderMark := True),

      New UnicodeEncoding(bigEndian := False, byteOrderMark := False),

      New UTF32Encoding(bigEndian := True, byteOrderMark := True),

      New UTF32Encoding(bigEndian := True, byteOrderMark := False),

      New UTF32Encoding(bigEndian := False, byteOrderMark := True),

      New UTF32Encoding(bigEndian := False, byteOrderMark := False),

      shift_jis

    }

    Const text As String = "日本語"

    For Each encoding In encodings

      ' 各種Encoding+BOMあり/なしでMemoryStreamに書き込む

      Console.Write($"{encoding.WebName,12} {If(encoding.Preamble.Length = 0, String.Empty, "BOM"),3} => ")

      Using stream As New MemoryStream()

        Using writer As New StreamWriter(stream, encoding, leaveOpen := True)

          writer.Write(text)

        End Using

        stream.Position = 0L

        ' BOMによるEncodingの自動判別を有効にしてMemoryStreamから読み込む

        Using reader As New StreamReader(stream, detectEncodingFromByteOrderMarks := True)

          reader.Peek() ' 自動判別されたEncodingを参照するには、まずPeek/Readを行う必要がある

          ' 自動判別されたEncodingを参照する

          Dim e = reader.CurrentEncoding

          Console.WriteLine($"{e.WebName,12} {If(e.Preamble.Length = 0, String.Empty, "BOM"),3}")

        End Using

      End Using

    Next

  End Sub

#If NETFRAMEWORK Then

    Shared ReadOnly shift_jis As Encoding = Encoding.GetEncoding("shift_jis")

#Else

    ' `dotnet add sample.vbproj package System.Text.Encoding.CodePages`

    Shared ReadOnly shift_jis As Encoding = CodePagesEncodingProvider.Instance.GetEncoding("shift_jis")

#End If

End Class

}}

$samplecode

#prompt{{

       utf-8 BOM =>        utf-8 BOM

       utf-8     =>        utf-8 BOM

    utf-16BE BOM =>     utf-16BE BOM

    utf-16BE     =>        utf-8 BOM

      utf-16 BOM =>       utf-16 BOM

      utf-16     =>        utf-8 BOM

    utf-32BE BOM =>     utf-32BE BOM

    utf-32BE     =>        utf-8 BOM

      utf-32 BOM =>       utf-32 BOM

      utf-32     =>        utf-8 BOM

   shift_jis     =>        utf-8 BOM

}}

$samplecode$

$remarks

StreamクラスでEncodingの自動判別と''BOMを維持した''読み込みを行う例については[[#BomTransparentStream]]を参照。

$remarks$

*各クラスにおけるBOM出力の動作と制御

以下は書き込みを行うクラスにおけるBOM出力の動作と、BOMありなしを指定する方法について。

**System.IO名前空間 [#System.IO]

***StreamWriter (追記モード) [#System.IO.StreamWriter]

コンストラクタの引数&var{append};に``true``を指定して追記モードで書き込みを行う場合、ファイルが存在しない場合(新規作成となる場合)は''Encodingのpreambleに応じてBOMが出力される''。　一方、追記となる場合はpreambleによらず''BOMの追記は行われない''。

上書きモード(&var{append}; = ``false``)でのStreamWriterの動作は[[前述のとおり>#summary]]。

$samplecode(lang=c#-9.0,copyright-year=2020,追記モードのStreamWriterに指定するEncodingとBOM出力の有無の違い)

#code{{

using System;

using System.IO;

using System.Text;

const string path = "out.txt";

const string text = "日本語";

foreach (var createStreamWriter in new Func<StreamWriter>[] {

  // 引数encodingに指定する値を変えて、追記モード(append: true)のStreamWriterを作成する

  () => new(path, append: true), // encodingの指定なし

  () => new(path, append: true, encoding: Encoding.UTF8),

  () => new(path, append: true, encoding: Encoding.Default), // ⚠.NET FrameworkのEncoding.DefaultはUTF-8ではなくShift_JIS等のANSIコードページとなる

  () => new(path, append: true, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: true)),

  () => new(path, append: true, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)),

}) {

  if (File.Exists(path))

    File.Delete(path); // ファイルを削除しておく

  // 新規に作成したファイルへの書き込みとなる場合

  using (var writer = createStreamWriter()) {

    writer.Write(text);

  }

  // StreamWriterが出力したバイト列を16進形式で表示

  Console.Write("{0,-40} => ", BitConverter.ToString(File.ReadAllBytes(path)));

  // 既存のファイルへの追記となる場合

  using (var writer = createStreamWriter()) {

    writer.Write(text);

  }

  // StreamWriterが出力したバイト列を16進形式で表示

  Console.WriteLine(BitConverter.ToString(File.ReadAllBytes(path)));

E6-97-A5-E6-9C-AC-E8-AA-9E               => E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

{{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E      => {{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

E6-97-A5-E6-9C-AC-E8-AA-9E               => E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

{{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E      => {{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

E6-97-A5-E6-9C-AC-E8-AA-9E               => E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

}}

$relevantdocs

-[[programming/netfx/stream/2_streamreader_streamwriter#StreamWriter]]

-[[programming/netfx/stream/2_streamreader_streamwriter#StreamWriter_Append]]

$relevantdocs$

***File.WriteAllText [#System.IO.File.WriteAllText]

&msdn(netfx,member,System.IO.File.WriteAllText){File.WriteAllText};などのFileクラスの書き込みメソッドでは、[[StreamWriterと同様の動作>#summary]]でBOMが出力される。

$samplecode(lang=c#-9.0,copyright-year=2020,File.WriteAllTextメソッドに指定するEncodingとBOM出力の有無の違い)

#code{{

using System;

using System.IO;

using System.Text;

const string contents = "日本語";

const string path = "out.txt";

foreach (var writeAllText in new Action[] {

  // 引数encodingに指定する値を変えてFile.WriteAllTextを呼び出す

  () => File.WriteAllText(path, contents), // encodingの指定なし

  () => File.WriteAllText(path, contents, encoding: Encoding.UTF8),

  () => File.WriteAllText(path, contents, encoding: Encoding.Default), // ⚠.NET FrameworkのEncoding.DefaultはUTF-8ではなくShift_JIS等のANSIコードページとなる

  () => File.WriteAllText(path, contents, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: true)),

  () => File.WriteAllText(path, contents, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)),

}) {

  writeAllText();

  // File.WriteAllTextが出力したバイト列を16進形式で表示

  Console.WriteLine(BitConverter.ToString(File.ReadAllBytes(path)));

}

}}

$samplecode

#prompt(emphasize=brace){{

E6-97-A5-E6-9C-AC-E8-AA-9E

{{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E

E6-97-A5-E6-9C-AC-E8-AA-9E

$samplecode$

-[[programming/netfx/filesystem/2_filereadwrite#System.IO.File_Write]]

$relevantdocs$

&msdn(netfx,member,System.IO.File.AppendAllText){File.AppendAllText};など、Fileクラスの追記による書き込みを行うメソッドでは、[[追記モードのStreamWriterと同様の動作>#System.IO.StreamWriter]]となる。

using System.IO;

  () => File.AppendAllText(path, contents, encoding: Encoding.UTF8),

  () => File.AppendAllText(path, contents, encoding: Encoding.Default), // ⚠.NET FrameworkのEncoding.DefaultはUTF-8ではなくShift_JIS等のANSIコードページとなる

  () => File.AppendAllText(path, contents, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: true)),

  () => File.AppendAllText(path, contents, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)),

}) {

  if (File.Exists(path))

    File.Delete(path); // ファイルを削除しておく

  appendAllText(); // 既存のファイルへの追記となる場合

  // File.AppendAllTextが出力したバイト列を16進形式で表示

  Console.WriteLine(BitConverter.ToString(File.ReadAllBytes(path)));

#prompt(emphasize=brace){{

E6-97-A5-E6-9C-AC-E8-AA-9E               => E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

{{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E      => {{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

E6-97-A5-E6-9C-AC-E8-AA-9E               => E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

{{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E      => {{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

E6-97-A5-E6-9C-AC-E8-AA-9E               => E6-97-A5-E6-9C-AC-E8-AA-9E-E6-97-A5-E6-9C-AC-E8-AA-9E

$samplecode$

$relevantdocs

-[[programming/netfx/filesystem/2_filereadwrite#System.IO.File_Append]]

$relevantdocs$

&msdn(netfx,type,System.IO.BinaryWriter){BinaryWriterクラス};では、&msdn(netfx,member,System.IO.BinaryWriter.Write){Writeメソッド};で文字列を書き込むことができる。　また、このときに使用するEncodingをコンストラクタの引数&var{encoding};で指定することができる。

ただし、BinaryWriterはpreambleの内容に関わらず''BOMを出力しない''。　そのためBinaryWriterでBOMを出力させたい場合は、preambleを取得して明示的に書き込む必要がある。

なお、BinaryWriter.Writeメソッドでは文字列のバイト長を前置した上で書き込む動作となっている点に注意。

Console.WriteLine("{0} ('{1}')", BitConverter.ToString(Encoding.UTF8.GetBytes(text)), text);

Console.WriteLine();

  s => new(s), // encodingの指定なし

  s => new(s, encoding: Encoding.UTF8),

  s => new(s, encoding: Encoding.Default), // ⚠.NET FrameworkのEncoding.DefaultはUTF-8ではなくShift_JIS等のANSIコードページとなる

  s => new(s, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: true)),

  s => new(s, encoding: new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)),

}) {

  using var stream = new MemoryStream();

  }

09-E6-97-A5-E6-9C-AC-E8-AA-9E

09-E6-97-A5-E6-9C-AC-E8-AA-9E

09-E6-97-A5-E6-9C-AC-E8-AA-9E

}}

$samplecode$

**System.Xml名前空間 [#System.Xml]

***XmlWriter [#System.Xml.XmlWriter]

&msdn(netfx,member,System.Xml.dll,System.Xml.XmlWriter.Create){XmlWriter.Createメソッド};で作成したXmlWriterを使用する場合、BOMが出力されるかどうかは&msdn(netfx,member,System.Xml.dll,System.Xml.XmlWriterSettings.Encoding){XmlWriterSettings.Encodingプロパティ};に設定するEncoding次第となる。　デフォルトでは&msdn(netfx,member,System.Text.Encoding.UTF8){Encoding.UTF8};が設定されているため、''特に指定しなかった場合はBOMが出力される''。

したがって、BOMを出力したくない場合は、BOMを出力しないEncodingを明示的にXmlWriterSettings.Encodingに指定する必要がある。

$samplecode(lang=c#-9.0,copyright-year=2020,XmlWriterSettings.Encodingプロパティに指定するEncodingと、XmlWriterのBOM出力の有無の違い)

#code{{

using System;

using System.IO;

using System.Text;

using System.Xml;

const string path = "out.xml";

var doc = new XmlDocument();

doc.AppendChild(doc.CreateElement("doc"));

foreach (var createWriterSettings in new Func<XmlWriterSettings>[] {

  // Encodingプロパティに指定する値を変えてXmlWriterSettingsを作成する

  () => new(), // Encodingの指定なし (デフォルトではEncoding.UTF8が設定されている)

  () => new() { Encoding = Encoding.UTF8 },

  () => new() { Encoding = Encoding.Default }, // ⚠.NET FrameworkのEncoding.DefaultはUTF-8ではなくShift_JIS等のANSIコードページとなる

  () => new() { Encoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: true) },

  () => new() { Encoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false) },

}) {

  using (var writer = XmlWriter.Create(path, createWriterSettings())) {

    doc.Save(writer);

  // XmlWriterが出力した内容を文字列・16進形式で表示

  Console.WriteLine(File.ReadAllText(path));

  Console.WriteLine(BitConverter.ToString(File.ReadAllBytes(path)));

  Console.WriteLine();

-[[programming/netfx/xml/1_xmlwritersettings#XmlWriterSettings]]

-[[programming/netfx/xml/1_xmlwritersettings#XmlWriterSettings.Encoding]]

$relevantdocs$

***XmlDocument [#System.Xml.XmlDocument]

XmlWriterを使わず&msdn(netfx,member,System.Xml.ReaderWriter.dll,System.Xml.XmlDocument.Save){XmlDocument.Saveメソッド};でXML文書を出力する場合は次のようになる。

XML宣言(``XmlDeclaration``)のencoding属性に``"utf-8"``などを指定した場合は、''BOM付きのUTF-8''で出力される。　一方``null``や``string.Empty``を指定した場合は''BOMなしのUTF-8''で出力されるが、encoding属性は省略される。

したがって、BOMを出力せず、かつencoding属性付きのXML宣言を出力したい場合には[[XmlWriterを使う>#System.Xml.XmlWriter]]必要がある。

$samplecode(lang=c#-9.0,copyright-year=2020,XML宣言のencoding属性に指定する値と、XmlDocument.SaveメソッドのBOM出力の有無の違い)

  d => d.CreateXmlDeclaration(version: "1.0", encoding: "utf-8", standalone: null),

  d => d.CreateXmlDeclaration(version: "1.0", encoding: null, standalone: null),

  d => d.CreateXmlDeclaration(version: "1.0", encoding: string.Empty, standalone: null),

}) {

  var doc = new XmlDocument();

  doc.AppendChild(doc.CreateElement("doc"));

  Console.WriteLine();

}

}}

$samplecode

#prompt(emphasize=brace){{

<?xml version="1.0" encoding="utf-8"?>

<doc />

{{EF-BB-BF}}-3C-3F-78-6D-6C-20-76-65-72-73-69-6F-6E-3D-22-31-2E-30-22-20-65-6E-63-6F-64-69-6E-67-3D-22-75-74-66-2D-38-22-3F-3E-0A-3C-64-6F-63-20-2F-3E

<?xml version="1.0"?>

<doc />

3C-3F-78-6D-6C-20-76-65-72-73-69-6F-6E-3D-22-31-2E-30-22-3F-3E-0A-3C-64-6F-63-20-2F-3E

}}

$samplecode$

***XDocument (System.Xml.Linq) [#System.Xml.Linq.XDocument]

XmlWriterを使わず&msdn(netfx,member,System.Xml.XDocument.dll,System.Xml.Linq.XDocument.Save){XDocument.Saveメソッド};でXML文書を出力する場合は次のようになる。

XML宣言(``XDeclaration``)のencoding属性に``"utf-8"``/``null``/``string.Empty``のいずれを指定した場合でも''BOM付きのUTF-8''で出力される。　したがって、BOMを出力したくない場合には、BOMを出力しないEncodingを使用する[[XmlWriterを使う>#System.Xml.XmlWriter]]必要がある。

$samplecode(lang=c#-9.0,copyright-year=2020,XML宣言のencoding属性に指定する値と、XDocument.SaveメソッドのBOM出力の有無の違い)

#code{{

using System;

using System.IO;

using System.Xml.Linq;

const string path = "out.xml";

foreach (var createXDeclaration in new Func<XDeclaration>[] {

  // encoding属性に指定する値を変えてXML宣言(XDeclaration)を作成する

  () => new(version: "1.0", encoding: "utf-8", standalone: null),

  () => new(version: "1.0", encoding: null, standalone: null),

  () => new(version: "1.0", encoding: string.Empty, standalone: null),

}) {

  var doc = new XDocument(

    createXDeclaration(),

    new XElement("doc")

  );

  doc.Save(path);

  // XDocument.Saveが出力した内容を文字列・16進形式で表示

  Console.WriteLine(File.ReadAllText(path));

  Console.WriteLine(BitConverter.ToString(File.ReadAllBytes(path)));

  Console.WriteLine();

}}

$samplecode

#prompt(emphasize=brace){{

<?xml version="1.0" encoding="utf-8"?>

<doc />

{{EF-BB-BF}}-3C-3F-78-6D-6C-20-76-65-72-73-69-6F-6E-3D-22-31-2E-30-22-20-65-6E-63-6F-64-69-6E-67-3D-22-75-74-66-2D-38-22-3F-3E-0A-3C-64-6F-63-20-2F-3E

<?xml version="1.0" encoding="utf-8"?>

<doc />

{{EF-BB-BF}}-3C-3F-78-6D-6C-20-76-65-72-73-69-6F-6E-3D-22-31-2E-30-22-20-65-6E-63-6F-64-69-6E-67-3D-22-75-74-66-2D-38-22-3F-3E-0A-3C-64-6F-63-20-2F-3E

<?xml version="1.0" encoding="utf-8"?>

<doc />

{{EF-BB-BF}}-3C-3F-78-6D-6C-20-76-65-72-73-69-6F-6E-3D-22-31-2E-30-22-20-65-6E-63-6F-64-69-6E-67-3D-22-75-74-66-2D-38-22-3F-3E-0A-3C-64-6F-63-20-2F-3E

$relevantdocs

-[[programming/netfx/xml/0_generate_write#XDocument.Save]]

-[[programming/netfx/xml/0_generate_write#XDeclaration]]

$relevantdocs$

**JsonSerializer (System.Text.Json) [#System.Text.Json.JsonSerializer]

&urn2url(urn:ietf:rfc:8259,#8.1); (8.1. Character Encoding)にて、JSONフォーマットでは(閉じたシステム内で使用する場合を除き)UTF-8を使用しなければならない(''MUST'')、ネットワーク転送される場合はBOMを付加してはならない(''MUST NOT'')とされている。

&msdn(netfx,type,System.Text.Json.dll,System.Text.Json.JsonSerializer){JsonSerializerクラス};はこれに沿った動作となっていて、常に''BOMなしのUTF-8''で出力される。　オプション等でEncodingを明示的に指定することはできない。

$samplecode(lang=c#-9.0,copyright-year=2020,JsonSerializerではBOMは出力されない)

#code{{

using System;

using System.IO;

using System.Text;

using System.Text.Json;

using System.Threading.Tasks;

var stream = new MemoryStream();

await JsonSerializer.SerializeAsync<string[]>(stream, new[] {"json"});

// JsonSerializerが出力した内容を文字列・16進形式で表示

Console.WriteLine(Encoding.UTF8.GetString(stream.ToArray()));

Console.WriteLine(BitConverter.ToString(stream.ToArray()));

}}

$samplecode

$samplecode$

#code{{

using System;

using System.IO;

using System.Text;

using System.Text.Json;

using System.Threading.Tasks;

const string path = "out.json";

using (var stream = File.OpenWrite(path)) {

  stream.SetLength(0L); // 既存の内容を上書きする(truncate)

  stream.Write(Encoding.UTF8.Preamble); // UTF-8のBOMを書き込む

  await JsonSerializer.SerializeAsync<string[]>(stream, new[] {"json"}); // JsonSerializerでStreamに書き込む

}

// JsonSerializerが出力した内容を文字列・16進形式で表示

Console.WriteLine(File.ReadAllText(path));

Console.WriteLine(BitConverter.ToString(File.ReadAllBytes(path)));

}}

$samplecode

#prompt(emphasize=brace){{

["json"]

{{EF-BB-BF}}-5B-22-6A-73-6F-6E-22-5D

}}

$samplecode$

*BOMによる自動判別とBOMの透過的読み込みを行うStream [#BomTransparentStream]

以下は、BOMからEncodingを自動判別し、BOMの''透過的な''読み込みを行うStreamラッパー``BomTransparentStream``を実装した例。

与えられたStreamからBOMを読み込み、Encodingの自動判別を行うと同時に、コンストラクタでの指定に応じてBOMを維持/破棄した上で読み込むことができる。　StreamReaderとは異なり、自動判別できなかった場合は''BOMなしのUTF-8''として判別される。

簡易な実装かつ限定的なユースケースのみでの動作確認しかしていないため、使用方法によっては実装を修正する必要が出てくると思われる。　その他の制限・未実装事項等についてはコード中のコメントを参照。

$samplecode(lang=c#-9.0,copyright-year=2020,BomTransparentStream)

using System.Linq;

  private Stream baseStream;

  public Stream BaseStream => baseStream ?? throw new ObjectDisposedException(GetType().FullName);

  private readonly bool discardBom;

  public BomTransparentStream(string path, bool discardBom = true)

    : this(File.OpenRead(path), discardBom) {}

  public BomTransparentStream(Stream baseStream, bool discardBom = true)

  {

    this.baseStream = baseStream ?? throw new ArgumentNullException(nameof(baseStream));

    this.discardBom = discardBom;

  }

  public override void Close()

    baseStream = null;

  }

  public override bool CanRead => BaseStream.CanRead;

  public override bool CanWrite => false; // 書き込みはサポートしない

  public override bool CanTimeout => BaseStream.CanTimeout;

  public override long Position {

    get => BaseStream.Position; // 本来ならBOM分を差し引いた値を返すべき

    set => throw new NotSupportedException();

  }

  public override long Length => BaseStream.Length; // 本来ならBOM分を差し引いた値を返すべき

  public override void SetLength(long @value) => throw new NotSupportedException(); // 長さの設定はサポートしない

  public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();

  public override void Flush() => throw new NotSupportedException();

  public override void Write(byte[] buffer, int offset, int count) => throw new NotSupportedException();

  /// <summary>BOMから自動判別されたEncoding</summary>

  /// <remarks>未判別の状態、また判別できなかった場合はEncoding.Defaultを返す</remarks>

  public Encoding DetectedEncoding { get; private set; } = Encoding.Default;

  /// <summary>まだBOMを読み込んでいない場合は、BOMの読み込みとEncodingの自動判別を行う</summary>

  public void ReadPreamble()

  {

    if (isPreamble)

      Read(Array.Empty<byte>(), 0, 0);

  }

  {

    // 引数チェックは省略

      BaseStream.Read(_preamble.Span); // 戻り値のチェックは省略、この実装ではStreamの内容が4バイト未満の場合は想定していない

      // Encodingの判別を行い、判別できた場合はBOMを除去した結果を取得する

      var (detectedEncoding, remainder) = DetectEncodingFromPreamble(_preamble);

      DetectedEncoding = detectedEncoding;

    for (;;) {

      // preambleとして保持されている内容が空なら、BaseStreamから読み込み、そのまま返す

      if (preamble.IsEmpty)

        return readCount + BaseStream.Read(buf.Span);

      // preambleの内容をbufferにコピーする

      if (preamble.Length <= buf.Length) {

        var len = preamble.Length;

      else {

        var len = buf.Length;

        preamble.Slice(0, len).CopyTo(buf);

        preamble = preamble.Slice(len);

        return len;

      }

    }

  }

  private static (Encoding, ReadOnlyMemory<byte>) DetectEncodingFromPreamble(ReadOnlyMemory<byte> preamble)

  {

    // 与えられたpreambleからEncodingを判別する

    var e = encodings.FirstOrDefault(e => preamble.Span.StartsWith(e.Preamble)) ?? Encoding.Default;

    // 判別したEncodingと、BOMを差し引いた分を返す

    return (e, preamble.Slice(e.Preamble.Length));

  }

  // BOMの長い順にソート済みのEncoding

  private static readonly Encoding[] encodings = new[] {

    Encoding.UTF32,

    new UTF32Encoding(bigEndian: true, byteOrderMark: true),

    Encoding.UTF8,

    Encoding.Unicode,

    Encoding.BigEndianUnicode,

  };

}

$samplecode$

      new UnicodeEncoding(bigEndian: false, byteOrderMark: false),

      new UTF32Encoding(bigEndian: true, byteOrderMark: true),

      new UTF32Encoding(bigEndian: true, byteOrderMark: false),

      new UTF32Encoding(bigEndian: false, byteOrderMark: true),

      new UTF32Encoding(bigEndian: false, byteOrderMark: false),

      shift_jis,

    const string contents = "日本語";

    const string path = "out.txt";

      File.WriteAllText(path, contents, encoding);

        // 出力したファイルをBomTransparentStreamで読み込む

        using (var bomTransparentStream = new BomTransparentStream(path, discardBom: true /*BOMは除去する*/)) {

          bomTransparentStream.CopyTo(buffer); // 内容をbufferにコピー

        }

          fileStream.SetLength(0L); // truncate

      }

      // 出力したファイル内容を16進形式で表示

      Console.WriteLine(BitConverter.ToString(File.ReadAllBytes(path)));

  static readonly Encoding shift_jis =

#if NETFRAMEWORK

    Encoding.GetEncoding("shift_jis");

#else

    // `dotnet add sample.csproj package System.Text.Encoding.CodePages`

    CodePagesEncodingProvider.Instance.GetEncoding("shift_jis");

#endif

$samplecode

#prompt(emphasize=brace){{

{{EF-BB-BF}}-E6-97-A5-E6-9C-AC-E8-AA-9E                          => E6-97-A5-E6-9C-AC-E8-AA-9E

E6-97-A5-E6-9C-AC-E8-AA-9E                                   => E6-97-A5-E6-9C-AC-E8-AA-9E

{{FE-FF}}-65-E5-67-2C-8A-9E                                      => 65-E5-67-2C-8A-9E

65-E5-67-2C-8A-9E                                            => 65-E5-67-2C-8A-9E

{{FF-FE}}-E5-65-2C-67-9E-8A                                      => E5-65-2C-67-9E-8A

E5-65-2C-67-9E-8A                                            => E5-65-2C-67-9E-8A

{{00-00-FE-FF}}-00-00-65-E5-00-00-67-2C-00-00-8A-9E              => 00-00-65-E5-00-00-67-2C-00-00-8A-9E

00-00-65-E5-00-00-67-2C-00-00-8A-9E                          => 00-00-65-E5-00-00-67-2C-00-00-8A-9E

{{FF-FE-00-00}}-E5-65-00-00-2C-67-00-00-9E-8A-00-00              => E5-65-00-00-2C-67-00-00-9E-8A-00-00

E5-65-00-00-2C-67-00-00-9E-8A-00-00                          => E5-65-00-00-2C-67-00-00-9E-8A-00-00

93-FA-96-7B-8C-EA                                            => 93-FA-96-7B-8C-EA

}}

      new UnicodeEncoding(bigEndian: false, byteOrderMark: false),

      new UTF32Encoding(bigEndian: true, byteOrderMark: true),

      new UTF32Encoding(bigEndian: true, byteOrderMark: false),

      new UTF32Encoding(bigEndian: false, byteOrderMark: true),

      new UTF32Encoding(bigEndian: false, byteOrderMark: false),

      shift_jis,

    const string contents = "日本語";

    const string path = "out.txt";