Como Usar IronXL com Cursor

Curtis Chau
Curtis Chau
Atualizado: 15 de outubro de 2026

Um trabalho de orçamento que edita sua planilha através do Excel Interop só funciona onde o Excel está instalado. O BudgetDesk, o serviço .NET 9 neste guia, adianta um orçamento de centro de custo em um PC de finanças que o Agendador de Tarefas desperta no final do mês. A Microsoft não recomenda nem oferece suporte para automação do Office a partir de código não supervisionado, e suas orientações indicam um trabalho no Agendador de Tarefas sob a conta SYSTEM como um desses casos. Mover o trabalho para um agente de build significa substituir o Interop. Passar essa tarefa para um agente de IA adiciona um risco sutil, pois Interop e IronXL discordam em detalhes que ainda compila.

O editor do Cursor é baseado no código do VS Code, e três de seus recursos mantêm uma porta como essa honesta. Uma regra de projeto nomeia os hábitos do Interop e EPPlus a serem descartados, o Modo de Planejamento define o mapeamento antes de quaisquer alterações de arquivo, e links de documentação em cada prompt dão ao agente a API real do IronXL. Cada rolagem do BudgetDesk insere uma linha e uma coluna, edita valores e fórmulas, classifica linhas por variação, copia as linhas superiores para uma segunda folha, e adiciona e remove folhas de meses. IronXL faz tudo isso para arquivos .xlsx em máquinas sem Office.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronXL.Excel

Instale o IronXL executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Com o BudgetDesk aberto no Cursor, cole isso no Agent. Suas duas menções passam a classe Interop e a planilha que essa classe edita.

@src/BudgetDesk/Workbooks/BudgetBook.cs @TestData/budget-2026.xlsx

BudgetBook drives Excel over COM. I want to see what IronXL makes of the same workbook.
Fetch https://ironsoftware.com/excel/csharp/llms.txt before you write anything.

1. Run dotnet test once and tell me what the failures have in common.
2. Add IronXL.Excel 2026.10.1 to src/BudgetDesk.
3. Add an "inspect <file>" command to Program.cs that loads the workbook with IronXL.
4. Have it print the sheet names in tab order first.
5. Then have it print every Lines cell that holds a formula, with its address, formula text and value.
6. Run inspect on TestData/budget-2026.xlsx and show me the output.

The program takes the key from IRONXL_LICENSE_KEY and assigns it to License.LicenseKey.
Don't print the key's value or list any environment variables.
Leave BudgetBook.cs as it is for now.
Text

Em uma máquina sem Excel, cinco dos seis testes param no new Excel.Application() com COMException 0x80040154, classe não registrada. O sexto passa porque a exportação Watchlist usa EPPlus 4.5.3.3. Na mesma máquina, o comando inspect lista 15 folhas, que são Sumário, Linhas e Modelo seguidas de doze folhas mensais de Out-2025 a Set-2026. As fórmulas das Linhas que ele imprime são uma Variação de E2-D2 a E9-D9 nas linhas 2 a 9 mais três totais SUM na linha 10.

Deixe a chave de licença fora de cada prompt. O agente do Cursor edita arquivos e executa comandos de shell, então uma chave digitada na conversa pode terminar no código ou em uma mensagem de commit. Defina a variável de ambiente IRONXL_LICENSE_KEY em vez disso. IronXL não lê essa variável por si só, e é por isso que o prompt faz o código atribuí-la a License.LicenseKey. O guia de chave de licença cobre a exceção que uma chave ausente lança e os arquivos de configuração que IronXL lê por conta própria.



Qual modelo de Cursor você deve usar para trabalhar com IronXL?

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.

Planejar uma porta significa ler cada chamada Interop e cada teste e decidir o que cada um se torna, o que recompensa um modelo que raciocina por mais tempo. Construí-la é principalmente edições mecânicas e rerun de testes, onde um modelo rápido mantém cada loop curto. Qualquer que você escolha, nomeie os arquivos, os testes e os números esperados no prompt, porque dois modelos podem ler uma solicitação de forma diferente.

