Como Usar IronZIP com Cursor

Curtis Chau
Curtis Chau
Atualizado: 26 de outubro de 2026

ClientDrop, o serviço .NET 9 neste guia, compacta a pasta de documentos de cada cliente no ZIP que o cliente faz download. Ele constrói esses pacotes com System.IO.Compression, que não tem como definir uma senha, e agora a conformidade exige que cada pacote seja protegido com AES-256. O código do pacote precisa se mover para IronZIP, e uma mudança feita por um agente de IA tem um risco menos visível. IronZIP e System.IO.Compression discordam nos detalhes que ainda são compilados. System.IO.Compression mantém o caminho da pasta de cada arquivo que ele compacta e o Add do IronZIP mantém apenas o nome do arquivo, então duas declarações de meses diferentes podem receber o mesmo nome de entrada.

A porta usa três recursos do Cursor. Uma regra de projeto comprometida nomeia os hábitos de System.IO.Compression a serem abandonados, no Modo de Plano o agente escreve o mapeamento como um plano antes de qualquer alteração de arquivo, e links de documentação nos prompts e a regra apontam o agente para as páginas do IronZIP. Cada pacote ClientDrop é criptografado quando é construído, extraído com essa senha para provar que ainda mantém todos os arquivos, e aberto novamente com sua senha quando os testes contam suas entradas.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronZip

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

Com o ClientDrop aberto no Cursor, cole isso no Agent. Suas duas menções anexam a classe do pacote e a pasta de um cliente.

@src/ClientDrop/Bundles/BundleBuilder.cs @TestData/clients/C-1042/

Fetch https://ironsoftware.com/zip/csharp/llms.txt first and read it before any edit.
BundleBuilder packs a client folder with System.IO.Compression.
Run dotnet test once and report the result.

Then make these changes:
1. Add the IronZIP package, version 2026.10.2, to src/ClientDrop.
2. Give Program.cs an "inspect <zip> [password]" command that opens a bundle with IronZIP.
3. Have inspect print each entry's name, size and whether it is encrypted.
4. Assign License.LicenseKey the value of IRONZIP_LICENSE_KEY.
5. Keep the key out of all output, and don't list the environment variables.
6. Keep BundleBuilder.cs unchanged.

Bundle C-1042 with the current code, run inspect on out/C-1042.zip and show me the output.
Text

O comando de inspecionar lê o pacote antigo e lista sete entradas com seus caminhos de pasta, de contract.pdf na raiz até statements/2026-05/statement.pdf, e nenhuma delas criptografada.

Deixe a chave de licença fora de cada prompt. No modo Agent, o Cursor escreve código e executa comandos de terminal, então uma chave digitada na conversa pode ser copiada para o código ou uma mensagem de commit. Defina a variável de ambiente IRONZIP_LICENSE_KEY em vez disso. O IronZIP não lê essa variável por si só, por isso o prompt faz o código atribuí-la a License.LicenseKey. Num teste que definiu a variável e não fez atribuição, a chamada de salvar lançou uma LicensingException que diz "Licença de Produção Necessária". O guia de chave de licença cobre os lugares onde o IronZIP olha por conta própria, como um arquivo appsettings.json que o Git pode ignorar.



Qual modelo do Cursor você deve usar para trabalho com IronZIP?

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. A execução neste guia usou o Grok 4.7. Qualquer que seja o modelo que você escolher, nomeie os arquivos, os testes e as contagens esperadas no prompt.

Como você fornece a documentação do IronZIP para o Cursor?

O llms.txt do IronZIP é uma única página que lista seus exemplos e tutoriais com um breve resumo de cada um. Em outubro de 2026, o menu @ no Cursor oferece o navegador, diferenças do Git, terminais, bate-papos anteriores, arquivos e pastas, sem entrada para documentação, então o prompt fornece a documentação do IronZIP como um link.

A porta depende de para onde vão os caminhos das pastas e quando o IronZIP verifica uma senha. O próximo prompt pede ao Cursor para responder tanto das páginas quanto para dizer quando nenhuma página cobre um ponto.

