¿Cómo usar IronZIP con Cursor?

Curtis Chau
Curtis Chau
Actualizado: 26 de octubre de 2026

ClientDrop, el servicio .NET 9 en esta guía, empaqueta la carpeta de documentos de cada cliente en el ZIP que el cliente descarga. Construye esos paquetes con System.IO.Compression, que no tiene forma de establecer una contraseña, y ahora se requiere que cada paquete esté protegido con AES-256. El código del paquete debe mudarse a IronZIP, y un movimiento hecho por un agente de IA tiene un riesgo menos visible. IronZIP y System.IO.Compression discrepan en detalles que aún se compilan. System.IO.Compression mantiene la ruta de la carpeta de cada archivo que empaqueta y IronZIP's Add conserva solo el nombre del archivo, por lo que dos declaraciones de diferentes meses pueden recibir el mismo nombre de entrada.

El puerto utiliza tres funciones de Cursor. Una regla de proyecto comprometida menciona los hábitos de System.IO.Compression para eliminar, en Plan Mode el agente escribe el mapeo como un plan antes de cualquier cambio de archivo, y los enlaces de documentación en las sugerencias y la regla dirigen al agente a las páginas de IronZIP. Cada paquete de ClientDrop está encriptado cuando se construye, extraído con esa contraseña para probar que todavía contiene cada archivo, y abierto nuevamente con su contraseña cuando las pruebas cuentan sus entradas.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronZip

Instale IronZIP ejecutando el comando arriba en la Consola del Administrador de Paquetes NuGet, o busque el paquete en el Administrador de Paquetes NuGet.

Con ClientDrop abierto en Cursor, pega esto en Agent. Sus dos menciones adjuntan la clase de paquete y la carpeta de un 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

El comando inspect lee el antiguo paquete y lista siete entradas con sus rutas de carpeta, desde contract.pdf en la raíz hasta statements/2026-05/statement.pdf, y ninguno de ellos encriptado.

Deja la clave de licencia fuera de cada solicitud. En modo Agent, Cursor escribe código y ejecuta comandos de terminal, por lo que una tecla escrita en la conversación se puede copiar en el código o en un mensaje de commit. Establezca en su lugar la variable de entorno IRONZIP_LICENSE_KEY. IronZIP no lee esa variable por sí mismo, razón por la cual el aviso asigna el código a License.LicenseKey. En una sonda que estableció la variable y no hizo ninguna asignación, la llamada save lanzó una LicensingException que dice "Production License Required". La guía de claves de licencia cubre los lugares donde IronZIP busca por su cuenta, como un archivo appsettings.json que Git puede ignorar.



¿Qué modelo de Cursor debería usar para el trabajo con IronZIP?

Composer es el modelo agente propio de Cursor. El selector de modelos también ofrece los modelos Grok de SpaceXAI, que Cursor co-desarrolló, y modelos de OpenAI, Anthropic, Google y otros laboratorios. La ejecución en esta guía utilizó Grok 4.7. Cualquiera que sea el modelo que elija, nombre los archivos, las pruebas y los conteos esperados en el aviso.

¿Cómo le das la documentación de IronZIP a Cursor?

El llms.txt de IronZIP es una sola página que lista sus ejemplos y tutoriales con un breve resumen de cada uno. En octubre de 2026, el menú @ en Cursor ofrece el navegador, diferencias de Git, terminales, chats anteriores, archivos y carpetas, sin entrada para documentación, por lo que el aviso proporciona la documentación de IronZIP como un enlace.

El puerto depende de dónde van las rutas de carpeta y cuándo IronZIP verifica una contraseña. El siguiente aviso pide a Cursor que responda ambas cosas desde las páginas y que diga cuándo ninguna página cubre un punto.

@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

Las páginas responden la pregunta de encriptación en dos mitades. El ejemplo de contraseña llama a Encrypt con EncryptionMethods.Traditional, y el ejemplo de acceso cambia la misma llamada a AES-256. Ninguna página dice qué hace Add con una ruta de carpeta. Dos páginas conducen a error. El ejemplo de acceso dice que una contraseña incorrecta hace que la operación falle, lo cual fue solo cierto para la extracción, y el ejemplo de agregar archivos abre un ZIP existente con FromFile, que construye un nuevo archivo que contiene ese ZIP como una sola entrada. La referencia de IronZipArchive documenta miembros que ninguna página de ejemplo muestra, como SetPassword y RemoveEncryption.

Por favor, tenga en cuenta: IronZIP también publica un archivo de habilidad cuyo frontmatter lo nombra ironzip. Guardado como .cursor/skills/ironzip/SKILL.md, se descubre cuando Cursor se inicia, y al escribir /ironzip en Agente se adjunta a un mensaje.

¿Cómo escribes reglas de proyecto que codifican tus convenciones de IronZIP?