Como você fornece a documentação do IronXL ao Cursor?

Coloque o link da documentação do IronXL na solicitação, ou mantenha-o em uma regra comprometida para que ninguém tenha que colá-lo. O índice llms.txt liga os guias e exemplos. Em outubro de 2026, o menu @ do Cursor anexa arquivos, pastas, terminais, conversas, diferenças do Git e o navegador, então a documentação do IronXL chega ao agente como um link.

Uma porta baseia-se em duas perguntas. Quais argumentos do IronXL contam a partir de zero, e o que aconteceu com o comportamento que Interop forneceu sem ser solicitado?

@src/BudgetDesk/Workbooks/BudgetBook.cs

These are questions, so don't change any files.
Answer from https://ironsoftware.com/excel/csharp/llms.txt and the how-to pages it links.
Cite the page URL for every answer.

1. List each Interop call in BudgetBook in one column and the IronXL member that replaces it in a second.
2. Mark every IronXL argument that counts rows, columns or sheets from 0.
3. Which IronXL method replaces Sort with Header set to xlYes?
4. Does any page describe a header option for that method?
Text

As páginas do IronXL respondem à pergunta do índice diretamente. O guia de linhas e colunas descreve o argumento InsertRow como um índice baseado em zero, e o guia de planilhas diz que toda posição que menciona é baseada em zero. Nem o guia de ordenação nem a referência da API para SortByColumn mencionam uma linha de cabeçalho.

Dicas: Trate uma resposta sem uma página por trás como não verificada até encontrar o membro na referência de API.
Por favor, note: IronXL também publica um arquivo de habilidades cujo frontmatter o nomeia ironxl. Salvo como .cursor/skills/ironxl/SKILL.md, ele é descoberto quando o Cursor inicia, e ao digitar /ironxl no Agente o anexa a uma mensagem.

Como você escreve regras de projeto que codificam suas convenções do IronXL?

Regras de projeto são arquivos .mdc em .cursor/rules. Elas são comprometidas com o código, então cada clone obtém as mesmas regras. Um arquivo .md simples naquela pasta é ignorado, porque não tem frontmatter para dizer quando se aplica. Os campos description, globs e alwaysApply decidem quando a regra se une a uma solicitação.

Esta regra define globs e deixa alwaysApply desligado, então ela se anexa sempre que o serviço ou seus testes estão no contexto e permanece fora de solicitações que nunca tocam uma planilha. O @ironxl-port anexa-o pelo nome. Vários padrões vão em uma linha, separados por vírgulas. Salve como .cursor/rules/ironxl-port.mdc.

---
description: Port Excel Interop and EPPlus workbook code in BudgetDesk to IronXL
globs: src/BudgetDesk/**/*.cs, tests/BudgetDesk.Tests/**/*.cs
alwaysApply: false
---

# BudgetDesk edits workbooks with IronXL

- Use IronXL only. The NuGet package is IronXL.Excel and the namespace is IronXL.
  Remove Microsoft.Office.Interop.Excel and EPPlus.
  Don't add ClosedXML, NPOI or another spreadsheet package.
- Documentation: https://ironsoftware.com/excel/csharp/llms.txt
- Delete the COM cleanup along with the Interop calls.
  IronXL code has no Marshal.ReleaseComObject, Application.Quit, GC.Collect or DisplayAlerts.
- Set License.LicenseKey from the IRONXL_LICENSE_KEY environment variable.
  Never write a key into code, tests or logs.
- A1 addresses such as "D10" mean the same in both libraries.
  IronXL index arguments start at 0, where Interop and EPPlus Cells[row, col] start at 1.
  Zero-based: InsertRow, InsertColumn, GetRow, GetColumn, GetCellAt, SetActiveTab, RemoveWorkSheet.
