Jak korzystać z IronWord z GitHub Copilot
Usługa .NET może generować miesięczne wyciągi z kont jako pliki Word, każdy z wystylizowanym tytułem, dwoma liniami podsumowania i tabelą zbudowaną z danych. W tym przewodniku usługa działa w rozwiązaniu Visual Studio razem z zadaniami dostarczającymi jej dane, więc każdy asystent, który ją modyfikuje, musi działać w tym samym rozwiązaniu.
GitHub Copilot może pracować nad tym rozwiązaniem z Visual Studio lub VS Code w trybie czatu lub agenta, z terminala z Copilot CLI oraz z GitHub, gdzie jego agent w chmurze otwiera pull request dla przypisanego do niego problemu. IronWord buduje plik DOCX w kodzie z wystylizowanymi fragmentami tekstu i tabelami, które mają scalone komórki i zacienione wiersze. Zasady IronWord są przechowywane w plikach z instrukcjami w repozytorium, i każda z tych powierzchni je odczytuje.
Przewodnik po tabelach oraz Przewodnik po stylach tekstu obejmują dwie części API, na których opiera się ten przewodnik.
Szybki startUruchomić Copilot CLI z podstawowego katalogu rozwiązania i wkleić poniższą podpowiedź. Copilot Chat w Visual Studio odnosi się do pliku z #, podczas gdy CLI używa @.
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.
Podpowiedź nie nazywa żadnego członka stylizacji. Poniższy plik z instrukcjami specyficznymi dla ścieżki określa członków do użycia.
Plik Program.cs w rozwiązaniu odczytuje IRONWORD_LICENSE_KEY ze środowiska i przypisuje go do IronWord.License.LicenseKey, więc należy ustawić zmienną przed uruchomieniem Copilot. Przewodnik po kluczach licencyjnych pokazuje to samo przypisanie i pliki konfiguracyjne, które mogą przechowywać klucz.
Minimalny proces (5 kroków)
- Pobierz bibliotekę Word C# z NuGet
- Zapisz zasady IronWord w .github/copilot-instructions.md plus jeden plik z instrukcjami specyficznymi dla ścieżki.
- Stylizuj tekst na przebiegach i dodaj scalony końcowy wiersz jako osobny wiersz.
- Ponownie otwórz każdy zapisany wyciąg i porównaj jego komórki z danymi źródłowymi.
- Przydziel następną zmianę do agenta w chmurze jako problem i zweryfikuj pull request w odniesieniu do dokumentacji API IronWord.
Jak ustawić konwencje IronWord dla Copilot?
Zasady dla całego repozytorium znajdują się w .github/copilot-instructions.md. Copilot CLI, recenzja kodu Copilot, agent w chmurze oraz Copilot Chat w JetBrains IDEs, Visual Studio i VS Code odczytują ten plik zgodnie z matrycą wsparcia GitHub. Visual Studio wczytuje go dopiero po zaznaczeniu opcji z instrukcjami niestandardowymi w opcjach 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.
Jak nadać kodowi dokumentu własne zasady?
Zasady dla niektórych folderów znajdują się w pliku specyficznym dla ścieżki, takim jak .github/instructions/documents.instructions.md, którego wzorce applyTo tutaj obejmują kod dokumentu i jego testy. Dokumentacja Copilot CLI GitHub mówi, że CLI dodaje plik do żądania tylko wtedy, gdy plik, którym się zajmuje, pasuje do wymienionego wzorca. Podczas naszego uruchomienia CLI wymieniło wzorce i ścieżkę pliku na początku każdej sesji, a Copilot odczytał plik przed pierwszą edycją.
---
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.
Każda zasada w tym pliku jest wyprowadzana z budowy, sprawdzenia w pamięci lub zapisanego pliku. Dołączona dokumentacja XML wymienia ApplyCellStyle na tabeli, ale kompilator odrzuca wywołanie z CS1061, więc sam XML nie pokazuje, czy członek jest kompilowany. Sonda wykazała, że uzupełnienie ustawione przez właściwość Shading komórki nigdy nie zostało zapisane w pliku, podczas gdy Zebra zapisało uzupełnienie do każdej komórki.
Jak zbudować tabelę wyciągów z danych CSV?
Kod wyciągu może zawieść na tym etapie bez generowania błędu. W zapisanych plikach końcowy wiersz scalony z MergeCells nadal zawierał trzy zwykłe komórki, chociaż tabela zapisała scalanie w pamięci. Tytuł ustawiony na 18 punktów bez czcionki został zapisany bez rozmiaru. Tylko inspekcja zapisanego pliku wykrywa oba problemy.
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.
Fixture zawiera cztery konta, z pięcioma, dwoma, trzema i zero transakcji. W pliku CSV wiersze konta oszczędnościowego nie są w porządku daty, a układ wymaga najstarszych najpierw.
Jak przetestować zapisany wyciąg IronWord?
Dokument ExtractText zwrócił swoje akapity, ale żadnego z tekstu tabeli, więc test oparty na tym przechodzi nawet wtedy, gdy każda komórka jest pusta.
Przełącz Copilot CLI na tryb planowania klawiszem Shift+Tab przed wysłaniem tej podpowiedzi.
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.
Z planem najpierw można sprawdzić, jak pakiet odczytuje scaloną komórkę i styl przebiegu przed zapisaniem jakiejkolwiek asercji.
Jak naprawić kod stylizacji IronWord, który się nie kompiluje?
Przewodnik po tabelach IronWord stylizuje tekst komórki za pomocą inicjalizatora obiektu na TextContent. Przykład ten nie kompiluje się z CS0200, ponieważ te właściwości są tylko do odczytu.
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.
Kompilator zgłasza błędy na nagłówku i kwocie, a wyszukiwanie XML wymienia członków TextStyle, które zamiast tego wykorzystuje poprawka.
Co sprawia, że temat jest działaniem, które agent chmurowy może realizować?
Agent w chmurze pracuje z tytułu, opisu i istniejących komentarzy do problemu, plus jakiekolwiek instrukcje dostarczone podczas przypisania. Według GitHub, komentarze dodane później nigdy nie są przekazywane do agenta, więc kryteria ukończenia należą do treści problemu.
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.
Ponieważ test zlicza kolorowe komórki w jednym znanym wyciągu, zmiana kolorująca całą kolumnę oblewa go.
Dlaczego testy agenta w chmurze oblewają na projekcie IronWord?
Domyślnie agent w chmurze działa w środowisku Ubuntu Linux. IronWord 2026.10.4 dostarcza natywną bibliotekę dla linux-x64 wewnątrz pakietu, więc przywrócenie NuGet na runnerze go obejmuje. Runner nie ma klucza licencyjnego. Na maszynie testowej bez klucza, wyciąg zbudowany w pamięci bez błędu, a każde wywołanie zapisu w sondzie wyrzucało LicensingException z wiadomością 'Production License Required'. Każdy test, który zapisuje plik, zawodzi, nawet gdy kod jest poprawny.
Zanim Copilot rozpocznie pracę, GitHub Actions wykonuje zadanie copilot-setup-steps z .github/workflows/copilot-setup-steps.yml. Workflow nie jest uruchamiany dopóki domyślna gałąź nie zawiera tego pliku.
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.
Z umieszczeniem kontroli na końcu, brakujący sekret pozostawia nadal przywrócone i skompilowane rozwiązanie, plus jedna linia identyfikująca problem.
Przechowuj klucz jako sekret Agenta: sekrety zapisane dla Actions, Codespaces lub Dependabot nie są przekazywane do agenta w chmurze. Dodaj IRONWORD_LICENSE_KEY w Ustawieniach repozytorium w sekcji Bezpieczeństwo, Sekrety i zmienne, Agenci, a agent otrzyma go jako zmienną środowiskową.
Co należy sprawdzić przed scaleniem?
Rozpocząć recenzję jej własnym wywołaniem copilot -p, aby działało w innej sesji niż ta, która napisała kod.
/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.
Co wyprodukowały zapytania w rzeczywistym uruchomieniu?
Copilot CLI uruchomił wszystkie sześć podpowiedzi bez nadzoru nad rozwiązaniem wyciągu zbudowanym dla tego przewodnika. Odbudowaliśmy każdy commit, ponownie uruchomiliśmy zadanie i testy, i odczytaliśmy pliki DOCX skryptem, który nie używa IronWord.
- Plik zawiadomienia współpracownika spowodował 3 błędy budowy CS0200 przed podpowiedzią stylizacji i 0 po niej.
- Tylko ten plik zmienił się w poprawce stylizacyjnej.
- Zawiadomienie zachowało swój pogrubiony nagłówek 14 punktów i pogrubioną kwotę.
- Wszystkie 4 wyciągi przeszły kontrolę DOCX od podpowiedzi CSV.
- Wszystkie 4 końcowe salda zgadzały się z danymi CSV.
- Każdy końcowy wiersz miał dwie komórki, z etykietą obejmującą dwie kolumny.
- Tytuł był pogrubiony w 18 punktach.
- Wiersz nagłówka był pogrubiony.
- Wiersze przeplatały się w FFFFFF i F2F2F2.
- 3 testy Copilot przeszły.
- Każdy test czytał zapisaną tabelę poprzez jej wiersze i komórki.
- Workflow konfiguracji parsował jako YAML, z jednym zadaniem copilot-setup-steps i kontrolą klucza ostatnią.
- Wywołanie recenzji nie zmieniło żadnego pliku i oznaczyło dwa miejsca w generatorze. Jedno wypełnia komórki końcowego wiersza przed dodaniem wiersza, jak specyfikuje plik specyficzny dla ścieżki. Drugie używa TableCell.SetContent zamiast AddChild lub AddText.
- Niektóre kroki uruchomiono inaczej niż na stronie. Sesja była uruchamiana bez głowy, więc tryb planu używał flagi --plan, a zatwierdzenie było pisemną odpowiedzią. Problem, agent w chmurze, sekret Agenta i workflow konfiguracji wymagają hostowanego repozytorium i nie uruchomiły się.
Przewodnik po Kursorze ogranicza jego regułę IronWord do wzorców plików z globs, jak plik instrukcji specyficzny dla ścieżki robi tutaj z applyTo. Przewodnik Google Antigravity publikuje stronę IronWord dla linux-x64, platformy, na której działa agent w chmurze.
Wersja Copilot CLI, model, który wybrało Auto, maszyna testowa i czas trwania uruchomienia pojawiają się w wspólnym rekordzie uruchomienia.
Rozwiązywanie problemów
- Dodaj Tabelę do DOCX dla wierszy, komórek, granic i cieniowania.
- Stylizuj Tekst w DOCX dla czcionek, rozmiarów i pogrubionego tekstu.
- Wyodrębnij Tekst z DOCX dla tekstu w akapitach i wyciągania per-komórka z tabel.
- Zastosowanie Kluczy Licencyjnych dla ustawienia klucza z kodu, Web.config lub appsettings.json.
- IronWord w Dockerze dla runnerów i kontenerów Linux.
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.