@src/ClientDrop/Bundles/BundleBuilder.cs

Your only source is https://ironsoftware.com/zip/csharp/llms.txt plus the example pages it links.
Do not edit files.
List each System.IO.Compression call in BundleBuilder.
Next to each call, name the IronZIP member that would replace it.

Then answer three questions:
1. Does Add keep the folder path of the file it is given?
2. Which call encrypts a new archive with AES-256?
3. For an existing protected archive, is the password checked at the constructor or at extraction?

Cite the page URL behind every answer, and say plainly when no page covers a point.
Text

As páginas respondem à pergunta de criptografia em duas metades. O exemplo de senha chama Encrypt com EncryptionMethods.Traditional, e o exemplo de acesso muda a mesma chamada para AES-256. Nenhuma página diz o que Add faz com um caminho de pasta. Duas páginas enganam. O exemplo de acesso diz que uma senha incorreta faz a operação falhar, o que ocorreu apenas para a extração, e o exemplo de adicionar arquivos abre um ZIP existente com FromFile, que constrói um novo arquivo contendo aquele ZIP como uma única entrada. A referência IronZipArchive documenta membros que nenhuma página de exemplo mostra, como SetPassword e RemoveEncryption.

Por favor, note: O IronZIP também publica um arquivo de habilidade cujo frontmatter o nomeia ironzip. Salvo como .cursor/skills/ironzip/SKILL.md, ele é descoberto quando o Cursor inicia, e digitar /ironzip no Agent o anexa a uma mensagem.

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

Regras de projeto são arquivos .mdc em .cursor/rules, comprometidos com o código, cada um em Markdown com um bloco de frontmatter. O sistema de regras ignora um arquivo .md simples em .cursor/rules, porque tal arquivo não tem frontmatter. Os campos description, globs e alwaysApply decidem quando o Cursor aplica a regra.

Esta regra é escopada com globs, então o Cursor a aplica a qualquer solicitação que tenha um arquivo do serviço ou seus testes no contexto, e @ironzip-bundles a prende por nome. Vários padrões vão em uma linha, separados por vírgulas. Salve como .cursor/rules/ironzip-bundles.mdc.

---
description: Move ClientDrop bundle code from System.IO.Compression to IronZIP
globs: src/ClientDrop/**/*.cs, tests/ClientDrop.Tests/**/*.cs
alwaysApply: false
---

ClientDrop writes bundles with IronZIP and follows these rules:
- Use IronZIP only. Its package ID is IronZIP and its namespace is IronZip.
- Remove System.IO.Compression from src/ClientDrop.
- Do not add SharpZipLib, DotNetZip or another archive package.
- IronZIP's docs start at https://ironsoftware.com/zip/csharp/llms.txt.
- Set License.LicenseKey from IRONZIP_LICENSE_KEY.
- Never write a license key or a bundle password into code, tests or logs.
- Encrypt every bundle with EncryptionMethods.AES256 and BundleOptions.Password.
- Open an existing bundle with new IronZipArchive(path, password).
- FromFile, FromFiles and FromDirectory build a new archive instead.
- Do not invent IronZIP members. For a member no page documents, say so and cite the page searched.
Markdown

A linha FromFile está lá porque abrir um pacote com FromFile não gera erro, e o pacote original permanece inalterado.

A regra afeta apenas solicitações do Agent. De acordo com o FAQ na página de regras do Cursor, conclusões de Tab ignoram regras, e a edição em linha (Ctrl+K) ignora regras do usuário.

Como você mapeia chamadas System.IO.Compression para IronZIP?

Uma regra que apenas diz "use IronZIP" faz o modelo descobrir no que cada chamada se torna. Cada resultado do IronZIP foi medido com IronZIP 2026.10.2 no cliente C-1042, cuja pasta contém sete documentos, três deles chamados statement.pdf e dois chamados invoice.pdf em pastas de meses diferentes.

