Jak używać IronWord z Claude Code

Curtis Chau
Curtis Chau
Zaktualizowano: 19 października 2026

Każdego listopada, ubezpieczyciel wysyła listy odnowienia do swoich klientów. Zespół ds. zgodności zarządza jednym szablonem Word do brzmienia listu, podczas gdy imiona, daty, składki i szczegóły pokrycia są pozyskiwane z systemu polisowego. Scalony list, który wygląda na kompletny, nie dowodzi, że scalenie zadziałało. W testach za tym przewodnikiem, scalenia, które pozostawiły pusty wiersz pokrycia, zgubiły numer referencyjny lub ponownie wykorzystały dane pierwszego klienta, zakończyły się bez wyjątku. Claude Code, narzędzie do kodowania agentowego od Anthropic, czyta bazę kodu, edytuje pliki i uruchamia polecenia z terminala, VS Code, IDE JetBrains, aplikacji desktopowej lub przeglądarki.

IronWord wypełnia MERGEFIELD w szablonach DOCX używając słowników, wierszy danych lub zestawów danych oraz obsługuje powtarzające się regiony dla wierszy tabeli. Nie wymaga Microsoft Office. Samo scalenie wymaga kilku linii kodu. Kolejność wywołań i domyślne opcje determinują, czy wynik jest poprawny, a niektóre błędy mogą prowadzić do niewłaściwych wyników bez wywołania wyjątku. Cztery przetestowane podpowiedzi poniżej konfigurują Claude Code do produkcji partii listów odnowienia, a każda z nich jest wspierana przez odpowiednie zachowanie IronWord.

Szybki start
NuGetInstalacja z NuGet

PM > Install-Package IronWord

Zainstaluj IronWord, wykonując powyższe polecenie w konsoli Menedżera Pakietów NuGet lub wyszukaj pakiet w Menedżerze Pakietów NuGet.

Rozpocząć claude w folderze projektu i uruchomić /model opusplan raz, przed jakąkolwiek podpowiedzią. @ przed ścieżką dołącza zawartość tego pliku do żądania.

Add the IronWord NuGet package, version 2026.10.4, to RenewalLetters.csproj.
Then write one renewal letter in Program.cs.

Merge the first customer row of @Data/customers.csv into @Templates/renewal-letter.docx.
Save the letter to out/letters/NM-104233.docx.
Create that folder first, and pass the path to the save call.
Don't change the template file.

Next, open the saved letter in a new WordDocument and print these in order:

1. The body text.
2. The text of every table cell, row by row, with each cell cast to TableCell to read it.
3. The names of any merge fields still in the document, or "none".

My license key is in the IRONWORD_LICENSE_KEY environment variable.
Have the program read that variable itself and apply the key before the first IronWord call.
Don't print, echo or save the key anywhere.
Don't list environment variables to look for it either.
Tell me whether it's set and nothing more.
Text

Sprawdź wynik tabeli przed tekstem głównym. Wiersze pokrycia znajdują się w powtarzającym się regionie, który wypełnia tylko wywołanie regionu.



Co robi Claude Code w projekcie dokumentu Word .NET?

Claude Code tworzy usługę scalania i produkuje jeden list na polisę z dwóch plików CSV. Następnie ponownie otwiera każdy zapisany list i sprawdza go. Gdy kontrola zawodzi, poprawia kod scalania i ponownie uruchamia partię. Deweloper decyduje, co powinien zawierać poprawny list i przegląda plik audytu na końcu.

Nazwij pakiet IronWord i jego wersję w pierwszej podpowiedzi. Atakujący rejestrują złośliwe pakiety pod nazwami pakietów, które modele językowe wymyślają, technika ta zwana jest slopsquatting.

Jak skonfigurować Claude Code?

Szybki start Anthropic zawiera instalację i logowanie. Ustawienia są zakończone, gdy claude otwiera się w terminalu i odpowiada.

Jak skonfigurować projekt, w którym Claude Code może pracować?

Najpierw umieść prawdziwe wejścia w repozytorium. Fixtures użyte w tym przewodniku składają się z aplikacji konsolowej .NET 9, która się kompiluje, folderu Templates zawierającego list odnowienia z jego polami merge i folderu Data z jednym CSV klientów i jednym wierszy pokrycia kluczonych numerem polisy.