Las reglas del proyecto son archivos .mdc bajo .cursor/rules, comprometidos con el código, cada uno con Markdown y un bloque de frontmatter. El sistema de reglas salta un archivo .md simple bajo .cursor/rules, porque dicho archivo no tiene frontmatter. Los campos description, globs y alwaysApply deciden cuándo Cursor aplica la regla.

Esta regla está delimitada con globs, por lo que Cursor la aplica a cualquier solicitud que tenga un archivo del servicio o sus pruebas en contexto, y @ironzip-bundles la adjunta por nombre. Varios patrones van en una línea, separados por comas. Guárdelo 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

La línea FromFile está allí porque abrir un paquete con FromFile no genera error, y el paquete original permanece sin cambios.

La regla afecta solo las solicitudes de Agent. Según las preguntas frecuentes en la página de reglas de Cursor, Tab completions ignora reglas, y la edición en línea (Ctrl+K) ignora las reglas del usuario.

¿Cómo mapeas llamadas de System.IO.Compression a IronZIP?

Una regla que solo dice "use IronZIP" hace que el modelo determine en qué se convierte cada llamada. Cada resultado de IronZIP fue medido con IronZIP 2026.10.2 en el cliente C-1042, cuya carpeta contiene siete documentos, tres de ellos llamados statement.pdf y dos llamados invoice.pdf en diferentes carpetas de mes.

Llamada de System.IO.CompressionEsperadoIronZIP
ZipFile.CreateFromDirectorySiete entradas, carpetas conservadasFromDirectory, mostrado en el archivo de habilidad, empacó solo contract.pdf
CreateEntryFromFile para cada archivoUna entrada por archivoAdd almacenó siete entradas bajo cuatro nombres, y la extracción dejó cuatro archivos
Delete y CreateEntryFromFile en modo actualizaciónEl documento reemitido mantiene su nombreReplaceEntry nombró la nueva entrada según la ruta que se le dio, aquí ZipWork/cursor/repo-baseline/TestData/reissue/C-1042/contract.pdf
ZipFile.OpenRead en las pruebasCada entrada legibleLas entradas AES listadas, y al leer una lanzó InvalidDataException "unsupported compression method"

En el paquete con nombres duplicados, ReplaceEntry falló antes de cualquier renombrado. Lanzó ArgumentException "An item with the same key has already been added" sobre las dos entradas de invoice.pdf. La encriptación en sí misma funcionó. Encrypt con EncryptionMethods.AES256 marcó las siete entradas como encriptadas, y una copia puesta en escena de la carpeta bajo nombres planos únicos, como statements_2026-03_statement.pdf, se extrajo a siete archivos que coincidieron con los originales por SHA-256. Los nombres duplicados son el problema más difícil de detectar, porque un paquete que pierde una declaración aún contiene siete entradas, por lo que una verificación de conteo pasa mientras el cliente descarga cuatro documentos.

Agregue las traducciones a la regla.

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

¿Cómo planificas y ejecutas una migración a IronZIP?

Gira la entrada de chat a Plan Mode con Shift+Tab antes de enviar la siguiente sugerencia. En Plan Mode, Agent puede hacer preguntas aclaratorias mientras investiga el 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

El plan es un archivo Markdown que puede editar, por lo que un mapeo incorrecto se puede corregir antes de que se construya nada. Cuando el plan es correcto, constrúyalo desde Plan Mode, o regrese a modo Agent con la siguiente sugerencia, que agrega las verificaciones.

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

En nuestra calibración, una traducción directa que intercambió cada llamada por su miembro de IronZIP más cercano se compiló sin problemas y pasó cuatro de las seis pruebas. Las dos fallas fueron la verificación de extracción y la reemisión. El puerto que siguió la regla pasó las seis.

¿Cómo sacas un documento de un paquete protegido?

BundleBuilder también necesita una manera de eliminar un documento de un paquete que un cliente aún no ha descargado. Resalte todo el método Reissue en BundleBuilder.cs, presione Ctrl+Shift+L para agregarlo al chat abierto, y envíe la solicitud en 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

El Withdraw resultante es un guardia Contains, luego Delete, Encrypt con EncryptionMethods.AES256 y Save, en un archivo abierto con su contraseña. Retirar contract.pdf de C-1042 dejó seis entradas, todas aún encriptadas. En nuestra calibración un paquete de dos documentos conservó uno, y luego el constructor no pudo abrir el paquete.

¿Por qué un paquete de un solo documento rechaza su propia contraseña?

El constructor IronZipArchive rechaza la contraseña correcta cada vez que un archivo protegido contiene exactamente una entrada. En IronZIP 2026.10.2 lanzó una Exception diciendo "Invalid Password!" para archivos de una sola entrada encriptados con AES-256, AES-128 y encriptación tradicional, y la sobrecarga de matriz de bytes y FromArchive hicieron lo mismo. ExtractArchiveToDirectory con la misma contraseña extrajo el archivo sin error, y dos entradas o más se abrieron normalmente.

El cliente C-1077 tiene un solo documento, una carta de bienvenida. Mencione su carpeta, la carta corregida y el 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

