Wie verwenden Sie IronZIP mit Cursor

Curtis Chau
Curtis Chau
Aktualisiert: 26. Oktober 2026

ClientDrop, der .NET 9-Dienst in diesem Leitfaden, packt den Dokumentenordner jedes Kunden in die ZIP-Datei, die der Kunde herunterlädt. Es erstellt diese Bündel mit System.IO.Compression, das keine Möglichkeit hat, ein Passwort festzulegen, und die Compliance erfordert jetzt, dass jedes Bündel mit AES-256 geschützt wird. Der Bündelcode muss zu IronZIP verschoben werden, und ein von einem KI-Agenten durchgeführter Umzug birgt ein geringeres sichtbares Risiko. IronZIP und System.IO.Compression sind sich über Details uneinig, die dennoch kompiliert werden. System.IO.Compression behält den Ordnerpfad jeder Datei, die es packt, und IronZIP's Add behält nur den Dateinamen, sodass zwei Anweisungen aus verschiedenen Monaten denselben Eintragsnamen erhalten können.

Der Port verwendet drei Cursor-Funktionen. Eine festgelegte Projektregel benennt die Gewohnheiten von System.IO.Compression, die verworfen werden sollen. Im Planmodus schreibt der Agent die Zuordnung als Plan auf, bevor Änderungen an Dateien vorgenommen werden, und Dokumentationslinks in den Eingabeaufforderungen und in der Regel führen den Agenten zu den Seiten von IronZIP. Jedes ClientDrop-Bündel wird verschlüsselt erstellt, mit diesem Passwort extrahiert, um zu beweisen, dass es immer noch jede Datei enthält, und wieder mit seinem Passwort geöffnet, wenn die Tests seine Einträge zählen.

Schnellstart
NuGetMit NuGet installieren

PM > Install-Package IronZip

Installieren Sie IronZIP, indem Sie den obigen Befehl in der NuGet Packet Manager-Konsole ausführen, oder suchen Sie das Paket im NuGet Paket Manager.

Mit geöffnetem ClientDrop in Cursor fügen Sie dies in Agent ein. Seine zwei Erwähnungen hängen die Bündelklasse und den Ordner eines Kunden an.

@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

Der Inspektionsbefehl liest das alte Bündel und listet sieben Einträge mit ihren Ordnerpfaden auf, von contract.pdf im Wurzelverzeichnis bis statements/2026-05/statement.pdf, und keiner von ihnen ist verschlüsselt.

Lassen Sie den Lizenzschlüssel aus jeder Aufforderung heraus. Im Agent-Modus schreibt Cursor Code und führt Terminalbefehle aus, sodass ein in das Gespräch getippter Schlüssel in den Code oder eine Commit-Nachricht kopiert werden kann. Setzen Sie stattdessen die IRONZIP_LICENSE_KEY-Umgebungsvariable. IronZIP liest diese Variable nicht eigenständig, weshalb die Eingabeaufforderung den Code anweist, sie License.LicenseKey zuzuweisen. In einer Untersuchung, die die Variable setzte und keine Zuweisung vornahm, warf der Aufruf von save eine LicensingException aus, die „Produktionslizenz erforderlich“ anzeigte. Der Lizenzschlüssel-Leitfaden behandelt die Orte, die IronZIP von selbst durchsucht, wie eine appsettings.json-Datei, die von Git ignoriert werden kann.



Welches Cursor-Modell sollten Sie für IronZIP-Arbeiten verwenden?

Composer ist Cursors eigenes agentisches Modell. Der Modellwähler bietet auch die Grok-Modelle von SpaceXAI, die Cursor mitentwickelt hat, sowie Modelle von OpenAI, Anthropic, Google und anderen Laboren. Der Lauf in diesem Leitfaden verwendete Grok 4.7. Welches Modell Sie auch wählen, benennen Sie die Dateien, die Tests und die erwarteten Zähler in der Eingabeaufforderung.

Wie geben Sie Cursor die IronZIP-Dokumentation?

IronZIP's llms.txt ist eine einzelne Seite, die ihre Beispiele und Tutorials mit einer kurzen Zusammenfassung jedes einzelnen auflistet. Mit Stand Oktober 2026 bietet das @-Menü in Cursor den Browser, Git Diffs, Terminals, vergangene Chats, Dateien und Ordner, ohne Eintrag für Dokumentation, sodass die Eingabeaufforderung IronZIP's Dokumentation als Link angibt.

Der Port hängt davon ab, wohin die Ordnerpfade gehen und wann IronZIP ein Passwort überprüft. Die nächste Eingabeaufforderung fordert Cursor auf, sowohl von den Seiten zu antworten als auch anzugeben, wenn keine Seite einen Punkt abdeckt.