Chamada System.IO.CompressionEsperadoIronZIP
ZipFile.CreateFromDirectorySete entradas, pastas mantidasFromDirectory, mostrado no arquivo de habilidade, compactou apenas contract.pdf
CreateEntryFromFile para cada arquivoUma entrada por arquivoAdd armazenou sete entradas sob quatro nomes, e a extração deixou quatro arquivos
Delete e CreateEntryFromFile no modo de atualizaçãoO documento reeditado mantém seu nomeReplaceEntry nomeou a nova entrada após o caminho que foi dado a ela, aqui ZipWork/cursor/repo-baseline/TestData/reissue/C-1042/contract.pdf
ZipFile.OpenRead nos testesToda entrada legívelAs entradas AES listadas e a leitura de uma lançou InvalidDataException "método de compressão não suportado"

No pacote com nomes duplicados, ReplaceEntry falhou antes de qualquer renomeação. Lançou ArgumentException "Um item com a mesma chave já foi adicionado" sobre as duas entradas invoice.pdf. A criptografia em si funcionou. Encrypt com EncryptionMethods.AES256 marcou todas as sete entradas como criptografadas, e uma cópia encenada da pasta sob nomes planos únicos, como statements_2026-03_statement.pdf, extraída para sete arquivos que combinavam com os originais por SHA-256. Os nomes duplicados são o problema mais difícil de detectar, porque um pacote que perde uma declaração ainda mantém sete entradas, então uma verificação de contagem passa enquanto o cliente baixa quatro documentos.

Anexe as traduções à regra.

The port translates System.IO.Compression habits this way:
- Add keeps only the file name.
- Copy each file to a staging folder under a name unique in the bundle, and add the copy.
- One such name is statements_2026-03_statement.pdf.
- ReplaceEntry names the new entry after the path it is given.
- To swap a document, Delete the entry and Add a staged copy named like the old entry.
- System.IO.Compression cannot read AES entries. Tests open bundles with IronZIP.
Markdown

Como planejar e executar uma migração para IronZIP?

Gire a entrada do chat para o Modo de Plano com Shift+Tab antes de enviar o próximo prompt. No Modo de Plano, o Agent pode fazer perguntas de esclarecimento enquanto pesquisa o código.

@src/ClientDrop/ @tests/ClientDrop.Tests/ @ironzip-bundles

Plan the move of BundleBuilder from System.IO.Compression to IronZIP.
Every bundle is encrypted with AES-256 using BundleOptions.Password.
Map each System.IO.Compression call to the IronZIP member that replaces it.
For each call, name the file it lives in.
Public method signatures on BundleBuilder stay as they are.
No test is renamed or loses an assertion.
Write no code yet.

In the plan, tell me how each of these works:
- The three files called statement.pdf in different folders all survive.
- The tests read an encrypted bundle.
- Reissue swaps a document without renaming it.
Text

O plano é um arquivo Markdown que você pode editar, então um mapeamento errado pode ser corrigido antes que qualquer coisa seja construída. Quando o plano estiver correto, construa-o no Modo de Plano, ou retorne ao modo Agent com o próximo prompt, que adiciona as verificações.

Build the approved plan with @ironzip-bundles attached.
Remove every System.IO.Compression call from src/ClientDrop.
In the tests, change only BundleReader.
Set CLIENTDROP_BUNDLE_PASSWORD to a throwaway value inside each command you run.

After the build, carry out these steps in sequence:
1. Build and run the tests.
2. Run "bundle C-1042", then run "inspect" on the result with that password.
3. Extract that bundle with IronZIP to an empty folder.

Report how many tests pass now and how many passed at the start.
Also report how many files the client folder and the extracted folder each hold.
Text

Na nossa calibração, uma tradução direta que trocou cada chamada pelo seu membro IronZIP mais próximo compilou sem problemas e passou em quatro dos seis testes. Os dois fracassos foram a verificação de extração e a reemissão. A porta que seguiu a regra passou em todos os seis.