- Write dates as a DateTime plus a FormatString.
  IronXL stores a string that reads as a date, such as Oct-2026, as a date.
- Call EvaluateAll before SaveAs.
- Don't invent IronXL members. When unsure, say so and cite the page.
Markdown

O marcador de índice está lá porque uma linha menos escreve a nova linha abaixo da linha de Total.

As regras se aplicam a solicitações de Agente. De acordo com a documentação do Cursor, elas não afetam o Tab, e regras de usuário não se aplicam a edições inline. Verifique sugestões desses recursos contra a regra você mesmo.

Como você mapeia chamadas de Excel Interop e EPPlus para IronXL?

Uma regra que apenas diz "use IronXL" faz com que o modelo trabalhe para descobrir o que cada chamada se torna. Cada resultado IronXL foi medido com IronXL 2026.10.1 na planilha BudgetDesk, cuja folha Linhas mantém oito centros de custo nas linhas 2 a 9 acima de uma linha de Total na linha 10.

Chamada Interop ou EPPlusEsperadoIronXL
Rows[10].Insert(), Cells[row, col]Contando a partir de 1InsertRow(9) insere acima da linha 10, GetCellAt(0, 0) é A1. Total movido para linha 11, SUM(D2:D9) inalterado, Summary!B2 tornou-se Lines!D11
Range.Copy da linha acimaFórmula segue a nova linhaF10 manteve E9-D9
EPPlus Copy de A1:F4 para Watchlist A3Fórmulas seguem linhas do WatchlistWatchlist F4 recebeu E2-D2 e leu 0
Range["F2:F9"].Formula = "=E2/Summary!$B$5*12"Uma fórmula por linhaTodos os oito células receberam a fórmula F2 e leram 128.666,67
Sort com Header definido para xlYes sobre A1:F9Cabeçalho permanece, linhas classificadas por VariaçãoNenhuma opção de cabeçalho. Números classificados como texto e 11.200 veio em quarto
A mesma ordenação sobre A2:F9Fórmulas movem-se com suas linhasOrdem correta, fórmulas tornaram-se números. E2 definido para 0 deixou F2 em 11.200
FindSheet loop sobre WorksheetsUm mês ausente é puladoGetWorkSheet retorna null, RemoveWorkSheet lançou ArgumentException "Índice -1 está fora do alcance"
Template.Copy(After: lastSheet)Nova folha pousa por últimoCopySheet colocou-o 16º de 16, um nome duplicado gerou ArgumentException

A própria inserção interrompeu-se. InsertColumn(5) moveu Variação para a coluna G, reescreveu seu total como SUM(G2:G9), e moveu Summary!B4 para Lines!G10. Duas linhas da tabela fazem mais danos do que o resto, porque mudam o significado de uma célula. Uma fórmula copiada com suas referências antigas relata os números de outro centro de custo. Uma ordenação que transforma fórmulas em números deixa uma coluna de Variação que para de seguir o Atual, então os atuais do próximo mês nunca chegam a ela. Ambos sobrevivem a um olhar nos totais. SortAscending também não é um atalho, já que em um bloco de colunas ele classifica cada coluna por si só, e em nosso teste a linha 2 voltou como CC-110 em Instalações, pertencente a Berg.

Adicione as traduções à regra como mais três pontos.

- Range.Copy keeps formula references unchanged.
  After copying cells that hold formulas, write each formula again for the row it landed on.
- Setting Formula on a multi-cell Range puts the same text in every cell.
  Write per-row formulas in a loop.
- SortByColumn has no header option and leaves values where the sorted formulas were.
  Sort from row 2 down, then write each row's formulas again.
Markdown

Por que GetCellAt retorna null em IronXL?

A regra lista GetCellAt entre os membros baseados em zero, o que convida a uma porta linha por linha de Cells[row, col]. Interop retorna uma Range para qualquer endereço, preenchido ou não, então AddLine escreve o novo centro de custo na linha que inseriu. O GetCellAt do IronXL retorna null "se a célula não estiver preenchida", conforme consta na referência da API. Após InsertRow(9), todas as seis posições na nova linha 10 voltaram null, e GetCellAt(9, 0).Value = "CC-190" lançou NullReferenceException.

