誰かがWordテンプレートと締め切りを渡してきます。どんなデータが必要ですか? 通常の答えは、テンプレートを開き、スクロールし、推測し、実行し、エラーを読み、再度実行することです。ローカルで GroupDocs.Assembly.Mcp を実行すると(dnx GroupDocs.Assembly.Mcp --yes)、Claude Desktop、Cursor、または Copilot がテンプレートに直接問い合わせます:get_template_fields はすべてのタグ、使用されるデータ名、そして埋めるための JSON スケルトンをエンジンを実行せずに返し、実行が失敗した場合はエラーが何を変更すべきかを示します。

order-lines.docx に必要なデータは何ですか? 生成できない場合は理由とテンプレートの修正方法を教えてください。

設定とトラブルシューティングを含むステップバイステップのバージョンはドキュメントにあります: How to find out what a template needs and why it failed.

埋め込む前に検査する理由

試行錯誤はスキーマを学ぶための高コストな方法です。文書の可視テキストからフィールド名を推測するエージェントは、テンプレートが customer.Name と記述しているときに CustomerName と推測してしまい、間違った推測はすべて往復と混乱するエラーを生みます。テンプレートは散文ではなく、データ契約を持つプログラムであり、その契約は読み取ることができます。

それが get_template_fields のすべての機能です。<<…>> タグを解析し、名前を導き出し、スケルトンを構築します:

