System.Xml.XmlWriter クラス

[アーティクル]
01/06/2024

XmlWriter クラスはストリーム、ファイル、テキストリーダー、または文字列に XML データを書き込みます。このクラスは、W3C 勧告拡張マークアップ言語 (XML) 1.0 (第 4 版) および W3C 勧告 XML 1.0 の名前空間 (第 3 版) をサポートしています。

XmlWriter クラスのメンバーでは、次の機能を使用できます。

文字が有効な XML 文字かどうか、要素名と属性名が有効な XML 名かどうかを確認します。
XML ドキュメントが整形式かどうかを確認します。
バイナリバイトを Base64 または BinHex としてエンコードし、エンコード後のテキストを書き出します。
値の変換を手動で実行する必要がないように、文字列の代わりに共通言語ランタイム型を使用して値を渡します。
複数のドキュメントを 1 つの出力ストリームに書き込みます。
有効な名前、修飾された名前、および名前トークンを書き込みます。

XML ライターを作成する

XmlWriter インスタンスを作成するには、XmlWriter.Create メソッドを使用します。 XML ライターで有効にする機能のセットを指定するには、Create メソッドに XmlWriterSettings を渡します。それ以外の場合は、既定の設定が使用されます。詳細については、Create のリファレンスページを参照してください。

出力形式の指定

XmlWriterSettings クラスには、XmlWriter 出力の書式設定方法を制御するいくつかのプロパティが含まれています。

プロパティ	説明
Encoding	使用するテキストエンコーディングを指定します。既定値は、`Encoding.UTF8` です。
Indent	要素をインデントするかどうかを示します。既定値は `false` (インデントなし) です。
IndentChars	インデントに使用する文字列を指定します。既定値は 2 つのスペースです。
NewLineChars	改行に使用する文字列を指定します。既定値は、Unix 以外のプラットフォームの場合は `\r\n` (復帰、改行)、Unix プラットフォームの場合は `\n` (改行) です。
NewLineHandling	改行文字の処理方法を指定します。
NewLineOnAttributes	新しい行に属性を書き込むかどうかを示します。このプロパティを使用するときは、Indent を `true` に設定する必要があります。既定値は、`false` です。
OmitXmlDeclaration	XML 宣言を書き込むかどうかを示します。既定値は、`false` です。

Indent および IndentChars プロパティによって、意味のない空白の書式設定方法が制御されます。たとえば、要素ノードをインデントするには、次の操作を行います。

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.IndentChars = "\t";
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.IndentChars = vbTab
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

NewLineOnAttributes を使用して、1 レベル深くインデントされた新しい行に属性を書き込みます。

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.NewLineOnAttributes = true;
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.NewLineOnAttributes = True
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

データの一致

XML ライターは、XmlWriterSettings クラスの 2 つのプロパティを使用して、データの準拠をチェックします。

CheckCharacters プロパティは、W3C で定義されているように、文字をチェックし、有効範囲外の文字がある場合は XmlException 例外をスローするように XML ライターに指示します。

ConformanceLevel プロパティは、書き込まれるストリームが、W3C で定義されている整形式の XML 1.0 ドキュメントまたはドキュメントフラグメントの規則に準拠していることをチェックするように XML ライターを構成します。 3 つの一致レベルを次の表に示します。既定値は、Document です。詳細については、XmlWriterSettings.ConformanceLevel プロパティと System.Xml.ConformanceLevel 列挙型を参照してください。

Level	説明
Document	XML 出力は、整形式の XML 1.0 ドキュメントの規則に準拠しており、準拠している任意のプロセッサで処理できます。
Fragment	XML 出力は、整形式の XML 1.0 ドキュメントフラグメントの規則に準拠します。
Auto	XML ライターは、受信データに基づいて、適用する一致チェックのレベル (ドキュメントまたはフラグメント) を決定します。

要素の書き込み

次の XmlWriter メソッドを使用して、要素ノードを書き込むことができます。使用例については、一覧表示したメソッドを参照してください。

使用	受信先
WriteElementString	文字列値も含め、要素ノード全体を書き込みます。
WriteStartElement	要素値を書き込むには、複数のメソッド呼び出しを使用します。たとえば、WriteValue を呼び出して、型指定された値を書き込んだり、WriteCharEntity を呼び出して文字エンティティを書き込んだり、WriteAttributeString を呼び出して 1 つの属性を書き込んだり、子要素を書き込んだりすることができます。これは、WriteElementString メソッドのより高度なバージョンです。要素を閉じるには、WriteEndElement または WriteFullEndElement メソッドを呼び出します。
WriteNode	XmlReader オブジェクトまたは XPathNavigator オブジェクトの現在の位置で見つかる 1 つの要素ノードをコピーします。呼び出されると、ソースオブジェクトからすべてを XmlWriter インスタンスにコピーします。

属性の書き込み

次の XmlWriter メソッドを使用して、要素ノードに属性を書き込むことができます。次のセクションで説明するように、これらのメソッドは、要素に名前空間宣言を作成するためにも使用できます。