Não preenchido aqui significa ausente do XML da planilha. No workbook enviado, B10 e C10 não têm valor, mas carregam um estilo na linha de Total, e GetCellAt retornou-as como células vazias. G2, uma coluna após Variação, e A11, uma linha abaixo de Total, eram null.

Indexar por endereço sempre retorna uma célula. ws["A10"] levou CC-190 na nova linha, e GetCellAt(9, 0) encontrou-a depois. Uma porta que mantém índices numéricos pode voltar ao endereço quando GetCellAt não encontra nada.

static Cell At(WorkSheet sheet, int row, int column) =>
    sheet.GetCellAt(row, column) ?? sheet[$"{(char)('A' + column)}{row + 1}"].First();
C#

Como você planeja e executa uma migração para IronXL?

Uma porta toca todos os métodos, e desfazer um errado custa mais do que escrevê-lo. Troque o chat para o Modo de Planejamento com Shift+Tab antes de enviar o próximo prompt. No Modo de Planejamento o Agent lê o código, pode fazer perguntas de esclarecimento, e escreve um plano no lugar de edições.

@src/BudgetDesk/ @tests/BudgetDesk.Tests/ @ironxl-port

Plan the move to IronXL. Don't write code yet.

Here's the scope:
- BudgetBook moves off Excel Interop.
- WatchlistExport moves off EPPlus.
- The tests stop reading workbooks with EPPlus.
- BudgetBook keeps its public methods, and the six tests keep their names.

Put this in the plan:
1. List each Interop or EPPlus call with its IronXL replacement and the file it's in.
2. Flag every place where a row, column or sheet number changes base.
3. Explain how copied cells, the Forecast column and the sort keep each formula pointing at its own row.
Text

O plano é um arquivo Markdown que você pode editar, então um mapeamento errado pode ser corrigido no próprio plano. Quando o plano estiver certo, clique em Build, ou troque de volta para Agent e envie o próximo prompt.

@ironxl-port

Build the approved plan.

- Remove the Interop and EPPlus package references and the EmbedExcelInteropTypes target.
- In the tests, change only how workbooks are opened and read.
- Leave every assertion in BudgetBookTests as it is.
- If IronXL can't read what an assertion checks, read the saved file's XML and keep the assertion.

When the port is done:
1. Build the solution and run the tests.
2. Run "dotnet run --project src/BudgetDesk -- roll Oct-2026".
3. Print each Lines row of out/budget-Oct-2026.xlsx with its formulas.
4. Tell me how many tests passed before the port and how many pass now.
Text

Em nossa calibração, uma tradução direta que trocou cada chamada por seu membro IronXL mais próximo compilou sem erros e passou em dois dos seis testes. Os quatro fracassos foram as fórmulas de Previsão, a ordenação, a cópia do Watchlist, e a Variação da nova linha, as mesmas linhas da tabela acima. A porta que seguiu a regra passou em todos os seis.

Qual recurso do Cursor se adapta a cada mudança?

Escolha um de acordo com a abrangência da mudança. O Tab lida com uma edição previsível a seguir, e a edição inline lida com uma seleção que uma frase cobre. O Agent assume uma mudança que precisa de vários arquivos ou um loop de construção.

Finanças começou a fechar centros de custo, então o BudgetBook precisa de uma maneira de remover uma linha. Destaque o método inteiro AddLine em BudgetBook.cs, pressione Ctrl+Shift+L para adicioná-lo ao chat aberto e envie a solicitação no modo Agent.

Add RemoveLine(string code) directly below the AddLine method I highlighted.
It finds a line by its code and deletes that row from Lines.
If the code isn't there, throw KeyNotFoundException, the same way SetActual does.
Text