Claude Code ładuje CLAUDE.md do każdej nowej sesji, więc jego zasady dotyczą wszystkich późniejszych podpowiedzi. Po zainstalowaniu pakietu przez Quickstart, druga podpowiedź tworzy ten plik i recenzenta dla kodu merge.

Create CLAUDE.md in the repository root and give it a section called Mail merge.
Every later session should find these rules in it:

- IronWord is the only DOCX library this project may use.
- The NuGet package is IronWord, at the version RenewalLetters.csproj references now.
- Look up IronWord member names in docs/IronWord.xml.
- Templates/ is read-only, and each letter starts from a new load of the template file.
- The license key rules from my first message, written out in full.
- A letter isn't finished until the saved file has been reopened and checked.

Copy docs/IronWord.xml now from the ironword folder of the local NuGet cache.
If the file isn't there, stop and say so.

Then add a subagent at .claude/agents/merge-auditor.md.
Give it the Read, Grep and Glob tools and no others.
Its job is to list every IronWord type and member used under Services/.
It should name each one that docs/IronWord.xml doesn't document.
IronSoftware.* types such as ITableCell are documented in other packages.
Have it list those separately, so it doesn't call them missing.
Text

Claude Code monitoruje .claude/agents pod kątem nowych plików subagentów, ale monitorowany jest tylko folder uruchomiony na starcie, dlatego stwórz ten folder przed rozpoczęciem sesji. W celu dokumentacji wykraczającej poza listę członków, agenci mogą zacząć od llms.txt IronWord, który łączy przewodniki typu how-to i strony rozwiązywania problemów.

Omów licencjonowanie przed pierwszym zapisem. Bez klucza, każde wywołanie zapisu wywołuje LicensingException, który mówi "Wymagana licencja produkcyjna". Dotyczy to Save z lub bez ścieżki lub strumienia oraz SaveAs. Strona Licencyjna IronWord omawia wersje próbne i płatne klucze oraz jak ustawić jeden w kodzie lub pliku konfiguracyjnym.

Jakie zasady scalania poczty IronWord należą do CLAUDE.md?

Próba na szablonie fixture sprawdziła każdą linię w stosunku do IronWord 2026.10.4, z kluczem licencyjnym dla ostatnich trzech. Dodaj blok pod sekcją scalania poczty.

IronWord 2026.10.4 behaves this way in a mail merge:

- MailMerge.Execute(DataTable) merges the first row only.
- Merge each row into its own WordDocument, loaded fresh from the template file.
- A merge removes the fields it fills, so a second Execute on the same document changes nothing.
- Call ExecuteWithRegions before Execute.
- Execute removes any region it has no table for, because RemoveUnusedRegions defaults to true.
- That region's row then stays in the table with empty cells.
- A region table with no rows removes the region row and keeps the rest of the table.
- RemoveUnusedFields defaults to true, so a field with no matching key is deleted with no error.
- Compare GetFieldNames() with the data columns before merging.
- Field names match without regard to case unless CaseInsensitiveFieldNames is set to false.
- NullValueReplacement replaces DBNull values. An empty string merges as an empty string.
- WordDocument.ExtractText() returns body paragraphs only, joined with no separator.
- ExtractText() skips table cells, the header and the footer.
- Rows[i].Cells holds ITableCell values, which have no ExtractText().
- Cast each cell to TableCell before calling ExtractText() on it.
- GetFields() and GetFieldNames() don't see merge fields in the header.
- Save each letter with Save(outputPath).
- One troubleshooting page reports a header that SaveAs(outputPath) dropped and Save kept.
- Never call Save() with no argument. It overwrites the file the document was loaded from.
Markdown

Reguła nieużywanych pól wykazała najmniej widoczną porażkę w próbach. Szablon zawiera „Odwołanie” po którym następuje pole kodu referencyjnego bez pasującej kolumny w pliku klienta, a domyślne scalenie zmieniło zdanie na „Odwołanie . Podaj ten numer, kiedy do nas dzwonisz." bez wywołania wyjątku.

Jak scalać szablon Word z powtarzającymi się wierszami tabeli?