Como retirar um documento de um pacote protegido?

BundleBuilder também precisa de uma maneira de remover um documento de um pacote que um cliente ainda não tenha baixado. Destaque todo o método Reissue em BundleBuilder.cs, pressione Ctrl+Shift+L para adicioná-lo ao chat aberto, e envie a solicitação no modo Agent.

Below the highlighted Reissue, add Withdraw(string bundlePath, string entryName).
It takes one document out of an existing bundle and keeps the rest encrypted.
For a name the bundle lacks, it throws KeyNotFoundException, as Reissue does.
Add a "withdraw <zip> <entry>" command to Program.cs.
Try it on a fresh C-1042 bundle, with CLIENTDROP_BUNDLE_PASSWORD set inside each command.
Show me what each command prints.
Text

A Retirada resultante é uma guarda Contains, então Delete, Encrypt com EncryptionMethods.AES256 e Save, em um arquivo aberto com sua senha. Retirar contract.pdf de C-1042 deixou seis entradas, todas ainda criptografadas. Na nossa calibração, um pacote de dois documentos manteve um, e o construtor então falhou ao abrir o pacote.

Por que um pacote de um documento rejeita sua própria senha?

O construtor IronZipArchive rejeita a senha correta sempre que um arquivo protegido contém exatamente uma entrada. No IronZIP 2026.10.2, ele lançou uma Exception lendo "Senha inválida!" para arquivos de entrada única criptografados com AES-256, AES-128 e criptografia tradicional, e a sobrecarga de matriz de bytes e FromArchive fizeram o mesmo. ExtractArchiveToDirectory com a mesma senha extraiu o arquivo sem erro, e duas ou mais entradas abriram normalmente.

Cliente C-1077 tem um único documento, uma carta de boas-vindas. Mencione a pasta, a carta corrigida e o programa juntos.

@TestData/clients/C-1077/ @TestData/reissue/C-1077/ @src/ClientDrop/Program.cs

Client C-1077 has a single document.
Set the same throwaway CLIENTDROP_BUNDLE_PASSWORD inside each command.

Run these three steps in order:
1. Run bundle C-1077.
2. Run list on out/C-1077.zip.
3. Reissue its welcome-letter.pdf from TestData/reissue/C-1077/.

If any step throws, find the cause and fix it in BundleBuilder.
Don't catch and hide the exception.
If a line of @ironzip-bundles led to it, change that line too.
Then run all three steps again.
Show me the error you hit and the list output after the reissue.
Text

Na nossa calibração, o pacote foi escrito, então a lista e a reemissão falharam, e o próprio comando do pacote também falhou, que lista o novo pacote para imprimir sua contagem de entradas. Ler o pacote extraindo-o em uma pasta temporária e escrevê-lo novamente a partir dessa pasta para uma reemissão ou retirada listou a carta de 2.643 bytes e substituiu a corrigida. Anexe este bloco abaixo das traduções.

One-document bundles follow this rule:
- On a protected one-entry bundle, the IronZipArchive constructor rejects the correct password.
- List, reissue and withdraw such a bundle by extracting it with ExtractArchiveToDirectory.
- Then pack the extracted folder again.
Markdown

Como escrever testes de regressão para os pacotes?

Um Agente na Nuvem pode escrever a suíte de regressão. Ele clona o repositório do seu controle de origem conectado, então envie a porta primeiro, e adicione IRONZIP_LICENSE_KEY como um segredo no painel de Agentes na Nuvem antes de iniciar um.

@tests/ClientDrop.Tests/ @TestData/

Extend BundleBuilderTests for the IronZIP port with tests for these cases:
- The three statement.pdf documents from different C-1042 folders all survive a round trip.
- Those three documents keep distinct entry names.
- Every entry in the C-1042 bundle is encrypted.
- A wrong password fails when the bundle is extracted.
- A one-document bundle can be listed, reissued and extracted.
- Withdraw removes exactly one document.
- Withdraw throws KeyNotFoundException for an unknown name.

