Comment utiliser IronZIP avec Cursor
ClientDrop, le service .NET 9 de ce guide, compresse le dossier de documents de chaque client dans le fichier ZIP que le client télécharge. Il construit ces lots avec System.IO.Compression, qui ne permet pas de définir un mot de passe, et la conformité exige maintenant que chaque lot soit protégé par AES-256. Le code du lot doit être transféré à IronZIP, et un transfert réalisé par un agent IA présente un risque moins visible. IronZIP et System.IO.Compression ne sont pas d'accord sur des détails qui se compilent encore. System.IO.Compression conserve le chemin du dossier de chaque fichier qu'il compresse, tandis que Add de IronZIP ne conserve que le nom du fichier, de sorte que deux déclarations de mois différents peuvent recevoir le même nom d'entrée.
Le port utilise trois fonctionnalités de Cursor. Une règle de projet engagée nomme les habitudes System.IO.Compression à abandonner ; en mode Plan, l'agent rédige la carte comme un plan avant toute modification de fichier, et les liens de documentation dans les invites et la règle orientent l'agent vers les pages IronZIP. Chaque lot ClientDrop est chiffré lors de sa création, extrait avec ce mot de passe pour prouver qu'il contient toujours tous les fichiers, et ouvert à nouveau avec son mot de passe lorsque les tests comptent ses entrées.
Démarrage rapideAvec ClientDrop ouvert dans Cursor, collez ceci dans Agent. Ses deux mentions attachent la classe du lot et le dossier d'un client.
@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.
La commande inspect lit l'ancien lot et répertorie sept entrées avec leurs chemins de dossier, de contract.pdf à la racine à statements/2026-05/statement.pdf, et aucune d'elles n'est chiffrée.
Laissez la clé de licence en dehors de chaque invite. En mode Agent, Cursor écrit le code et exécute les commandes du terminal, de sorte qu'une clé saisie dans la conversation peut être copiée dans le code ou un message de commit. Définissez plutôt la variable d'environnement IRONZIP_LICENSE_KEY. IronZIP ne lit pas cette variable par elle-même, c'est pourquoi l'invite la fait attribuer à License.LicenseKey. Dans une sonde qui a défini la variable et n'a fait aucune assignation, l'appel de sauvegarde a déclenché une LicensingException qui dit 'Production License Required'. Le guide de la clé de licence couvre les endroits qu'IronZIP consulte de manière autonome, tels qu'un fichier appsettings.json que Git peut ignorer.
Flux de travail minimal (5 étapes)
- Téléchargez la bibliothèque ZIP C# depuis NuGet
- Commit une règle sous .cursor/rules qui abandonne System.IO.Compression et lie les documentations IronZIP
- Ajoutez le nom du fichier mesuré, rééditez et testez les traductions du lecteur à la règle
- Convenir du port en Plan Mode, puis le construire contre les tests existants.
- Extrayez chaque lot et comparez les hachages, et vérifiez les noms des membres dans la référence API
Quel modèle Cursor devriez-vous utiliser pour le travail avec IronZIP ?
Composer est le propre modèle agentique de Cursor. Le sélecteur de modèle offre également les modèles Grok de SpaceXAI, que Cursor a co-développés, ainsi que des modèles d'OpenAI, Anthropic, Google et d'autres laboratoires. L'exécution de ce guide a utilisé Grok 4.7. Quel que soit le modèle que vous choisissez, nommez les fichiers, les tests et les comptes attendus dans l'invite.
Comment donnez-vous la documentation IronZIP à Cursor ?
llms.txt d'IronZIP est une page unique qui liste ses exemples et tutoriels avec un court résumé de chacun. En octobre 2026, le menu @ dans Cursor offre le navigateur, les diffs Git, les terminaux, les discussions passées, les fichiers et dossiers, sans entrée pour la documentation, donc l'invite fournit la documentation IronZIP comme lien.
Le port dépend de l'endroit où les chemins des dossiers aboutissent et du moment où IronZIP vérifie un mot de passe. L'invite suivante demande à Cursor de répondre à la fois à partir des pages et de dire quand aucune page ne couvre un point.
@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.
Les pages répondent à la question de l'encryption en deux moitiés. L'exemple de mot de passe appelle Encrypt avec EncryptionMethods.Traditional, et l'exemple d'accès bascule le même appel en AES-256. Aucune page ne dit ce que fait Add avec un chemin de dossier. Deux pages sont trompeuses. L'exemple d'accès dit qu'un mot de passe incorrect rend l'opération impossible, ce qui n'était valable que pour l'extraction, et l' exemple d'ajout de fichiers ouvre un ZIP existant avec FromFile, qui construit une nouvelle archive contenant ce ZIP comme une seule entrée. La référence IronZipArchive documente des membres qu'aucune page d'exemple ne montre, tels que SetPassword et RemoveEncryption.
ironzip. Enregistré sous .cursor/skills/ironzip/SKILL.md, il est découvert lorsque Cursor démarre, et taper /ironzip dans Agent l'attache à un message.Comment écrivez-vous des règles de projet qui encodent vos conventions IronZIP ?
Les règles de projet sont des fichiers .mdc sous .cursor/rules, engagés avec le code, chacun en Markdown avec un bloc de frontmatter. Le système de règles ignore un fichier .md simple sous .cursor/rules, car un tel fichier n'a pas de frontmatter. Les champs description, globs et alwaysApply décident quand Cursor applique la règle.
Cette règle est limitée par des globaux, donc Cursor l'applique à toute demande qui contient un fichier du service ou de ses tests dans le contexte, et @ironzip-bundles l'attache par nom. Plusieurs motifs vont sur une ligne, séparés par des virgules. Enregistrez-le sous .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.
La ligne FromFile est présente car ouvrir un lot avec FromFile ne soulève aucune erreur, et le lot d'origine reste inchangé.
La règle affecte uniquement les demandes d'Agent. Selon la FAQ sur la page des règles de Cursor, les complétions Tab ignorent les règles, et l'édition en ligne (Ctrl+K) ignore les règles utilisateur.
Comment mappez-vous les appels System.IO.Compression vers IronZIP ?
Une règle qui dit seulement 'utilisez IronZIP' fait en sorte que le modèle trouve ce que devient chaque appel. Chaque résultat IronZIP a été mesuré avec IronZIP 2026.10.2 sur le client C-1042, dont le dossier contient sept documents, dont trois nommés statement.pdf et deux nommés invoice.pdf dans différents dossiers mensuels.
| Appel System.IO.Compression | Attendu | IronZIP |
|---|---|---|
ZipFile.CreateFromDirectory | Sept entrées, dossiers conservés | FromDirectory, montré dans le fichier de compétences, emballe seulement contract.pdf |
CreateEntryFromFile pour chaque fichier | Une entrée par fichier | Add a stocké sept entrées sous quatre noms, et l'extraction a laissé quatre fichiers |
Delete et CreateEntryFromFile en mode mise à jour | Le document réémis conserve son nom | ReplaceEntry a nommé la nouvelle entrée d'après le chemin qu'il a reçu, ici ZipWork/cursor/repo-baseline/TestData/reissue/C-1042/contract.pdf |
ZipFile.OpenRead dans les tests | Chaque entrée lisible | Les entrées AES listées, et la lecture de l'une a levé InvalidDataException 'méthode de compression non supportée' |
Sur le lot avec des noms en double, ReplaceEntry a échoué avant tout renommage. Il a levé ArgumentException 'Un élément avec la même clé a déjà été ajouté' concernant les deux entrées invoice.pdf. Le chiffrement lui-même a fonctionné. Encrypt avec EncryptionMethods.AES256 a marqué toutes les sept entrées comme chiffrées, et une copie en stage du dossier sous des noms plats uniques, tels que statements_2026-03_statement.pdf, extrait sept fichiers qui correspondaient aux originaux par SHA-256. Les noms en double sont le problème le plus difficile à détecter car un lot qui perd une déclaration contient toujours sept entrées, donc un contrôle de compte passe alors que le client télécharge quatre documents.
Ajoutez les traductions à la règle.
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.
Comment planifiez-vous et exécutez-vous une migration vers IronZIP ?
Faites pivoter l'entrée de chat en mode Plan avec Shift+Tab avant d'envoyer l'invite suivante. En mode Plan, Agent peut poser des questions de clarification pendant qu'il recherche le code.
@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.
Le plan est un fichier Markdown que vous pouvez modifier, donc un mappage incorrect peut être corrigé avant que quoi que ce soit ne soit construit. Lorsque le plan est correct, construisez-le à partir du mode Plan, ou retournez en mode Agent avec l'invite suivante, qui ajoute les contrôles.
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.
Dans notre calibration, une traduction directe qui a remplacé chaque appel par son membre IronZIP le plus proche s'est compilée sans problème et a réussi quatre des six tests. Les deux échecs concernaient le contrôle d'extraction et la réémission. Le port qui a suivi la règle a réussi les six.
Comment sortez-vous un document d'un lot protégé ?
BundleBuilder a également besoin d'un moyen pour retirer un document d'un lot qu'un client n'a pas encore téléchargé. Mettez en surbrillance la méthode entière Reissue dans BundleBuilder.cs, appuyez sur Ctrl+Shift+L pour l'ajouter à la discussion ouverte et envoyez la demande en mode 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.
Le retrait résultant est une garde Contains, puis Delete, Encrypt avec EncryptionMethods.AES256 et Save, sur une archive ouverte avec son mot de passe. Le retrait de contract.pdf de C-1042 a laissé six entrées, toutes encore chiffrées. Dans notre calibration, un lot de deux documents en a conservé un, et le constructeur a ensuite échoué à ouvrir le lot.
Pourquoi un lot d'un seul document rejette-t-il son propre mot de passe ?
Le constructeur IronZipArchive rejette le mot de passe correct chaque fois qu'une archive protégée contient exactement une entrée. Dans IronZIP 2026.10.2, il a levé une Exception indiquant 'Mot de passe invalide!' pour les archives à une seule entrée chiffrées avec AES-256, AES-128 et chiffrement traditionnel, et le surcharge de tableau d'octets et FromArchive ont fait de même. ExtractArchiveToDirectory avec le même mot de passe a extrait le fichier sans erreur, et deux entrées ou plus se sont ouvertes normalement.
Le client C-1077 a un seul document, une lettre d'accueil. Mentionnez son dossier, la lettre corrigée et le programme ensemble.
@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.
Dans notre calibration, le lot a été écrit, puis la liste et la réémission ont échoué, de même que la commande du lot elle-même, qui liste le nouveau lot pour imprimer son nombre d'entrées. Lire le lot en l'extrayant dans un dossier temporaire, et le réécrire à partir de ce dossier pour une réédition ou un retrait, a listé la lettre de 2 643 octets et remplacé par la corrigée. Ajoutez ce bloc sous les traductions.
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.
Comment écrivez-vous des tests de régression pour les lots ?
Un agent cloud peut écrire la suite de régression. Il clone le dépôt de votre contrôle source connecté, alors poussez d'abord le port, et ajoutez IRONZIP_LICENSE_KEY comme secret dans le tableau de bord des agents cloud avant de démarrer un.
@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.
Le test du mot de passe incorrect doit extraire le lot. Sur un lot de trois entrées, le constructeur a accepté un mauvais mot de passe sans erreur, et le compte des entrées, la liste des entrées et la recherche de nom ont tous répondu comme si c'était correct. ExtractArchiveToDirectory a été le premier appel à le refuser, avec ArgumentException 'Mot de passe invalide!!'. Un port qui liste les entrées par extraction rejette donc un mot de passe incorrect à la première lecture.
Le guide des assistants de codage AI d'IronZIP exécute une tâche IronZIP de bout en bout contre les critères de réussite définis.
Qu'est-ce que les messages ont produit lors d'une réelle exécution ?
Les sept invites ont été envoyées à Cursor dans l'ordre, dans une seule conversation, contre une copie du dépôt ClientDrop créée pour ce guide. La copie contenait le BundleBuilder System.IO.Compression, six tests xUnit qui lisent les lots avec System.IO.Compression, et le client C-1042. Le fichier de règle et le client C-1077 ont été ajoutés immédiatement avant les invites qui les utilisent, et la clé de licence n'a été définie que comme une variable d'environnement. Chaque figure ci-dessous provient des compilations et des exécutions du code engagé après la fin de la discussion.
- Tous les 6 tests ont été réussis avant le port, et les mêmes 6 ont été réussis après.
- Le lot porté C-1042 a contenu 7 entrées sous des noms plats uniques.
- IronZIP a extrait 7 fichiers de ce lot, le même nombre que celui contenu dans le dossier client.
- pyzipper, un lecteur ZIP Python qui ne partage aucun code avec IronZIP, a trouvé un chiffrement AES-256 sur toutes les 7 entrées.
- Les 7 fichiers extraits correspondaient aux fichiers dans le dossier client par SHA-256.
- À la question de savoir où IronZIP vérifie un mot de passe, Cursor a nommé le constructeur et cité l'exemple d'accès.
- Withdraw a levé KeyNotFoundException pour un nom que le lot n'avait pas.
- Avant la correction, les étapes de lot, de liste et de réédition pour C-1077 ont chacune levé Exception 'Mot de passe invalide!' du constructeur IronZipArchive.
- Après la correction, la liste a montré welcome-letter.pdf à 2 643 octets, et à 2 761 octets après la réémission.
- La lettre réémise qu'a extrait pyzipper correspondait au fichier corrigé par SHA-256.
- Chaque lot C-1077 contenait également une entrée vide nommée __bundle_keep, que l'extraction a écrite comme un deuxième fichier.
- Dans le code final, retirer un document d'un lot de deux documents a laissé une entrée, et la liste a ensuite levé 'Mot de passe invalide!'.
- L'invite de test a ajouté 6 tests, et les 12 ont été réussis.
- IronZIP 2026.10.2 était le seul package dans le service, et aucun appel System.IO.Compression n'en restait.
- Chaque build Release après une invite s'est terminé sans avertissement ni erreur.
- Certaines étapes ont été exécutées différemment de la page. En mode Plan, Cursor a recherché des dossiers hors du dépôt pour ironzip-bundles avant d'ouvrir le fichier de règle. Pour C-1077, Cursor a ajouté l'entrée __bundle_keep aux lots d'un document et l'a écrite dans la règle, à la place de la lecture par extraction. L'invite de l'Agent cloud a été envoyée localement dans la même discussion en mode Agent, et non comme un Agent cloud.
L'approbation du plan avant tout code se produit également dans le guide Claude Code, où le plan a reconstruit chaque archive à partir d'une copie extraite et a ainsi traité une archive à entrée unique. Le guide GitHub Copilot restreint ses règles TAR à l'archiviseur de logs et ses tests via la valeur applyTo d'un fichier d'instructions spécifiques au chemin, et les globaux restreignent cette règle de la même manière. Le journal d'exécution nomme la version Cursor et le modèle, et donne le temps total de l'invite et le matériel de la machine de test.
Dépannage
- Clés de licence IronZIP lorsque le code porté déclenche LicensingException
- Protéger par mot de passe ZIP lorsqu'un lot nécessite AES-256
- Accéder au ZIP protégé lorsqu'une réédition doit rouvrir un lot avec son mot de passe
- Extraire le ZIP protégé lorsqu'un lot d'un seul document ne s'ouvre pas
- Limites de taille de fichier et d'archive IronZIP pour les lots dépassant 4 Go ou 65 535 entrées
Des questions ?
Si vous avez des questions, contactez support@ironsoftware.com
Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes et créer des manuels bien structurés et visuellement attrayants.