IronWord를 GitHub Copilot과 함께 사용하는 방법

Curtis Chau
Curtis Chau
업데이트됨: 2026년 10월 19일

.NET 서비스는 매월 계정 명세서를 워드 파일로 생성할 수 있습니다. 각 파일에는 스타일이 적용된 제목, 두 개의 요약 줄, 데이터를 기반으로 작성된 표가 포함됩니다. 이 가이드에서는 서비스가 그 데이터를 제공하는 작업들과 함께 Visual Studio 솔루션에 존재하므로, 이를 수정하는 모든 조수는 동일한 솔루션 내에서 작동해야 합니다.

GitHub Copilot은 Visual Studio 또는 VS Code에서 채팅 또는 에이전트 모드로 작업할 수 있으며, 터미널에서는 Copilot CLI로, GitHub에서는 할당된 이슈에 대해 클라우드 에이전트가 풀 요청을 엽니다. IronWord는 코드에서 텍스트와 스타일이 적용된 테이블을 병합된 셀과 음영 처리된 행으로 DOCX를 작성합니다. IronWord 규칙은 저장소의 지침 파일에 보관되며, 각 표면은 이를 읽습니다.

테이블 가이드와 텍스트 스타일 가이드는 이 가이드가 의존하는 API의 두 부분을 다룹니다.

빠른 시작
NuGetNuGet으로 설치

PM > Install-Package IronWord

위 명령을 NuGet 패키지 관리자 콘솔에 입력하거나 NuGet 패키지 관리자에서 패키지를 검색하여 IronWord를 설치하십시오.

솔루션 루트에서 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.
Text

프롬프트에 스타일링 멤버는 지정되어 있지 않습니다. 경로별로 지정된 지침 파일은 사용할 멤버를 지정합니다.

솔루션의 Program.cs는 IRONWORD_LICENSE_KEY를 환경에서 읽고 IronWord.License.LicenseKey에 할당하므로, Copilot을 시작하기 전에 변수를 설정하세요. 라이선스 키 가이드는 동일한 할당과 키를 보관할 수 있는 구성 파일을 보여줍니다.



Copilot에 대한 IronWord 규칙을 어떻게 설정하나요?

전체 저장소의 규칙은 .github/copilot-instructions.md에 기록됩니다. Copilot CLI, Copilot 코드 리뷰, 클라우드 에이전트, 그리고 JetBrains IDE, 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.
Markdown

문서 코드에 자체 규칙을 어떻게 부여하나요?

일부 폴더에 대한 규칙은 문서 코드와 그 테스트를 커버하는 applyTo 패턴이 포함된 .github/instructions/documents.instructions.md와 같은 경로별 파일에 기록됩니다. 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.
Markdown

해당 파일의 모든 규칙은 빌드, 메모리 내 검사 또는 저장된 파일에서 파생됩니다. 배포된 XML 문서가 표에서 ApplyCellStyle를 나열하지만, 컴파일러는 CS1061로 호출을 거부하므로 XML만으로는 멤버가 컴파일되는지를 보여주지 않습니다. 프로브는 셀의 Shading 속성을 통해 설정된 채우기가 저장된 파일에 결코 기록되지 않았고, Zebra는 각 셀에 채우기를 기록했다고 보여줬습니다.

CSV 데이터로부터 명세서 표를 어떻게 작성하나요?

이 단계에서 명세서 코드는 오류를 생성하지 않고 실패할 수 있습니다. 저장된 파일에서는 MergeCells와 병합된 마무리 행이 여전히 세 개의 일반 셀을 포함하고 있었지만, 표는 메모리 내에서 병합을 기록했습니다. 폰트없이 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.
Text

고정장치에는 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.
Text

먼저 계획을 세우면, 어떤 주장도 작성되기 전에 병합된 셀과 실행의 스타일을 IronWord 스위트가 읽는 방법을 확인할 수 있습니다.

컴파일되지 않는 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.
Text

컴파일러는 제목과 금액에 대해 오류를 보고하고, 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.
Markdown

테스트는 알려진 하나의 명세서에서 색상을 기준으로 셀을 계산하기 때문에, 열을 전체적으로 색칠하는 변경은 실패합니다.

왜 클라우드 에이전트의 테스트가 IronWord 프로젝트에서 실패하나요?