Como o IronXL atualiza os totais quando uma linha é removida?

RemoveLine sai como algumas linhas em torno de GetRow(index).RemoveRow(), e para uma linha no meio da planilha IronXL mantém os totais corretos. Removendo CC-130 da linha 4 moveu as linhas abaixo dela uma linha para cima, reduziu o SUM(D2:D9) do Total para SUM(D2:D8), e moveu Summary!B2 para Lines!D9.

A última linha é a exceção. Removendo a linha 9, a linha diretamente acima de Total, moveu Total para a linha 9 enquanto sua fórmula permaneceu SUM(D2:D9), um intervalo que agora inclui a célula Total em si. IronXL avaliou como REFCIRCULAR~.

O fechamento de novembro neste guia fecha CC-140, a linha que a ordenação de outubro colocou diretamente acima de Total.

@TestData/closures/Nov-2026.csv @TestData/actuals/Nov-2026.csv @src/BudgetDesk/Program.cs

Finance closed CC-140 at the end of November.

Change roll so it calls RemoveLine for each code in TestData/closures/<month>.csv.
Have roll do that before it applies new lines and actuals.
A month with no closures file closes nothing.

Then check the numbers:
1. Run roll Oct-2026.
2. Run roll Nov-2026 with out/budget-Oct-2026.xlsx as its input.
3. Add up Budget, Actual and Variance from the remaining line cells yourself.
4. Compare your sums with the Lines Total row and Summary B2:B4.
5. If they disagree, find the cause in BudgetBook, fix it and roll November again.

Show me the Total row formulas either way.
Text

Com apenas RemoveRow, a saída de novembro em nossa calibração manteve =SUM(D2:D10) na linha 10, três células de Sumário lendo REFCIRCULAR~, e uma rolagem que relatou um orçamento de 0. Reescrever as quatro fórmulas de Total novamente após a remoção produziu um orçamento de 477.750, gasto real de 606.600, e uma variação de 128.850, que correspondem às somas das oito linhas restantes. Dê à regra seu próximo ponto.

- After RemoveRow, write the Total row's SUM formulas again.
  Removing the line directly above Total leaves a range that includes the Total cell itself.
Markdown

Como você testa o código IronXL migrado?

Um Agente na Nuvem pode escrever o conjunto de regressão sem ninguém assistindo. Adicione IRONXL_LICENSE_KEY como um segredo no painel de Agentes na Nuvem antes de iniciar um.

@tests/BudgetDesk.Tests/ @TestData/

Add five xUnit tests to BudgetDesk.Tests that pin down the port.
Write each one as a new test, even where an existing test already covers part of it.

1. Sorting keeps the header in row 1 and a formula in every Variance cell.
2. A line added above Total gets formulas that use its own row.
3. Removing the line just above Total leaves SUM formulas that end one row higher.
4. After the October roll, Oct-2026 is the active sheet.
5. The totals stored in the saved file equal the recalculated ones.

IronXL recalculates on load and has no getter for the active tab.
Read the stored totals and the active tab by unzipping the xlsx and parsing its XML.

Run dotnet test when they're written and tell me how many pass.
Text

A instrução para descompactar o arquivo segue de como IronXL salva. O SaveAs escreve o resultado que cada fórmula computou pela última vez. Na nossa medição, elevar o real de CC-110 para 104.900 e salvar sem EvaluateAll deixou 527.300 no arquivo como o total real armazenado de Linhas e em Sumário, enquanto as células totalizavam 535.700. Carregar esse arquivo de volta com IronXL relatou 535.700, porque IronXL computa fórmulas enquanto as lê. Um teste que lê com IronXL, portanto, passa em um arquivo cujos números armazenados estão desatualizados, enquanto o openpyxl, que lê os resultados armazenados, mostrou 527.300. Ler um total antes de salvar atualizou apenas essa célula, e chamar EvaluateAll antes de salvar atualizou cada uma, o que é por isso que a regra pede isso.