@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

Die Seiten beantworten die Verschlüsselungsfrage in zwei Hälften. Das Passwortbeispiel ruft Encrypt mit EncryptionMethods.Traditional auf, und das Zugriffbeispiel wechselt denselben Aufruf zu AES-256. Keine Seite sagt, was Add mit einem Ordnerpfad macht. Zwei Seiten führen in die Irre. Das Zugriffbeispiel besagt, dass ein falsches Passwort den Vorgang scheitern lässt, was nur für die Extraktion zutraf, und das Dateien hinzufügen-Beispiel öffnet ein bestehendes ZIP mit FromFile, das ein neues Archiv erstellt, das dieses ZIP als einen einzigen Eintrag enthält. Die IronZipArchive-Referenz dokumentiert Mitglieder, die keine Beispielseite zeigt, wie SetPassword und RemoveEncryption.

Bitte beachten Sie: IronZIP veröffentlicht auch eine Skill-Datei, deren Frontmatter sie ironzip nennt. Gespeichert als .cursor/skills/ironzip/SKILL.md wird sie entdeckt, wenn Cursor startet, und durch Tippen von /ironzip im Agent-Modus wird sie an eine Nachricht angehängt.

Wie schreiben Sie Projektregeln, die Ihre IronZIP-Konventionen kodieren?

Projektregeln sind .mdc-Dateien unter .cursor/rules, die mit dem Code übernommen werden, jede ist eine Markdown-Datei mit einem Frontmatter-Block. Das Regelsystem überspringt eine einfache .md-Datei unter .cursor/rules, da eine solche Datei kein Frontmatter hat. Die Felder description, globs und alwaysApply entscheiden, wann Cursor die Regel anwendet.

Diese Regel ist mit Globs abgedeckt, sodass Cursor sie auf jede Anfrage anwendet, die eine Datei aus dem Service oder seinen Tests im Kontext hat, und @ironzip-bundles hängt sie nach Name an. Mehrere Muster stehen in einer Zeile, getrennt durch Kommas. Speichern Sie sie als .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

Die FromFile-Zeile ist vorhanden, da das Öffnen eines Bündels mit FromFile keinen Fehler verursacht und das ursprüngliche Bündel unverändert bleibt.

Die Regel betrifft nur Agent-Anfragen. Laut dem FAQ auf Cursors Regeln-Seite ignorieren Tab-Vervollständigungen Regeln, und Inline-Bearbeitung (Ctrl+K) ignoriert Benutzerregeln.

Wie mappen Sie System.IO.Compression-Aufrufe auf IronZIP?

Eine Regel, die nur sagt „verwenden Sie IronZIP“, lässt das Modell herausfinden, was aus jedem Aufruf wird. Jedes IronZIP-Ergebnis wurde mit IronZIP 2026.10.2 auf dem Client C-1042 gemessen, dessen Ordner sieben Dokumente enthält, davon drei als statement.pdf und zwei als invoice.pdf in verschiedenen Monatsordnern benannt.

System.IO.Compression-AufrufErwartetIronZIP
ZipFile.CreateFromDirectorySieben Einträge, Ordner behaltenFromDirectory, im Skill-Datei gezeigt, packte nur contract.pdf
CreateEntryFromFile für jede DateiEin Eintrag pro DateiAdd speicherte sieben Einträge unter vier Namen, und die Extraktion ließ vier Dateien zurück
Delete und CreateEntryFromFile im AktualisierungsmodusDas neu herausgegebene Dokument behält seinen NamenReplaceEntry benannte den neuen Eintrag nach dem gegebenen Pfad, hier ZipWork/cursor/repo-baseline/TestData/reissue/C-1042/contract.pdf
ZipFile.OpenRead in den TestsJeder Eintrag lesbarDie AES-Einträge aufgelistet, und das Lesen eines warf InvalidDataException „nicht unterstützte Komprimierungsmethode“

Beim Bündel mit doppelten Namen scheiterte ReplaceEntry vor jeder Umbenennung. Es warf ArgumentException „Ein Element mit demselben Schlüssel wurde bereits hinzugefügt“ über die zwei invoice.pdf-Einträge. Die Verschlüsselung selbst funktionierte. Encrypt mit EncryptionMethods.AES256 markierte alle sieben Einträge als verschlüsselt, und eine gestufte Kopie des Ordners unter eindeutigen flachen Namen, wie statements_2026-03_statement.pdf, extrahierte zu sieben Dateien, die durch SHA-256 mit den Originalen übereinstimmten. Die doppelten Namen sind das härteste Problem, da ein Bündel, das eine Aussage verliert, immer noch sieben Einträge hält, sodass eine Zählprüfung passiert, während der Client vier Dokumente herunterlädt.

