GitHub Copilotを使用してIronWordを利用する方法
.NETサービスは月次口座明細をWordファイルとして生成でき、それぞれにスタイル付きタイトル、二行の概要行、データから構築された表が含まれます。 このガイドでは、サービスはそのデータを提供するジョブと共にVisual Studioソリューション内にあり、それを変更するアシスタントは同じソリューション内で動作しなければなりません。
GitHub CopilotはVisual StudioまたはVS Codeでのチャットモードまたはエージェントモードからそのソリューションで作業できます。また、Copilot CLIを使用したターミナルから、そしてそのクラウドエージェントが割り当てられた問題のプルリクエストを開くGitHubからも作業が可能です。 IronWordは、マージされたセルやシェーディングされた行を持つスタイル付きのテキストとテーブルをコード内で構築します。 IronWordのルールはリポジトリ内の指示ファイルに保管され、それぞれのサーフェイスがそれを読み取ります。
テーブルガイドとテキストスタイルガイドは、このガイドが依存するAPIの二つの部分をカバーしています。
クイックスタートソリューションのルートからCopilot CLIを開始し、以下のプロンプトを貼り付けます。 Visual StudioのCopilot Chatは#を含むファイルを参照し、CLIは@を使用します。
Fill in @src/Statements/Documents/StatementBuilder.cs with a public static Build method.
Its signature is Build(Account account, IReadOnlyList<Transaction> transactions, string outputPath).
Add Account and Transaction as small records in the same folder.
Write the DOCX with IronWord, from the IronWord NuGet package.
The types are in the IronWord and IronWord.Models namespaces.
Lay out the statement exactly as @docs/statement-layout.md describes. Three parts need care:
- the bold heading row
- the merged closing-balance cell
- the alternate row shading
Save the file to outputPath, then compile the solution and clear every build error.
Tell me which files you added or changed.
プロンプトはスタイリングメンバーを指定しません。 以下のパス固有の指示ファイルは、使用するメンバーを指定しています。
ソリューションのProgram.csは環境からIRONWORD_LICENSE_KEYを読み込み、それをIronWord.License.LicenseKeyに割り当てるので、Copilotを開始する前にその変数を設定してください。 ライセンスキーガイドは、同じ割り当てとキーを保持できる設定ファイルを示しています。
最小限のワークフロー(5ステップ)
- NuGetからC# Wordライブラリをダウンロード
- IronWordのルールを.github/copilot-instructions.mdと1つのパス固有の指示ファイルに書き込みます。
- ランでのテキストにスタイルを適用し、マージされた閉じ行を別の行として追加します。
- 保存されたすべてのステートメントを再開し、テーブルのセルをソースデータと比較します。
- 次の変更をクラウドエージェントの問題として割り当て、そのIronWord APIリファレンスに対してプルリクエストを確認します。
Copilot用のIronWord規約をどのように設定しますか?
リポジトリ全体のルールは.github/copilot-instructions.mdにあります。 Copilot CLI、Copilotコードレビュー、クラウドエージェント、JetBrains IDEs、Visual Studio、VS CodeのCopilot ChatはすべてGitHubのサポートマトリックスに従ってそのファイルを読みます。 Visual StudioはCopilot Chatオプションでカスタム指示のチェックボックスが選択されて初めてそれをロードします。
Statement code in this repository follows these rules:
- Statements are DOCX files written with IronWord, from the NuGet package IronWord.
- Import both namespaces, IronWord and IronWord.Models.
- Use no other Word library and no OpenXML SDK code.
- Keep the IronWord version set in Directory.Packages.props, unless the task is upgrading it.
- IRONWORD_LICENSE_KEY holds the license key, and Program.cs reads it there.
- Do not put the key in source, settings files, tests or logs.
- Never print its value, and don't list environment variables.
- docs/statement-layout.md is the layout contract. Do not edit it.
- Propose changes to that layout in your reply instead.
- IronWord's documentation for agents is at https://ironsoftware.com/word/csharp/llms.txt
- An IronWord member is real only when it builds and a saved file shows its effect.
- The documentation, its samples and IronWord.xml list some that do not compile or are not saved.
Statement tests follow these rules:
- Build statements in a temp directory and reopen the saved file with IronWord.
- Compare cell text, values and run styles. Never compare DOCX bytes.
ドキュメントコードに独自のルールをどのように付与しますか?
一部のフォルダー用のルールは、.github/instructions/documents.instructions.mdのようなパス固有のファイルにあり、ここではapplyToパターンがドキュメントコードとそのテストをカバーしています。 GitHubのCopilot CLIのドキュメントによれば、CLIはファイルが処理中のファイルがリストされたパターンと一致する場合にのみリクエストにファイルを追加します。 当社の実行では、CLIはセッションの開始時にファイルのパターンとパスをリストし、Copilotは最初の編集前にそれを読みました。
---
applyTo: "src/Statements/Documents/**,tests/Statements.Tests/**"
---
The document code and its tests follow these IronWord rules:
- Style text on a Run, with new Run(new TextStyle { ... }) or Run.Style.
- TextContent.IsBold, TextContent.FontSize and Run.FontSize are read-only.
- SaveAs drops a TextStyle assigned to TextContent.Style.
- SaveAs writes a TextStyle's FontSize only when its TextFont is set too.
- Add each body line as its own paragraph with AddParagraph.
- WordDocument.AddText joins its text onto whichever paragraph came last.
- Table.ApplyCellStyle is listed in IronWord.xml but does not compile.
- Style each cell's runs in place of ApplyCellStyle.
- new Table(rows, columns) creates every cell, with zero-based indexes.
- Fill a cell with AddChild or AddText on table[row, column].
- Table.Rows, TableRow.Cells and a TableRow indexer return ITableRow and ITableCell.
- ITableRow and ITableCell have no AddText, AddChild or ExtractText.
- Cast to TableRow or TableCell first.
- SaveAs writes no merge made with Table.MergeCells.
- For a cell that spans two columns, add a new TableRow of two TableCells with AddRow.
- Give the first of those two cells GridSpan = 2.
- Shade alternate rows with Table.Zebra = new ZebraColor(first, second).
- SaveAs writes no fill set through TableCell.Shading.
- With no key set, every save throws LicensingException.
- An in-memory build does not throw it, so it proves nothing about the saved file.
そのファイル内のすべてのルールは、ビルド、メモリ内チェック、または保存されたファイルから派生しています。出荷されたXMLドキュメントは、テーブルにApplyCellStyleをリストしていますが、コンパイラはCS1061で呼び出しを拒否するので、XMLだけではメンバーがコンパイルされるかどうかを示しません。 調査では、セルのShadingプロパティを通じて設定されたフィルが保存されたファイルに書き込まれることはありませんでしたが、Zebraはすべてのセルにフィルを書き込みました。
CSVデータからステートメントテーブルをどのように構築しますか?
ステートメントコードはこの段階でエラーなしに失敗する可能性があります。 保存されたファイルの中でMergeCellsとマージされた閉じ行にはまだ3つのプレーンセルが含まれていましたが、テーブルはメモリ内でマージを記録していました。 フォントなしで18ポイントに設定されたタイトルはサイズなしで保存されました。どちらの問題も保存されたファイルの検査でのみ検出されます。
Rework @src/Statements/Pipeline/StatementJob.cs to write one statement per account, in this order:
1. Read Data/accounts.csv and Data/transactions.csv.
2. Group the transactions by account.
3. Call StatementBuilder.Build once per account.
4. Write <AccountId>.docx into the output folder that StatementJob.Run receives.
That folder is out/statements under the solution root.
The data needs care in a few places:
- Descriptions such as "Rent, September" hold commas.
- Parse quoted fields with a few lines of your own code, and add no CSV package.
- Parse amounts as decimal with the invariant culture.
- An account with no transactions still gets a statement, with its heading and closing rows.
Run the job.
For every statement, print its path, its transaction row count and its closing balance.
フィクスチャには4つのアカウントと、5、2、3、0のトランザクションが含まれています。 CSVファイルでは、貯蓄アカウントの行は日付順になっておらず、レイアウトは最初に最古のものを要求します。
保存されたIronWordステートメントをどのようにテストしますか?
ExtractTextがドキュメントから段落を返しましたが、テーブルのテキストは返されなかったため、それに基づいたテストは、すべてのセルが空の場合でも合格します。
このプロンプトを送信する前にShift+TabでCopilot CLIを計画モードに切り替えます。
Plan an xUnit suite in tests/Statements.Tests, and wait for my approval before you write any code.
Every test loads IRONWORD_LICENSE_KEY into the License.LicenseKey property first.
ExtractText leaves out the text inside tables.
Read the statement table through Tables, Rows and Cells instead.
A reopened file reads GridSpan and MergedCells back empty.
The merged label shows up there as a closing row of two cells.
The suite has to prove these points:
- Each account in Data/accounts.csv gets a table of its transactions.
- The table also holds a heading row and that closing row.
- Cell values and the closing balance match the CSV files.
- Every heading run that holds text is bold.
- The title is bold and 18 point.
- CHK-40902 has the heading and closing rows and no others.
Once I approve, write the tests, run dotnet test and tell me the pass and fail counts.
最初に計画を立てることで、アサーションを書かれる前にスイートがマージされたセルとランのスタイルをどのように読み取るかを確認できます。
コンパイルされないIronWordスタイリングコードをどのように修正しますか?
IronWordのテーブルガイドは、TextContentのオブジェクト初期化子を使用してセルのテキストにスタイルを適用します。 そのサンプルはCS0200エラーでビルドに失敗します。これらのプロパティは読み取り専用だからです。
A teammate adapted @src/Statements/Documents/OverdraftNotice.cs from IronWord's add-table how-to.
Now the solution no longer builds.
Before you edit anything, work through these steps:
1. Build and quote each compiler error.
2. Open the IronWord.xml file inside the IronWord package in the NuGet cache.
3. List the styling members it gives for TextStyle and Run.
Then rewrite just the styling in that file.
The saved notice must keep its bold 14 point heading and its bold amount.
Rebuild and confirm the error count is zero. Don't touch any other file.
コンパイラは見出しと額にエラーを報告し、XML検索はその代わりに使用されるTextStyleメンバーをリストしています。
クラウドエージェントが行動できる問題を作成するにはどうすれば良いですか?
クラウドエージェントは、問題のタイトル、説明、既存のコメント、および割り当て時に提供された指示から作業します。 GitHubによれば、後で追加されたコメントはエージェントに渡されないため、完了基準は問題本文に含まれます。
Title: Show debit amounts in red on statements
The change covers these files and versions:
- Files: src/Statements/Documents/StatementBuilder.cs, tests/Statements.Tests
- IronWord version: the one Directory.Packages.props sets
- Framework: .NET 9
The expected result is this:
- In the Amount column, every negative amount is red (C00000).
- Positive amounts, the heading row and the closing row keep their current color.
- docs/statement-layout.md gains the rule in the pull request text only.
The actual result is that every amount is black.
The constraints are these:
- Keep the Build signature.
- Style the runs as .github/instructions/documents.instructions.md says.
- Add no packages.
The acceptance test is this:
- The current tests still pass.
- A new test reopens CHK-40211.docx and finds red runs in exactly the four debit cells.
テストは、既知のステートメントで着色されたセルをカウントするため、列全体を着色する変更は失敗します。
なぜクラウドエージェントのテストがIronWordプロジェクトで失敗するのですか?
デフォルトでは、クラウドエージェントはUbuntu Linux環境で動作します。 IronWord 2026.10.4は、linux-x64用のネイティブライブラリをパッケージ内に送り出しています。したがって、ランナー上でのNuGetリストアにはこれが含まれています。 ランナーにはライセンスキーがありません。 キーのないテストマシンでは、ステートメントはエラーなしでメモリ内で構築され、プローブ内のすべての保存呼び出しで「製品ライセンスが必要」と表示されるLicensingExceptionをスローしました。 コードが正しい場合でもファイルを書き込むすべてのテストが失敗します。
Copilotが作業を開始する前に、GitHub Actionsは.github/workflows/copilot-setup-steps.ymlからcopilot-setup-stepsジョブを実行します。 デフォルトブランチにそのファイルが含まれるまでワークフローはトリガーされません。
The cloud agent's Ubuntu runner needs .github/workflows/copilot-setup-steps.yml.
GitHub picks up a single job called copilot-setup-steps, so give the file exactly that job.
Set the job up like this:
- Give it read access to the repository contents.
- Trigger it on workflow_dispatch and on pull requests that touch the file itself.
- Fetch the code and install whichever .NET SDK the projects use.
- Run a restore, then build in Release.
Without a license key, every IronWord save throws a LicensingException.
Add a step that checks IRONWORD_LICENSE_KEY, which is an Agents secret.
GitHub documents Agents secrets for the cloud agent's environment.
That includes this workflow when it runs for the agent.
So the check works like this:
- In pull_request and workflow_dispatch runs, it prints a warning and passes.
- In any other run, it exits non-zero with a clear message when the key is empty.
Put that step last, because a failing setup step makes Copilot skip whatever follows it.
Write the file, then show me the finished YAML.
チェックを最後に置くと、メッセージの秘匿がまだ復元およびコンパイルされたソリューションを残し、問題を識別する1 行が追加されます。
キーをエージェントのシークレットとして保存してください:クラウドエージェントに渡されるシークレットは、Actions、Codespaces、またはDependabotのために保存されたシークレットではありません。 リポジトリの設定にIRONWORD_LICENSE_KEYを追加し、セキュリティ、シークレットおよび変数、エージェントの下にあり、エージェントは環境変数として受け取ります。
マージする前に何を確認すべきですか?
それ自身のcopilot -p呼び出しでレビューを開始し、それはコードを書いたセッションとは別のセッションで実行されます。
/review every change committed after the first commit on this branch.
Hold every IronWord call up against .github/instructions/documents.instructions.md.
Check it against the XML API documentation in the IronWord NuGet package as well.
List each place they conflict.
Also flag any of these:
- styling set on TextContent instead of on runs
- a table cell filled anywhere but on the cell the table already holds
- a closing row that spans its label with MergeCells instead of GridSpan
- a font size with no TextFont beside it
- a test that reads table data with ExtractText instead of reloading the saved file
- any line that prints IRONWORD_LICENSE_KEY
Tell me what you find, and don't edit any file.
プロンプトが実運用で生成したものは何ですか?
Copilot CLIは、このガイド用に組み立てられたステートメントソリューションで6つのプロンプトすべてを無人で実行しました。各コミットを再ビルドし、ジョブとテストを再実行し、IronWordを使用しないスクリプトでDOCXファイルを読みました。
- 同僚の通知ファイルはスタイリングプロンプトの前に3つのCS0200ビルドエラーを引き起こし、その後は0でした。
- スタイリング修正で変更されたのはそのファイルのみです。
- 通知は太字14ポイントの見出しと太字の額を保持しました。
- 全ての4つのステートメントがCSVプロンプト以降のDOCXチェックに合格しました。
- 全ての4つの閉じ残高はCSVデータと一致しました。
- それぞれの閉じ行には2つのセルがあり、ラベルは2つの列にまたがっていました。
- タイトルは18ポイントで太字でした。
- 見出し行が太字でした。
- 行はFFFFFFとF2F2F2が交互になっていました。
- Copilotの3つのテストが合格しました。
- 各テストはその行とセルを通して保存されたテーブルを読みました。
- セットアップワークフローはYAMLとして解析され、1つのcopilot-setup-stepsジョブとキー確認が最後にありました。
- レビューの呼び出しはファイルを変更せず、ビルダーの2箇所をフラグしました。 1つはパス固有のファイルが指定する通りに行を追加する前に終了行のセルを埋めます。 もう1つはAddChildやAddTextの代わりにTableCell.SetContentを使用します。
- 一部のステップはページと異なる方法で実行されました。 セッションはヘッドレスで実行されたため、プランモードは--planフラグを使用し、承認はタイプされた返信でした。 問題、クラウドエージェント、エージェントシークレット、セットアップワークフローにはホスティングされたリポジトリが必要ですが、実行されませんでした。
カーソルガイドは、そのIronWordルールをグロブでファイルパターンにスコープし、ここでパス固有の指示ファイルがapplyToで行うのと同様にします。 Google Antigravityガイドは、IronWordのページをlinux-x64用に公開し、クラウドエージェントが実行されるプラットフォームです。
Copilot CLIバージョン、Autoによって選ばれたモデル、テストマシン、および実行時間が共有実行記録に表示されます。
トラブルシューティング
- DOCXにテーブルを追加は行、セル、ボーダー、シェーディング用
- DOCXでテキストをスタイリングはフォント、サイズ、太字テキスト用
- DOCXからテキストを抽出は段落テキストとテーブルからのセルごとの抽出用
- ライセンスキーの適用はコード内、Web.configまたはappsettings.jsonからキーを設定するため
- DockerでのIronWordはLinuxランナーおよびコンテナ用
質問ありますか?
質問がある場合は、support@ironsoftware.com にお問い合わせください。
Curtis Chauは、カールトン大学でコンピュータサイエンスの学士号を取得し、Node.js、TypeScript、JavaScript、およびReactに精通したフロントエンド開発を専門としています。直感的で美しいユーザーインターフェースを作成することに情熱を持ち、Curtisは現代のフレームワークを用いた開発や、構造の良い視覚的に魅力的なマニュアルの作成を楽しんでいます。