使用	受信先
WriteAttributeString	文字列値も含め、属性ノード全体を書き込みます。
WriteStartAttribute	複数のメソッド呼び出しを使用して属性値を書き込みます。たとえば、WriteValue を呼び出して型指定された値を書くことができます。これは、WriteElementString メソッドのより高度なバージョンです。要素を閉じるには、WriteEndAttribute メソッドを呼び出します。
WriteAttributes	XmlReader オブジェクトの現在の位置で見つかるすべての属性をコピーします。書き込まれる属性は、リーダーが現在位置するノードの種類によって異なります。 - 属性ノードの場合、現在の属性を書き込み、次に終了タグが来るまで残りの属性を書き込みます。 - 要素ノードの場合、要素に含まれるすべての属性が書き込まれます。 - XML 宣言ノードの場合、宣言内のすべての属性が書き込まれます。 - その他すべての種類の場合、メソッドは例外をスローします。

名前空間を処理する

名前空間は、XML ドキュメント内の要素名と属性名を修飾するために使用されます。名前空間プレフィックスは、要素と属性を名前空間に関連付けます。名前空間は URI 参照に関連付けられます。名前空間は、XML ドキュメントの中の要素名と属性名を一意にします。

XmlWriter は、現在の名前空間のスコープ内で定義されているすべての名前空間に対応する名前空間スタックを保持します。要素および属性の書き込み時には、次の方法で名前空間を使用できます。

WriteAttributeString メソッドを使用して名前空間を手動で宣言します。これは、名前空間宣言の個数を最適化する方法がわかっているときに役立つ場合があります。例については、「WriteAttributeString(String, String, String, String) メソッド」を参照してください。

現在の名前空間宣言を新しい名前空間でオーバーライドする。次のコードでは、WriteAttributeString メソッドは "x" プレフィックスの名前空間 URI を "123" から "abc" に変更します。

writer.WriteStartElement("x", "root", "123");
writer.WriteStartElement("item");
writer.WriteAttributeString("xmlns", "x", null, "abc");
writer.WriteEndElement();
writer.WriteEndElement();

writer.WriteStartElement("x", "root", "123")
writer.WriteStartElement("item")
writer.WriteAttributeString("xmlns", "x", Nothing, "abc")
writer.WriteEndElement()
writer.WriteEndElement()

このコードは、次の XML 文字列を生成します。

<x:root xmlns:x="123">
  <item xmlns:x="abc" />
</x:root>

属性または要素の書き込み時に名前空間プレフィックスを指定する。要素と属性の書き込みに使用されるメソッドの多くで、これを行うことができます。たとえば、WriteStartElement(String, String, String) メソッドは開始タグを書き込み、指定した名前空間とプレフィックスに関連付けます。

型指定されたデータを書き込む

WriteValue メソッドは、共通言語ランタイム (CLR) オブジェクトを受け入れ、XML スキーマ定義言語 (XSD) データ型変換規則に従って入力値をその文字列形式に変換し、WriteString メソッドを使用して書き出します。これは、XmlConvert クラス内のメソッドを使用して、型指定されたデータを書き出す前に文字列値に変換するよりも簡単です。

テキストが書き込まれると、型指定された値は、そのスキーマ型に関する XmlConvert 規則を使用してテキストにシリアル化されます。

CLR 型に対応する既定の XSD データ型の場合は、WriteValue メソッドを参照してください。

XML データストアに書き込むために、XmlWriter を使用することもできます。たとえば、XPathNavigator クラスは XmlWriter オブジェクトを作成して、XmlDocument オブジェクト用のノードを作成できます。データストアに使用可能なスキーマ情報がある場合、許可されていない型に変換しようとすると、WriteValue メソッドは例外をスローします。データストアに使用可能なスキーマ情報がない場合、WriteValue メソッドは、すべての値を xsd:anySimpleType 型として扱います。

XML ライターを閉じる

XML を出力するために XmlWriter メソッドを使用する場合、要素と属性は Close メソッドを呼び出すまで書き込まれません。たとえば、XmlDocument オブジェクトの設定に XmlWriter を使用している場合、XmlWriter インスタンスを閉じるまで、ターゲットドキュメントに書き込まれた要素と属性を表示することはできません。

非同期プログラミング

ほとんどの XmlWriter メソッドには、メソッド名の末尾に "Async" を持つ非同期の対応するメソッドがあります。たとえば、WriteAttributeString の非同期に相当するものは WriteAttributeStringAsync です。

WriteValue メソッドの場合は、戻り値を文字列に変換し、代わりに WriteStringAsync メソッドを使用します。

セキュリティに関する考慮事項

XmlWriter クラスを使用する際には、次の点に注意してください。

XmlWriter で例外がスローされると、アプリにバブルアップしたくないパス情報が開示される可能性があります。アプリは例外をキャッチし、それらを適切に処理する必要があります。
XmlWriter は、WriteDocType または WriteRaw メソッドに渡されるデータを検証しません。これらのメソッドに任意のデータを渡さないでください。