Fügen Sie die Übersetzungen der Regel hinzu.

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

Wie planen und führen Sie eine Migration zu IronZIP durch?

Drehen Sie die Chateingabe in den Planmodus mit Shift+Tab, bevor Sie die nächste Eingabeaufforderung senden. Im Planmodus kann der Agent klärende Fragen stellen, während er den Code untersucht.

@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

Der Plan ist eine Markdown-Datei, die Sie bearbeiten können, sodass eine falsche Zuordnung korrigiert werden kann, bevor etwas erstellt wird. Wenn der Plan korrekt ist, bauen Sie ihn aus dem Planmodus oder kehren Sie mit der nächsten Eingabeaufforderung zurück in den Agent-Modus, der die Prüfungen hinzufügt.

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

In unserer Kalibrierung wurde eine direkte Übersetzung, die jeden Aufruf gegen sein nächstliegendes IronZIP-Mitglied austauschte, sauber kompiliert und bestand vier von sechs Tests. Die beiden Fehler waren die Extraktionsprüfung und die erneute Ausgabe. Der Port, der der Regel folgte, bestand alle sechs.

Wie nehmen Sie ein Dokument aus einem geschützten Bündel heraus?

BundleBuilder benötigt auch eine Möglichkeit, ein Dokument aus einem Bündel zu entfernen, das ein Kunde noch nicht heruntergeladen hat. Markieren Sie die gesamte Reissue-Methode in BundleBuilder.cs, drücken Sie Ctrl+Shift+L, um sie dem offenen Chat hinzuzufügen, und senden Sie die Anfrage im Agent-Modus.

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

Das resultierende Abheben ist eine Contains-Wache, dann Delete, Encrypt mit EncryptionMethods.AES256 und Save, in einem mit seinem Passwort geöffneten Archiv. Der Rückzug von contract.pdf aus C-1042 ließ sechs Einträge zurück, alle noch verschlüsselt. In unserer Kalibrierung behielt ein Bündel von zwei Dokumenten ein, und der Konstruktor konnte das Bündel dann nicht öffnen.

Warum lehnt ein Ein-Dokument-Bündel sein eigenes Passwort ab?

Der IronZipArchive-Konstruktor lehnt das korrekte Passwort ab, wann immer ein geschütztes Archiv genau einen Eintrag enthält. In IronZIP 2026.10.2 warf er eine Exception, die „Ungültiges Passwort!“ lautete, für Einzelerarchiven, die mit AES-256, AES-128 und traditioneller Verschlüsselung verschlüsselt wurden, und die Byte-Array-Überladung und FromArchive taten das Gleiche. ExtractArchiveToDirectory mit demselben Passwort extrahierte die Datei ohne Fehler, und zwei Einträge oder mehr öffneten sich normal.

Kunde C-1077 hat ein Einzeldokument, ein Willkommensbrief. Erwähnen Sie seinen Ordner, den korrigierten Brief und das Programm zusammen.

@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

In unserer Kalibrierung wurde das Bündel geschrieben, dann scheiterten die Liste und die erneute Ausgabe, und der Bündelbefehl selbst, der das neue Bündel auflistet, um seine Eintragsanzahl zu drucken. Das Lesen des Bündels durch Extraktion in einen temporären Ordner und das erneute Schreiben aus diesem Ordner für eine erneute Ausgabe oder einen Rückzug listete den 2.643-Byte-Brief auf und tauschte den korrigierten ein. Fügen Sie diesen Block unter den Übersetzungen hinzu.

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

Wie schreiben Sie Regressionstests für die Bündel?

Ein Cloud-Agent kann die Regressionstestsuite schreiben. Er klont das Repository von Ihrer verbundenen Versionskontrolle, also pushen Sie den Port zuerst und fügen Sie IRONZIP_LICENSE_KEY als Geheimnis im Cloud-Agent-Dashboard hinzu, bevor Sie einen starten.

@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

Der falsche Passworttest muss das Bündel extrahieren. Bei einem Bündel mit drei Einträgen nahm der Konstruktor ein falsches Passwort ohne Fehler an, und die Eintragsanzahl, die Eintragsliste und die Namenssuche antworteten alle, als ob es richtig wäre. ExtractArchiveToDirectory war der erste Aufruf, es abzulehnen, mit ArgumentException „Ungültiges Passwort!“. Ein Port, der Einträge durch Extraktion auflistet, lehnt daher ein falsches Passwort beim ersten Lesen ab.

IronZIP's AI-Coding-Assistenten-Leitfaden führt eine IronZIP-Aufgabe von Anfang bis Ende gegen definierte Erfolgskriterien aus.

Was haben die Aufforderungen in einem realen Lauf erzeugt?