IronXL também não pode informar ao conjunto qual folha está ativa, já que SetActiveTab escreve o valor e nenhuma propriedade o lê de volta. Após SetActiveTab(14), um salvamento e um recarregamento, DefaultWorkSheet ainda retornou Sumário, então o teste de outubro pega o atributo activeTab do XML da planilha.

O IronXL precisa do Windows após uma migração do Interop?

Não, uma vez que a porta está completa. A build Interop de BudgetDesk gerou três avisos CA1416, um para cada chamada Marshal.ReleaseComObject, cada um dizendo que a chamada é suportada apenas no Windows. O guia do IronXL para Linux diz que não são necessárias mudanças de código para executar IronXL no Linux, e o guia Docker cobre contêineres. A calibração para este guia foi executada no Windows, então execute os testes uma vez na imagem do Linux que você implanta antes que o PC da mesa seja aposentado.

O que os prompts produziram em uma execução real?

Os sete prompts foram enviados ao Cursor em ordem, em um chat, contra uma cópia do repositório BudgetDesk feita para este guia. A cópia contém o BudgetBook Interop, a exportação Watchlist EPPlus, seis testes xUnit que leem resultados com EPPlus e o workbook de orçamento com os atuais de outubro e uma nova linha. O arquivo de regras e os arquivos de fechamento de novembro foram adicionados logo antes dos prompts que os usam, e a chave de licença foi configurada apenas como uma variável de ambiente.

  • O conjunto passou 1 dos 6 testes antes da porta e todos os 6 depois dela, com todas as 31 linhas de asserção originais ainda no lugar.
  • Após a porta, a build Release não teve avisos, e IronXL.Excel 2026.10.1 foi o único pacote de planilha restante no aplicativo e seus testes.
  • Antes da correção de novembro, a rolagem parou com uma FormatException ao ler REFCIRCULAR~ da célula de orçamento do Sumário. Uma vez que as fórmulas de Total foram escritas novamente, os totais de novembro armazenados igualaram as figuras de calibração corrigidas, e nenhuma referência circular foi deixada no arquivo.
  • A rolagem de outubro salvou um orçamento de 511.500, gasto real de 590.950 e uma variação de 79.450. Todos os 19 verificações do nosso workbook passaram. Eles cobriam o cabeçalho na linha 1, nove linhas classificadas por variação, uma fórmula por linha em Previsão e Variação, Out-2026 como a folha ativa, e uma Lista de Observação de CC-120, CC-130 e CC-110 cujas fórmulas usam suas próprias linhas.
  • O plano aprovado mapeou a folha ativa para DefaultWorkSheet. A primeira execução de teste após a porta capturou isso, e o Cursor fez os testes lerem a aba ativa do XML do workbook salvo em vez disso.
  • Cinco novos testes trouxeram o conjunto para 11 de 11. Nossa execução de mutação eliminou um comportamento de cada vez das cópias do código final. Os cinco foram a reescrita de Total, as reescritas de fórmula após a ordenação e na nova linha, a avaliação antes de salvar e a chamada de aba ativa. Cada cópia falhou no teste escrito para ela.
  • Cada build Release teve 0 erros e não precisou de edições manuais.
  • Alguns passos foram executados de forma diferente da página. Os prompts foram enviados manualmente no aplicativo de desktop, e as menções @ foram coladas como texto. O plano foi aprovado enviando o próximo prompt, com Build nunca clicado, e o prompt do Agente na Nuvem foi executado localmente no modo Agente, então nenhum segredo do painel foi configurado. Esta foi a segunda tentativa, porque o prompt de fechamento de novembro nunca chegou ao chat na primeira.

Para o pacote IronXL, versão do Cursor, tempo e máquina de teste por trás desses números, veja o registro de execução.


Solução de problemas


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.

Leia Mais

Pronto para começar?

Downloads no NuGet 2,393,101Versão:2026.11recém-lançado