기본적으로 클라우드 에이전트는 Ubuntu Linux 환경에서 작동합니다. IronWord 2026.10.4는 패키지 내부에 linux-x64용 네이티브 라이브러리를 제공하므로, 러너에서의 NuGet 복원은 이를 포함합니다. 러너에는 라이선스 키가 없습니다. 키가 없는 테스트 머신에서, 명세서는 메모리 내에서 오류 없이 작성되었고, 프로브의 모든 저장 호출은 "Production License Required"라는 메시지로 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.
Text

확인 사항을 마지막에 두면, 누락된 비밀도 복원 및 컴파일된 솔루션과 문제를 식별하는 한 줄을 남깁니다.

키를 에이전트 비밀로 저장하세요: 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.
Text

실제 실행에서 프롬프트가 무엇을 생성했습니까?

Copilot CLI는 이 가이드를 위해 작성된 명세서 솔루션의 6개 프롬프트를 무인으로 실행했습니다. 우리는 각 커밋을 재빌드하고, 작업과 테스트를 다시 수행했으며, IronWord를 사용하지 않는 스크립트로 DOCX 파일을 읽었습니다.

  • 팀원의 통지 파일은 스타일링 프롬프트 전에는 3개의 CS0200 빌드 오류를 발생시키고, 이후에는 0으로 줄었습니다.
  • 스타일링 수정을 통해 변경된 파일은 그 파일 하나뿐이었습니다.
  • 통지는 굵은 14 포인트의 제목과 굵은 금액을 유지했습니다.
  • 모든 4개의 명세서는 CSV 프롬프트 이후 DOCX 검사에 통과했습니다.
  • 모든 4개의 종결 잔고는 CSV 데이터와 일치했습니다.
  • 각 마무리 행은 두 개의 셀을 가지고 있었으며, 레이블은 두 열에 걸쳐 있었습니다.
  • 제목은 굵은 18 포인트였습니다.
  • 제목 행은 굵게 표시되었습니다.
  • 행은 FFFFFF와 F2F2F2로 교대로 표시되었습니다.
  • Copilot의 3개의 테스트는 통과했습니다.
  • 각 테스트는 저장된 테이블을 행과 셀을 통해 읽었습니다.
  • 설정 워크플로는 YAML로 파싱되었으며, 하나의 copilot-setup-steps 작업과 키 확인이 마지막이었습니다.
  • 리뷰 호출은 파일을 변경하지 않고 빌더의 두 곳을 표시했습니다. 하나는 경로별 파일에서 지정된 대로 행을 추가하기 전에 마무리 행의 셀을 채웁니다. 다른 하나는 AddChild나 AddText 대신 TableCell.SetContent를 사용합니다.
  • 일부 단계는 페이지와 달리 작동했습니다. 세션은 무대모드로 실행되었으므로, plan 모드는 --plan 플래그를 사용하였고 승인은 입력된 응답이었습니다. 이슈, 클라우드 에이전트, 에이전트 비밀 및 설정 워크플로는 호스트된 저장소가 필요하며 실행되지 않았습니다.

Cursor 가이드는 IronWord 규칙을 파일 패턴에 glob으로 범위를 지정하며, 경로별 지침 파일은 여기에서 applyTo와 함께 그렇게 합니다. Google Antigravity 가이드는 클라우드 에이전트가 실행되는 플랫폼인 linux-x64용 IronWord 페이지를 게시합니다.

Copilot CLI 버전, Auto가 선택한 모델, 테스트 머신 및 실행 시간은 공유 실행 기록에 나타납니다.


문제 해결


질문?

질문이 있으시면 support@ironsoftware.com으로 문의하세요.

커티스 차우는 칼턴 대학교에서 컴퓨터 과학 학사 학위를 취득했으며, Node.js, TypeScript, JavaScript, React를 전문으로 하는 프론트엔드 개발자입니다. 직관적이고 미적으로 뛰어난 사용자 인터페이스를 만드는 데 열정을 가진 그는 최신 프레임워크를 활용하고, 잘 구성되고 시각적으로 매력적인 매뉴얼을 제작하는 것을 즐깁니다.

더 읽기

시작할 준비 되셨나요?

NuGet 다운로드 수 62,392버전:2026.11방금 출시