Oznacz powtarzający się wiersz w szablonie polem startowym i polem końcowym, które dzielą nazwę regionu. W szablonie fixture, wiersz pokrycia zaczyna się od TableStart:Coverages i kończy się TableEnd:Coverages. Wywołanie regionu akceptuje tabelę danych, której nazwa pasuje do regionu i kopiuje wiersz raz na każdy wiersz danych. Wywołanie wartości następnie wypełnia każde pole poza regionem z słownika lub pojedynczego wiersza danych.

Przewodnik scalania poczty dokumentuje każde przeciążenie i opcje scalania.

Jak wywołać kod IronWord, który się kompiluje?

Scalenie i jego audyt idą w jednej podpowiedzi, wysłanej w trybie planu, aby projekt został ustalony przed jakimikolwiek zmianami plików. Przełączyć się z Shift+Tab na tryb planowania i wysłać podpowiedź, gdy pasek stanu to pokazuje. Z opusplan, Opus obsługuje plan, a Sonnet pisze kod po zatwierdzeniu.

Build the batch in Services/LetterMerger.cs and Services/LetterAudit.cs.
Run both from Program.cs after the Quickstart letter.

LetterMerger reads @Data/customers.csv and @Data/coverages.csv.
For each customer it does this:

1. Loads Templates/renewal-letter.docx again.
2. Fills the Coverages region with that policy's rows, if any.
3. Fills the other fields from the customer row.
4. Saves out/letters/<PolicyNumber>.docx.

Before the first merge, it prints each template merge field with no column in either CSV.

LetterAudit opens each saved letter from disk and passes it when these all hold:

- Every customer value appears in the body text.
- The coverage table holds only that policy's rows, in CSV order.
- word/document.xml, read as a zip entry, has no merge field or MERGEFIELD instruction left.

For an empty customer value, check its whole sentence.
One case is the agent sentence with no phone number.

Two more columns don't count toward a pass:

- Header, from word/header1.xml: shows the policy number, still has the merge field, or is missing.
- Footer, from word/footer1.xml: matches the template's footer, changed, or is missing.

Write out/letter-audit.csv with one row per letter.
Print how many letters pass.
After the batch, run git status on Templates/ and tell me about any change.

Don't use a docx skill or rewrite any package XML by hand.
The audit can read parts as zip entries.
Keep fixing the merger until every letter passes.
If a header keeps its field, tell me whether any IronWord call reached it.
Then have the merge-auditor subagent review Services/.
Text

Dwie części podpowiedzi zależą od zachowania IronWord i Claude Code.

  1. Audyt odczytuje zapisany pakiet: nagłówek i stopka nie są zawarte w ekstraktowanym tekście ani na liście pól. Ich kolumny są wykluczone z liczby przejść, ponieważ żadne wywołanie scalania IronWord nie wypełnia nagłówka, więc liczenie go doprowadziłoby agenta do obejścia XML, które podpowiedź zabrania.
  2. Recenzent tylko do odczytu: niestandardowe subagenty ładują CLAUDE.md, tak samo jak wszyscy wbudowani agenci oprócz Explore i Plan, więc audytinelle skaluje się usługi z zasadami scalania poczty.
Porady: Zatwierdź plan tylko wtedy, gdy ładuje szablon wewnątrz pętli na klienta i umieszcza wywołanie regionu przed wywołaniem wartości. Plan, który ładuje szablon raz, produkuje pięć kopii pierwszego listu.

Czy kod scalania IronWord może być testowany bez klucza licencyjnego?

Tak, o ile test zatrzyma się przed zapisem. Ładowanie szablonu, scalanie go i odczytywanie tekstu przebiega bez licencji, więc agent budujący bez klucza nadal może uruchomić testy scalania.

Add a RenewalLetters.Tests xUnit project that tests LetterMerger without writing any file.

Merge NM-104267 and NM-104288 in memory.
Assert the body text and every coverage table cell against the CSV rows.
Cover the policy with no coverage rows and the agent sentence with an empty phone number.

A few things about the setup:

- Split the merge from the save in LetterMerger if a test needs that.
- Leave the license key unset when the variable is missing.
- Put the test project in its own folder, with no solution file at the repository root.
- Keep RenewalLetters.csproj from compiling the files in that folder.
- Have the test project copy Templates/ and Data/ to its output folder.