-> get_template_fields {"template":{"filePath":"order-lines.docx"}}
<- { "tagCount": 3,
     "dataSourceNames": [ "lines" ],
     "fields": [ "lines[].Title", "lines[].Quantity" ],
     "dataSkeleton": { "lines": [ { "Title": "", "Quantity": "" } ] },
     "notes": [ "fields and dataSkeleton are inferred from the tags,
       not from the engine; values computed by Select/GroupBy
       projections are not followed." ] }

このメモは手法について正直に述べています: これは静的検査です。Select 投影内で生成されたフィールドは追跡されません。通常の契約書、レター、請求書テンプレートでは、スケルトンがまさに埋めるべき内容です。

スケルトンは会話の流れも変えます。たとえば「注文書の生成を試みたが失敗した」という代わりに、エージェントは「このテンプレートは各行にタイトルと数量を持つ行リストが必要です。メールで3件見つけました、こちらです」と言い、そして初めて生成します。検査はコストがかからず、データも不要で何も触れないため、エージェントが未経験のテンプレートに対して最初に行うべき呼び出しであり、誰かがテンプレートを編集した後でも再度行うべき呼び出しです。

3つの失敗、3つの解決策

template problem          what the server says          the fix
------------------------  ----------------------------  -------------------
{{name}} placeholders     "2 '{{...}}' placeholder(s).  write <<[name]>>
                          ... does not process that
                          syntax"                     write <<[name]>>
<<foreach>> never closed  "Unexpected end of template.  add <</foreach>>
                          A block tag is not closed"   add <</foreach>>
data lacks a field        "The template reads 'Email',  add it, or
                          which the data does not have" allowMissingMembers

間違った構文。 実際に流通している多くのテンプレートは他のエンジン向けに {{name}} を使用して書かれています。GroupDocs.Assembly はそれらをテキストとして残し、検査は誰も実行を無駄にする前にそれを指摘します:

-> get_template_fields {"template":{"filePath":"shipping-notice.docx"}}
<- { "tagCount": 0, "notes": [ "No <<…>> tags were found: ...",
     "The template contains 2 '{{…}}' placeholder(s). GroupDocs.Assembly
      does not process that syntax and leaves it as text; write
      <<[name]>> instead." ] }

閉じられていないブロック。 order-lines.docx は <<foreach>> を開いたまま閉じていません。検査はタグを喜んで列挙しますが、生成は失敗します:

-> assemble_document {"template":{"filePath":"order-lines.docx"},
     "dataJson":"{\"lines\":[{\"Title\":\"Cable\",\"Quantity\":2}]}"}
<- Document assembly failed for 'order-lines.docx': ...
   Unexpected end of template. A block tag is not closed: every
   <<foreach>> needs <</foreach>> and every <<if>> needs <</if>>.

フィールドが欠如している。 データにテンプレートが参照する項目がない場合、エラーはそのフィールド名を示し、名前は大文字小文字を区別することを伝え、allowMissingMembers: true スイッチを提案します。これにより欠損メンバーは何も出力されず、空リストが生成失敗に置き換わります。そのヒントはエンジンを超えて有用で、次のセクションが示すように、空リストでもテンプレートがメンバーに対して算術演算を行うと失敗します。

テンプレートに多数のミスがある場合

いくつかのテンプレートは複数のエラーを抱えており、1回ずつ失敗しながら修正するのは遅いです。inlineErrors: true を指定するとテンプレートが独自のエラーレポートに変わり、ドキュメントが生成され、各不正なタグの横にメッセージが書き込まれます。GroupDocs.Assembly のサンプルテンプレートでの例:

-> assemble_document {"template":{"filePath":"inline-error.docx"},
     "dataJson":"{\"name\":\"x\"}","inlineErrors":true}
<- Assembled 'inline-error.docx' ... The template has errors: each one
   is written into the output next to its tag, starting with 'Error!'

出力には << var [name] Error! An assignment operator is expected. >> がタグが配置されている箇所に含まれます。ファイルを開き、マークされたタグをすべて修正し、フラグなしで再実行してください。

検査で見えないもの

バイナリの Outlook テンプレートは例外です。.msg ファイルのタグは生成せずに読むことができず、サーバーは空リストではなく「フィールドがない」旨を返します:

-> get_template_fields {"template":{"filePath":"contracts-table.msg"}}
<- { "readable": false, "notes": [ "Tags cannot be read from a .msg
     template without generating it. Save the template as DOCX, XLSX,
     PPTX or EML to inspect it, or generate it with assemble_document
     and inlineErrors=true to see which fields fail." ] }

もう一つの罠は、データ側でリストが空の場合にメンバー型が存在しないことです。契約テンプレートは item.Quantity * item.UnitPrice を計算しますが、"items": [] と allowMissingMembers: true でも “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”* で失敗しました。テーブル周囲に <<if [items.Any()]>> を置いても効果はなく、エンジンは実行前にすべての式をチェックします。効果があったのは算術演算を行列から除外したことです。金額をデータ側で事前に用意しておけば(<<[item.Amount]>>)、同じ空リストと allowMissingMembers: true でドキュメントが生成され、<<if [items.Count() == 0]>>No services ordered.<</if>> が行を出力しました。そうでなければ、エージェントにリストが空でないことを確認させてから生成させ、空の契約がどのようになるべきかを尋ねてください。

正直な限界

  • 検査は静的です: Select と GroupBy の投影は追跡されず、.msg テンプレートは読み取れません。
  • テンプレートは信頼された入力とみなされます。画像やドキュメントタグは式が返すパスや URL をロードします。
  • 評価モード: すべての出力は “Evaluation Only. Created with GroupDocs.Assembly 26.7…” で始まります。
  • 日付: 2026-11-12T00:00:00 を渡し、テンプレート内で :"d MMMM yyyy" とフォーマットします。UTC+2 のマシンでは日付文字列だけが1日ずれてしまい、"12.11.2026" が 11 月 12 日ではなく 12 月 11 日として解釈されました。

FAQ

Wordテンプレートに必要なフィールドはどうやって確認しますか?
エージェントに get_template_fields を呼び出させます。タグ、データ名、JSON スケルトンがローカルで取得でき、何も生成せずに確認できます。

テンプレートが値ではなく {{name}} を出力するのはなぜですか?
GroupDocs.Assembly のタグは <<[name]>> です。サーバーの検査は {{…}} プレースホルダーをフラグし、代わりに何を書けばよいかを示します。

Markdownをテンプレートにできますか?
はい。product-readme.md に含まれる <<[product]>> と <<[description]>> タグは Word ファイルと同様に検査され、直接 DOCX に生成されました。

さらに詳しく