Como usar IronWord com Cursor
O repositório de exemplo para este guia lê formulários de fornecedores com código do OpenXML SDK que percorre elementos do corpo e lê InnerText. Mover esse leitor para IronWord ao analisar cada valor rotulado de um bloco de texto extraído com uma expressão regular falha. Na calibração, essa versão leu 3 de 12 formulários corretamente, juntando cinco números de registro ao rótulo seguinte e não retornando nenhum número de registro para os quatro formulários de tabela.
Cursor é construído na base de código do VS Code e fornece um agente ao lado do editor. Duas de suas funcionalidades, os links de documentação que o agente lê e as regras de projeto comprometidas em .cursor/rules, determinam se ele produz código IronWord ou código que segue o padrão do leitor OpenXML. Ambas as características aparecem abaixo em um serviço de integração de fornecedores que lê os formulários DOCX retornados por fornecedores. O serviço extrai o nome do fornecedor, o número de registro, a tabela de lista de preços e as imagens de logotipo e assinatura incorporadas, e seu leitor se move do OpenXML SDK para IronWord.
Para detalhes sobre os métodos de leitura do IronWord, veja o guia de extração de texto e o guia de extração de imagens.
Início RápidoCom o repositório de entrada de fornecedores aberto, cole este prompt em um novo chat do Agente.
@src/SupplierIntake/ @TestData/forms/
Don't write anything until you've fetched https://ironsoftware.com/word/csharp/llms.txt.
Read the extract text and extract images pages it links as well.
Then give Program.cs a dump command that opens one form with IronWord:
`dotnet run --project src/SupplierIntake -- dump <file.docx>`
Have the dump print what IronWord returns for that form:
- The ExtractText result, in quotes.
- Every entry of Paragraphs, with its index.
- Every table cell, with its table, row and column numbers.
- Each extracted image's Width and Height, and the pixel size of the AnyBitmap behind it.
The program should read IRONWORD_LICENSE_KEY itself when it's set.
At startup, assign the key to License.LicenseKey.
Never print the key, and keep environment variables out of the output.
Leave Forms/FormReader.cs and its DocumentFormat.OpenXml reference as they are.
Run the dump on TestData/forms/form-03.docx and show me the output.
Não insira a chave de licença em um chat. O agente edita arquivos e executa comandos de shell, assim uma chave colada é exposta a todos os arquivos, mensagens de commit e logs de construção que ele escreve. Em nossos testes, IronWord abriu e leu todos os formulários sem uma chave e lançou uma LicensingException apenas ao salvar um documento. O guia de chave de licença mostra como definir a chave no código, no Web.config ou no appsettings.json.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca C# Word do NuGet
- Adicione uma regra de projeto em .cursor/rules que contenha o link de documentação do IronWord
- Documente na regra o que
ExtractTextomite - Referencie o arquivo do leitor e uma pasta de formulários retornados em cada solicitação
- Compare cada valor extraído com uma lista conhecida, depois confirme cada nome de membro na referência de API
Qual modelo Cursor você deve usar para trabalhar com IronWord?
Composer é o modelo agêntico próprio do Cursor. O seletor de modelos também oferece os modelos Grok da SpaceXAI, que o Cursor co-desenvolveu, e modelos da OpenAI, Anthropic, Google e outros laboratórios. O teste executado abaixo usou o Grok 4.7.
Como você fornece a documentação do IronWord para o Cursor?
Inclua o link da documentação do IronWord na solicitação, ou armazene-o em uma regra compartilhada pela equipe toda. O llms.txt do IronWord lista cada guia e a referência de API, e llms-full.txt condensa 46 páginas de documentação em um único arquivo. A partir de outubro de 2026, o menu @ do Cursor anexa arquivos, pastas, terminais, chats, diffs Git e o navegador, portanto, a documentação do IronWord vai para o agente como um link.
O dump de Quickstart mostra dois comportamentos que o guia de extração de texto não declara. Para o formulário-03, ExtractText retornou o texto do parágrafo do corpo concatenado em uma string e omitiu todo o texto nas duas tabelas do formulário.
@src/SupplierIntake/Forms/RegistrationCheck.cs
Answer five questions about IronWord, without editing any files:
1. Does WordDocument.ExtractText include text from table cells?
2. What does it put between paragraphs?
3. Does the Paragraphs collection list the paragraphs inside table cells?
4. What does ExtractImages return, and what element type does the list hold?
5. What unit do the Width and Height of each result use?
Use the documentation at https://ironsoftware.com/word/csharp/llms.txt as your source.
The project rule doesn't count as one.
Check your answers against the form-03 dump from the last turn, where it shows them.
Cite the page each answer comes from.
Where no page states it, say the answer is measured, not documented.
Como você escreve regras de projeto que codificam suas convenções do IronWord?
Uma regra de projeto é um arquivo .mdc armazenado em .cursor/rules e versionado com o repositório, para que cada clone o inclua. Cursor ignora arquivos plain .md nessa pasta porque, sem frontmatter, ele não consegue determinar quando carregá-los.
A regra abaixo define globs e define alwaysApply para false. Cursor a carrega sempre que uma solicitação inclui um leitor de formulários ou um arquivo de teste e omite caso contrário. Salve-a como .cursor/rules/ironword-forms.mdc.
---
description: IronWord conventions for reading supplier forms
globs: src/SupplierIntake/Forms/**/*.cs, tests/**/*.cs
alwaysApply: false
---
Read and write DOCX files with IronWord only, under these package rules:
- The NuGet package is IronWord.
- Its types come from two namespaces, IronWord and IronWord.Models.
- AnyBitmap comes from IronSoftware.Drawing.
- Don't add DocX, NPOI or any other DOCX package.
- Add no new DocumentFormat.OpenXml code.
- The documentation index is https://ironsoftware.com/word/csharp/llms.txt
Keep license keys out of the code, and handle the key this way:
- Read it at run time from an environment variable named IRONWORD_LICENSE_KEY.
- Never print it.
WordDocument.ExtractText leaves out table cells and runs paragraphs together with no separator.
Use the paragraph and table collections instead:
- Read labeled values one paragraph at a time from doc.Paragraphs.
- Read tables through doc.Tables, Rows and Cells.
- doc.Paragraphs also returns the paragraphs inside table cells.
Table.Rows returns ITableRow, and a row's Cells returns ITableCell.
Two casts are needed:
- Cast a row to TableRow before you pass it to a method that takes a TableRow.
- Cast a cell to TableCell before you call ExtractText on it.
Don't invent IronWord members.
When you're unsure of one, say so and name the page you checked.
A página de regras do Cursor afirma que as regras não afetam o Tab e que as regras do usuário não são aplicadas a edições em linha, então sugestões de Tab e edição em linha precisam de uma verificação manual contra a regra.
Como você mapeia chamadas do OpenXML SDK para o IronWord?
Instruir o modelo a usar o IronWord não diz a ele qual chamada IronWord substitui cada chamada do OpenXML SDK. Uma tabela de equivalentes fornece esse mapeamento.
| OpenXML SDK | IronWord |
|---|---|
WordprocessingDocument.Open | O construtor WordDocument, de um caminho, bytes ou um fluxo |
| Parágrafos do corpo e seu texto interno | Paragraphs, com ExtractText em cada um |
| Tabelas do corpo, linhas e células | Tables, Rows e Cells |
| Elementos Blip e fluxos de partes de imagem | ExtractImages, salvos através do AnyBitmap |
Duas linhas se comportam de forma diferente do código SDK que substituiram. A lista de parágrafos contém os parágrafos dentro das células da tabela, bem como os parágrafos do corpo, então o formulário-03 retorna 15 entradas onde o leitor do OpenXML SDK iterou sobre 5 parágrafos do corpo. As células são retornadas como ITableCell, que não tem método de texto, então uma chamada sem o cast falha ao compilar com CS1061.
IronWord não referencia o pacote DocumentFormat.OpenXml, e um projeto que referencia tanto o IronWord 2026.10.4 quanto o DocumentFormat.OpenXml 3.5.1 compila e executa. A migração, portanto, pode prosseguir um leitor de cada vez. A página de conflito do OpenXML cobre compilações do IronWord mais antigas do que 2025.7.13.
Adicionar essas linhas ao final da regra coloca a tabela em cada solicitação que carrega a regra.
Translate OpenXML SDK code instead of porting it, with these equivalents:
- WordprocessingDocument.Open becomes new WordDocument(path).
- Body.Elements<Table>() becomes doc.Tables.
- Counting Blip elements becomes doc.ExtractImages().Count.
Save extracted images with ((AnyBitmap)image.Image).SaveAs(path).
Como você planeja e executa uma migração para IronWord?
Pressione Shift+Tab na entrada do chat até que o Modo de Planejamento seja selecionado, então envie a solicitação abaixo. Cursor escreve seu plano em um arquivo editável.
@src/SupplierIntake/Forms/ @TestData/forms/expected.csv
Plan the move of FormReader to IronWord so the project can drop DocumentFormat.OpenXml.
Write no code until I approve.
FormReader still reads supplier forms with the OpenXML SDK.
RegistrationCheck already uses IronWord, and the team wants a single DOCX library.
The plan has to cover these points:
- Every OpenXML SDK call, with its IronWord replacement and the file where the call lives.
- How the reader will find the price table.
- How it will find a registration number inside a table.
Keep SupplierForm and the public Read and SaveImages signatures unchanged.
Where something is unclear, state your assumption instead of asking.
Show me the plan when it's ready.
Corrija quaisquer erros no plano. Em seguida, clique em Build ou volte para Agent e envie esta solicitação.
@ironword-forms
Carry out the approved plan.
Check the forms output against TestData/forms/expected.csv before and after the move.
A printed row counts as a match when its supplier, registration, items and images columns agree.
Work through it in this order:
1. Run `dotnet run --project src/SupplierIntake -- forms TestData/forms` and count the matches.
2. Migrate FormReader to IronWord.
3. Remove the DocumentFormat.OpenXml package reference.
4. Run dotnet build, then run the forms command again.
Tell me the match count for the OpenXML version and for the IronWord version.
Then show me the diff.
A menção @ironword-forms aplica a regra por nome, independentemente de o Cursor já a ter anexado através de seus globs.
Qual recurso do Cursor se adapta a cada mudança?
Tab completa uma edição que já está visível no editor, e a edição em linha (Ctrl+K) reescreve uma seleção a partir de uma instrução de uma frase. Mudanças em vários arquivos, ou mudanças que precisam de uma compilação, vão para o Agent. Use o Modo de Planejamento quando uma mudança incorreta exigir mais esforço para desfazer do que para escrever um plano. Um Cloud Agent é adequado para trabalho não supervisionado.
Um novo fornecedor retorna o formulário-13, cuja tabela de preços une uma célula de item em dois níveis de preços. Destaque o loop que itera sobre as linhas de preço em FormReader, pressione Ctrl+Shift+L (Cmd+Shift+L no macOS) para adicionar o código destacado à entrada de chat, e envie esta solicitação no Agent.
Make FormReader.Read handle merged cells in the price rows:
- An Item cell that Word merged with the cell above comes back empty.
- For that row, reuse the item name from the previous row.
- Before you read a cell by its column position, check that the row has that many cells.
Then rerun the forms command over TestData/forms.
Tell me how many rows agree with expected.csv, which now lists 13 forms.
O verificador de comprimento de linha aborda fusões na outra direção. Em um arquivo sonda separado, uma célula mesclada entre colunas foi retornada como uma única célula, então essa linha era mais curta que as outras.
Como você depura valores ausentes de texto extraído?
A pré-verificação do repositório lê o número de registro com uma expressão regular sobre o resultado de ExtractText.
@src/SupplierIntake/Forms/RegistrationCheck.cs @TestData/forms/
Find out why the pre-check flags 9 of the 13 forms as missing a registration number.
FormReader finds one in all 13, and every number is visible in Word.
Before you edit anything, do these three things:
1. Run the check command on TestData/forms and on TestData/edge, and note what it flags.
2. Run the dump command on one flagged form.
3. Explain what the check reads that FormReader doesn't.
Then fix RegistrationCheck and keep it on IronWord.
Rerun the check on both folders.
Tell me how many forms it flags in TestData/forms and in TestData/edge, before and after the fix.
As nove falhas têm duas causas. Em cinco formulários, um parágrafo de e-mail de contato segue o número, então a expressão captura GB-0012345Contact, e a verificação de formato o rejeita. Os outros quatro armazenam o número em uma tabela de detalhes da empresa, onde a célula de rótulo lê Número de registro sem dois-pontos e o valor está na célula seguinte. Ler os parágrafos individualmente e pegar o valor da célula ao lado do rótulo resolve ambos os problemas.
Quais partes de um DOCX o IronWord deixa de fora?
Nossas sondas contra o IronWord 2026.10.4 identificaram conteúdo que a biblioteca não retorna para um leitor de formulários.
- Cabeçalhos: nenhuma leitura retorna texto de cabeçalho, e
ExtractImagesomite imagens de cabeçalho. A configuração da página expõe a altura do cabeçalho, mas nenhum de seu conteúdo. - Controles de conteúdo e caixas de texto: seu texto está ausente tanto dos parágrafos quanto do texto extraído.
- Mudanças rastreadas: as leituras deixam de fora texto inserido enquanto o rastreamento estava habilitado.
- Arquivos legados: um arquivo Word 97-2003 .doc lança "Arquivo contém dados corrompidos" ao carregar.
- Imagens inline sem atributos de espaçamento: um DOCX cujas imagens inline omitem distT, distB, distL e distR falha ao carregar com uma InvalidOperationException. python-docx omite esses atributos.
Imagens flutuantes e imagens dentro de células de tabela são extraídas, na ordem do documento. Se os fornecedores completarem formulários construídos com controles de conteúdo, ou colocarem o número de registro em um cabeçalho, teste esses formulários antes de depender do leitor.
Como você escreve testes de regressão para leitura de documentos?
Testes que comparam valores extraídos com uma lista conhecida verificam a saída do serviço de entrada, independentemente da implementação interna do leitor. Um Cloud Agent pode escrevê-los em sua própria VM isolada. Armazene IRONWORD_LICENSE_KEY sob segredos no painel do Cloud Agents primeiro.
@tests/SupplierIntake.Tests/ @TestData/
Write xUnit tests for FormReader and RegistrationCheck.
Each of these needs a test:
- Every row of TestData/forms/expected.csv matches.
- In form-13, both price tiers keep the item name.
- SaveImages writes one PNG per picture, with the pixel sizes listed in the image_sizes column.
- RegistrationCheck passes every form and flags TestData/edge/no-registration.docx.
- Reading TestData/edge/legacy.doc throws a FormatException or a type derived from it.
Copy TestData into the test output and run dotnet test.
Tell me the passed and failed counts.
A afirmação de arquivo legado não pode referenciar o tipo de exceção do IronWord porque é interno. Deriva de FormatException, então uma afirmação que aceita tipos derivados, como Assert.ThrowsAny<FormatException> em xUnit, compila e ainda falha quando um erro diferente é lançado.
O guia de assistentes de codificação de IA inclui uma tarefa IronWord executada do início ao fim contra critérios de aprovação escritos.
O que os prompts produziram em uma execução real?
Os sete prompts foram enviados para Cursor em ordem em um único chat. O repositório de exemplo continha um leitor do OpenXML SDK, uma pré-verificação do IronWord, um projeto xUnit vazio, doze formulários com valores conhecidos, e dois arquivos de borda.
- Tanto o leitor do OpenXML SDK quanto o leitor do IronWord que o substituiu coincidiram com todos os 12 formulários.
- IronWord foi o único pacote DOCX restante no aplicativo e seus testes.
- Com o formulário-13 adicionado, o leitor combinou 12 de 13 e deixou de lado o nome do item do segundo nível de preço.
- Após a mudança de célula mesclada, o leitor combinou 13 de 13.
- A pré-verificação sinalizou 9 dos 13 formulários antes da correção e nenhum depois dela. Sinalizou o formulário de borda sem número de registro ambas as vezes.
- Todas as 21 imagens salvas tinham seus tamanhos de pixel listados.
- O dump do formulário-03 listou 10 células em duas tabelas e uma imagem de 108 por 36 pontos e 144 por 48 pixels.
- Quando perguntado o que a documentação declara, o Cursor respondeu sem alterar nenhum arquivo.
- Todos os 42 casos de seis métodos de teste passaram, com e sem uma chave de licença.
- Em cópias do código final, remover o tratamento de célula mesclada falhou em 2 casos. Restaurar a velha pré-verificação falhou em 9, e pular uma imagem por formulário falhou em 13.
- O teste de arquivo legado aceitou qualquer exceção e passou com o arquivo excluído. Reduzido para FormatException, passou com o arquivo real e falhou sem ele.
- O primeiro leitor IronWord do Cursor faltou o cast de linha e falhou ao compilar com CS1503. O Cursor adicionou o cast antes de sua próxima compilação.
- Cada compilação de Release teve 0 avisos e 0 erros, sem edições manuais.
- Alguns passos foram executados de forma diferente da página. A regra não continha o cast de linha. O prompt de célula mesclada não solicitou uma verificação de comprimento de linha, e o Cursor não adicionou nenhuma. O prompt de teste exigia apenas que uma exceção fosse lançada. Prompts, @ menções incluídas, foram colados no aplicativo de desktop como texto. O plano foi aprovado no Agent, não com o botão Build. O prompt do Cloud Agent foi executado localmente no modo Agent, sem uma VM.
O guia de Claude Code adiciona um subagente de leitura que verifica cada membro do IronWord no código gerado contra o IronWord.xml. O guia de ChatGPT Codex cobre o lado da escrita e mede quais partes de um documento do Word uma substituição de texto altera.
O registro de execução lista o pacote IronWord, modelo, tempo e máquina de teste para esses resultados.
Solução de problemas
- Extrair Texto de DOCX quando um valor dentro de uma tabela está ausente do texto extraído
- Extrair Imagens de DOCX quando imagens salvas precisam de seus tamanhos ou formato verificados
- IronWord com DocumentFormat.OpenXml enquanto ambos os pacotes são referenciados em um projeto durante uma migração
- Usando Chaves de Licença quando o código gerado lança uma exceção de licenciamento ao salvar
Questões?
Se você tiver dúvidas, entre em contato com support@ironsoftware.com
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.