Run dotnet test on the test project once, in a child process with no IRONWORD_LICENSE_KEY variable.
Show me the tests passing without a key.
Text

Co powinno się zweryfikować przed zaufaniem wygenerowanemu kodowi IronWord?

Porównaj każdą wartość z testem zawartości na ekstraktowanym tekście głównym, ponieważ jego akapity są zwracane bez przerw między nimi.

Dodaj trzy kontrole do recenzji.

  • Kompilacja: dotnet build zawodzi na każdej nazwie członka, której brakuje IronWord. Dostarczony IronWord.xml również wymienia członków, którzy nie są publiczni, więc nazwa znaleziona tam nadal może zawieść z CS1061, jak to miało miejsce w próbie z dwoma członkami WordDocument.
  • Szablon: porównaj z jego zatwierdzoną kopią po partii. W naszym próbnym z licencją, pojedynczy zapis bez argumentu zastąpił szablon listem scalonym pierwszego klienta, więc każde późniejsze ładowanie tego pliku nie zawierało pól do wypełnienia.
  • Nagłówek: strona rozwiązywania problemów z nagłówkami instruuje czytelników, by otworzyć swój własny wynik i sprawdzić nagłówek. Ta sama próba wykazała, że każde wywołanie zapisu zachowało nagłówek i stopkę bajt po bajcie.

Przewodnik po asystentach kodowania AI zawiera kompletne zadanie IronWord, którego kryteria zdawcze są stałe, więc każdy czytelnik może je ponownie uruchomić.

Co wyprodukowały zapytania w rzeczywistym uruchomieniu?

Claude Code wykonalo cztery prompty w jednej sesji, w kolejnosci. Blok scalania poczty wszedł do CLAUDE.md przed podpowiedzią 3. Żaden kod nie był edytowany ręcznie. Dane zawierały pięciu klientów i dziesięć wierszy pokrycia. Czysta kompilacja Release dała ten sam plik audytu. Nasza inspekcja pakietu dopasowała każdy wiersz.

  • List Quickstart, scalony tylko z wartościami, zachował wiersz nagłówka i jeden pusty wiersz.
  • Wszystkie 5 listów zawartości zaliczyło pierwszy audyt.
  • Listy miały 3, 1, 4, 0 i 2 wiersze pokrycia, jak w CSV.
  • Wstępne sprawdzenie zgłosiło jedno pole bez kolumny danych, ReferenceCode.
  • Pole numeru polisy pozostało we wszystkich 5 nagłówkach.
  • Każda stopka dopasowana do szablonu.
  • 4 z 4 testów przeszły z IRONWORD_LICENSE_KEY nieobecnym w procesie.
  • Subagent nie znalazł żadnego członka IronWord brakującego w IronWord.xml.
  • Hash szablonu pozostał niezmieniony po partii.
  • Każda podpowiedź zakończyła się czystą kompilacją Release.
  • Klucz licencyjny był nieobecny we wszystkich zapisach, plikach sesji i plikach repozytorium tego uruchomienia.
  • W podpowiedziach 1 i 4, test powłoki drukował tylko, czy klucz został ustawiony.
  • Niektóre kroki uruchomiono inaczej niż na stronie. Ponieważ sesja była prowadzona bez interfejsu graficznego, operator zatwierdził plan podpowiedzi 3 odpowiedzią tekstową. Podpowiedź 3 zmieniła wywołanie SaveAs Quickstart na Save, aby stosować CLAUDE.md.

W Przewodniku po kursorze, kursor również planuje przed edytowaniem jakiegokolwiek pliku i zapisuje plan do edytowalnego pliku. Przewodnik ChatGPT Codex przechowuje swoje stałe instrukcje w AGENTS.md, odpowiednik Codex CLAUDE.md.

Wspólna karta uruchomienia zawiera tę wersję Claude Code, modele, czas trwania i maszynę testową.


Rozwiązywanie problemów


Pytania?

Jeśli są jakiekolwiek pytania, należy skontaktować się z support@ironsoftware.com

Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.

Czytaj więcej

Gotowy, aby rozpocząć?

Pobrania z NuGet 62,392Wersja:2026.11właśnie wydane