Compare extracted files by SHA-256, never archive bytes.
Run dotnet test and report how many tests pass and fail.
Text

O teste de senha errada tem que extrair o pacote. Em um pacote de três entradas, o construtor aceitou uma senha errada sem erro e a contagem de entradas, a lista de entradas e a busca de nomes responderam como se estivesse correta. ExtractArchiveToDirectory foi a primeira chamada a recusá-la, com ArgumentException "Senha inválida!!". Uma porta que lista entradas extraindo, portanto, rejeita uma senha errada na primeira leitura.

O guia de assistentes de codificação de IA do IronZIP executa uma tarefa do IronZIP de ponta a ponta contra critérios de aprovação definidos.

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

Os sete prompts foram enviados para o Cursor em ordem, em um único chat, contra uma cópia do repositório ClientDrop feita para este guia. A cópia continha o BundleBuilder do System.IO.Compression, seis testes xUnit que liam pacotes com System.IO.Compression, e o cliente C-1042. O arquivo de regra e o cliente C-1077 foram adicionados imediatamente antes dos prompts que os usam, e a chave de licença foi definida apenas como uma variável de ambiente. Cada figura abaixo vem de construções e execuções do código comprometido após o término do chat.

  • Todos os 6 testes passaram antes da porta, e os mesmos 6 passaram após ela.
  • O pacote C-1042 portado continha 7 entradas sob nomes planos únicos.
  • O IronZIP extraiu 7 arquivos daquele pacote, o mesmo número que a pasta do cliente continha.
  • pyzipper, um leitor ZIP do Python que não compartilha código com o IronZIP, encontrou criptografia AES-256 em todas as 7 entradas.
  • Todos os 7 arquivos extraídos combinem com os arquivos na pasta do cliente por SHA-256.
  • Perguntado onde o IronZIP verifica uma senha, o Cursor nomeou o construtor e citou o exemplo de acesso.
  • A Retirada lançou KeyNotFoundException para um nome que o pacote não possuía.
  • Antes da correção, os passos de pacote, lista e reemissão para C-1077 lançaram Exception "Senha inválida!" do construtor IronZipArchive.
  • Após a correção, a lista mostrou welcome-letter.pdf com 2.643 bytes, e com 2.761 bytes após a reemissão.
  • A carta reemitida que o pyzipper extraiu correspondeu ao arquivo corrigido por SHA-256.
  • Cada pacote do C-1077 também manteve uma entrada vazia chamada __bundle_keep, que a extração escreveu como um segundo arquivo.
  • No código final, retirar um documento de um pacote de dois documentos deixou uma entrada, e a lista então lançou "Senha inválida!".
  • O prompt de teste adicionou 6 testes, e todos os 12 passaram.
  • IronZIP 2026.10.2 era o único pacote no serviço, e nenhuma chamada do System.IO.Compression permaneceu nele.
  • Cada construção Release após um prompt terminou sem um aviso ou erro.
  • Alguns passos foram executados de forma diferente da página. No Modo de Plano, o Cursor pesquisou pastas fora do repositório por ironzip-bundles antes de abrir o arquivo de regra. Para o C-1077, o Cursor adicionou a entrada __bundle_keep em pacotes de um documento e escreveu isso na regra, em lugar de ler por meio de extração. O prompt de Agente na Nuvem foi enviado localmente no mesmo chat no modo Agent, não como um Agente na Nuvem.

A aprovação do plano antes de qualquer código também ocorre no guia Claude Code, onde o plano reconstruiu cada arquivo de uma cópia extraída e assim lidou com um arquivo de entrada única. O guia GitHub Copilot restringe suas regras TAR ao arquivador de log e seus testes por meio do valor applyTo de um arquivo de instruções específico para o caminho, e os globs restringem esta regra da mesma forma. O registro de execução nomeia a versão do Cursor e o modelo, e fornece o tempo total de prompt e o hardware da máquina de teste.


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 25,383Versão:2026.11recém-lançado