En nuestra calibración el paquete se escribió, luego falló la lista y la reemisión, y también lo hizo el comando del paquete, que lista el nuevo paquete para imprimir su conteo de entradas. Leer el paquete extrayéndolo en una carpeta temporal, y escribirlo nuevamente desde esa carpeta para una reemisión o retiro, listó la carta de 2,643 bytes e intercambió por la corregida. Agregue este bloque debajo de las traducciones.

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

¿Cómo escribes pruebas de regresión para los paquetes?

Un Cloud Agent puede escribir la suite de regresión. Clona el repositorio desde tu control de origen conectado, así que implementa el puerto primero, y agrega IRONZIP_LICENSE_KEY como un secreto en el dashboard de Cloud Agents antes de iniciar uno.

@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

La prueba de contraseña incorrecta tiene que extraer el paquete. En un paquete de tres entradas, el constructor tomó una contraseña incorrecta sin error, y el conteo de entradas, la lista de entradas y la búsqueda de nombres respondieron como si fuera correcta. ExtractArchiveToDirectory fue la primera llamada en negarse, con ArgumentException "Invalid password!!". Un puerto que lista entradas extrayendo por lo tanto rechaza una contraseña incorrecta en la primera lectura.

La guía de asistentes de codificación AI de IronZIP ejecuta una tarea de IronZIP de principio a fin contra criterios de aprobación definidos.

¿Qué produjeron los prompts en una ejecución real?

Las siete sugerencias se enviaron a Cursor en orden, en un chat, contra una copia del repositorio ClientDrop hecha para esta guía. La copia contenía el BundleBuilder de System.IO.Compression, seis pruebas xUnit que leían paquetes con System.IO.Compression, y el cliente C-1042. El archivo de reglas y el cliente C-1077 se agregaron inmediatamente antes de las sugerencias que los utilizan, y la clave de licencia se estableció solo como una variable de entorno. Cada figura a continuación proviene de construcciones y ejecuciones del código comprometido después de que terminó el chat.

  • Todas las 6 pruebas pasaron antes del puerto, y las mismas 6 pasaron después.
  • El paquete transferido C-1042 contenía 7 entradas bajo nombres planos únicos.
  • IronZIP extrajo 7 archivos de ese paquete, el mismo número que contenía la carpeta del cliente.
  • pyzipper, un lector de ZIP en Python que no comparte código con IronZIP, encontró encriptación AES-256 en las 7 entradas.
  • Todos los 7 archivos extraídos coincidían con los archivos en la carpeta del cliente por SHA-256.
  • Preguntado dónde IronZIP verifica una contraseña, Cursor nombró al constructor y citó el ejemplo de acceso.
  • Withdraw lanzó KeyNotFoundException por un nombre que le faltaba al paquete.
  • Antes de la solución, los pasos de paquete, lista y reemisión para C-1077 cada uno lanzó Exception "Invalid Password!" desde el constructor de IronZipArchive.
  • Después de la solución, la lista mostró welcome-letter.pdf con 2,643 bytes, y con 2,761 bytes después de la reemisión.
  • La carta reemitida que extrajo pyzipper coincidía con el archivo corregido por SHA-256.
  • Cada paquete C-1077 también contenía una entrada vacía llamada __bundle_keep, que la extracción escribía como un segundo archivo.
  • En el código final, retirar un documento de un paquete de dos documentos dejó una entrada, y la lista luego lanzó "Invalid Password!".
  • La sugerencia de prueba agregó 6 pruebas, y todas las 12 pasaron.
  • IronZIP 2026.10.2 era el único paquete en el servicio, y no quedó ninguna llamada a System.IO.Compression en él.
  • Cada build de Release después de una sugerencia terminó sin advertencia ni error.
  • Algunos pasos se ejecutaron de manera diferente a lo esperado. En Plan Mode, Cursor buscó carpetas fuera del repositorio para ironzip-bundles antes de que abrió el archivo de reglas. Para C-1077, Cursor agregó la entrada __bundle_keep a los paquetes de un solo documento y escribió eso en la regla, en lugar de leer por extracción. La sugerencia de Cloud Agent se envió localmente en el mismo chat en modo Agent, no como un Cloud Agent.

La aprobación del plan antes de cualquier código también ocurre en la guía Claude Code, donde el plan reconstruyó cada archivo a partir de una copia extraída y así manejó un archivo de una sola entrada. La guía de GitHub Copilot restringe sus reglas TAR al archivador de registros y sus pruebas a través del valor applyTo de un archivo de instrucciones específico de ruta, y los globs restringen esta regla de la misma manera. El registro de ejecución nombra la versión de Cursor y el modelo, y da el tiempo total de la sugerencia y el hardware de la máquina de prueba.


Solución de problemas


¿Preguntas?

Si tienes alguna pregunta, contacta a support@ironsoftware.com

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.

Leer más

¿Listo para empezar?

Descargas de NuGet 25,383Versión:2026.11recién lanzado