Die sieben Eingabeaufforderungen wurden in der Reihenfolge, in einem Chat, an Cursor gesendet, gegen eine Kopie des ClientDrop-Repositorys, die für diesen Leitfaden erstellt wurde. Die Kopie enthielt den System.IO.Compression-BundleBuilder, sechs xUnit-Tests, die Bündel mit System.IO.Compression lesen, und den Client C-1042. Die Regeldatei und der Client C-1077 wurden unmittelbar vor den Eingabeaufforderungen hinzugefügt, die sie verwenden, und der Lizenzschlüssel wurde nur als Umgebungsvariable festgelegt. Jede nachfolgende Abbildung stammt von Builds und Läufen des übernommenen Codes, nachdem der Chat beendet wurde.

  • Alle 6 Tests bestanden vor dem Port, und dieselben 6 bestanden danach.
  • Das portierte C-1042-Bündel hielt 7 Einträge unter einzigartigen flachen Namen.
  • IronZIP extrahierte 7 Dateien aus diesem Bündel, die gleiche Anzahl wie der Kundenordner enthielt.
  • pyzipper, ein Python-ZIP-Leser, der keinen Code mit IronZIP teilt, stellte AES-256-Verschlüsselung auf allen 7 Einträgen fest.
  • Alle 7 extrahierten Dateien stimmten durch SHA-256 mit den Dateien im Kundenordner überein.
  • Gefragt, wo IronZIP ein Passwort prüft, nannte Cursor den Konstruktor und erwähnte das Zugriffbeispiel.
  • Withdraw warf KeyNotFoundException für einen Namen, der dem Bündel fehlte.
  • Vor der Korrektur warfen die Bündel-, Listen- und erneute Ausgabeschritte für C-1077 jeweils Exception „Ungültiges Passwort!“ vom IronZipArchive-Konstruktor.
  • Nach der Korrektur zeigte die Liste welcome-letter.pdf mit 2.643 Bytes an, und mit 2.761 Bytes nach der erneuten Ausgabe.
  • Der neu herausgegebene Brief, der von pyzipper extrahiert wurde, stimmte durch SHA-256 mit der korrigierten Datei überein.
  • Jedes C-1077-Bündel hielt auch einen leeren Eintrag namens __bundle_keep, den die Extraktion als zweite Datei herausgeschrieben hat.
  • Im endgültigen Code ließ das Entfernen eines Dokuments aus einem Zwei-Dokumenten-Bündel einen Eintrag, und die Liste warf dann „Ungültiges Passwort!“.
  • Die Testaufforderung fügte 6 Tests hinzu, und alle 12 bestanden.
  • IronZIP 2026.10.2 war das einzige Paket im Service, und es blieb kein Aufruf von System.IO.Compression darin.
  • Jeder Release-Build nach einer Eingabeaufforderung endete ohne Warnung oder Fehler.
  • Einige Schritte liefen anders als die Seite. Im Planmodus durchsuchte Cursor Ordner außerhalb des Repositorys nach ironzip-bundles, bevor es die Regeldatei öffnete. Für C-1077 fügte Cursor den __bundle_keep-Eintrag zu Ein-Dokumenten-Bündeln hinzu und schrieb das in die Regel, anstelle des Lesens durch Extraktion. Die Cloud-Agent-Aufforderung wurde lokal im gleichen Chat im Agent-Modus gesendet, nicht als Cloud-Agent.

Planbestätigung vor jedem Code erfolgt auch im Claude-Code-Leitfaden, wo der Plan jedes Archiv aus einer extrahierten Kopie neu erstellte und so ein Einzelarchiv behandelte. Der GitHub Copilot-Leitfaden beschränkt seine TAR-Regeln auf den Log-Archivierer und seine Tests durch den applyTo-Wert einer pfadspezifischen Anleitungsdatei, und die Globs beschränken diese Regel auf die gleiche Weise. Der Laufrekord nennt die Cursor-Version und das Modell und gibt die gesamte Aufforderungszeit und die Hardware der Testmaschine an.


Fehlerbehebung


Fragen?

Wenn Sie Fragen haben, wenden Sie sich an support@ironsoftware.com.

Curtis Chau hat einen Bachelor-Abschluss in Informatik von der Carleton University und ist spezialisiert auf Frontend-Entwicklung mit Expertise in Node.js, TypeScript, JavaScript und React. Leidenschaftlich widmet er sich der Erstellung intuitiver und ästhetisch ansprechender Benutzerschnittstellen und arbeitet gerne mit modernen Frameworks sowie der Erstellung gut strukturierter, optisch ansprechender Handbücher.

Mehr lesen

Bereit loszulegen?

NuGet-Downloads 25,383Version:2026.11gerade veröffentlicht