Jak używać IronZIP z Cursorem

Curtis Chau
Curtis Chau
Zaktualizowano: 26 października 2026

ClientDrop, usługa .NET 9 w tym przewodniku, pakuje folder dokumentów każdego klienta do pliku ZIP pobieranego przez klienta. Buduje te pakiety za pomocą System.IO.Compression, które nie ma możliwości ustawienia hasła, a zgodnie z przepisami teraz każdy pakiet musi być chroniony za pomocą AES-256. Kod pakietu musi zostać przeniesiony do IronZIP, a przeniesienie wykonane przez agenta AI wiąże się z mniej widocznym ryzykiem. IronZIP i System.IO.Compression nie zgadzają się w szczegółach, które nadal można skompilować. System.IO.Compression zachowuje ścieżkę folderu każdego pliku, który pakuje, a Add IronZIP przechowuje tylko nazwę pliku, więc dwa oświadczenia z różnych miesięcy mogą uzyskać tę samą nazwę wpisu.

Port używa trzech funkcji Cursora. Zadeklarowana zasada projektu nazywa nawyki System.IO.Compression do porzucenia, w trybie Plan agent zapisuje mapowanie jako plan przed jakąkolwiek zmianą plików, a linki do dokumentacji w zapytaniach i zasada kieruje agenta do stron IronZIP. Każdy pakiet ClientDrop jest szyfrowany podczas budowy, wyciągany z tym hasłem w celu potwierdzenia, że nadal zawiera każdy plik, oraz otwierany ponownie z jego hasłem, gdy testy liczą jego wpisy.

Szybki start
NuGetInstalacja z NuGet

PM > Install-Package IronZip

Zainstaluj IronZIP, wykonując powyższe polecenie w konsoli Menedżera Pakietów NuGet lub wyszukaj pakiet w Menedżerze Pakietów NuGet.

Z otwartym ClientDrop w Cursor, wkleić to do Agent. Jego dwa odniesienia dołączają klasę pakietu i folder jednego klienta.

@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

Polecenie inspekcji odczytuje stary pakiet i wymienia siedem wpisów z ich ścieżkami folderów, od contract.pdf w korzeniu do statements/2026-05/statement.pdf, z których żaden nie jest zaszyfrowany.

Pomiń klucz licencyjny we wszystkich przypomnieniach. W trybie Agent, Cursor pisze kod i wykonuje polecenia terminalu, więc klucz wpisany w rozmowę można skopiować do kodu lub wiadomości zatwierdzającej. Ustaw zmienną środowiskową IRONZIP_LICENSE_KEY zamiast tego. IronZIP nie odczytuje tej zmiennej samodzielnie, dlatego zapytanie ma kod przypisujący ją do License.LicenseKey. W próbie, która ustawiła zmienną i nie dokonała przypisania, wywołanie zapisu rzuciło wyjątkiem LicensingException, który brzmi "Production License Required". Przewodnik po kluczach licencyjnych obejmuje miejsca, które IronZIP faktycznie sprawdza samodzielnie, takie jak plik appsettings.json, który Git może ignorować.



Jaki model Cursora należy użyć do pracy z IronZIP?

Composer to własny agentyczny model Cursor. Wybór modelu oferuje także modele SpaceXAI Grok, które Cursor współtworzył, oraz modele od OpenAI, Anthropic, Google i innych laboratoriów. Bieg w tym przewodniku używał Grok 4.7. Niezależnie od wybranego modelu, nazwij pliki, testy i oczekiwane liczniki w zapytaniu.

Jak przekazać dokumentację IronZIP do Cursora?

llms.txt IronZIP to pojedyncza strona, która wymienia jego przykłady i samouczki z krótkim podsumowaniem każdego z nich. Na październik 2026, menu @ w Cursor oferuje przeglądarkę, różnice Git, terminale, wcześniejsze czaty, pliki i foldery, bez pozycji dla dokumentacji, zatem zapytanie przekazuje dokumentację IronZIP jako link.

Port zależy od tego, gdzie trafiają ścieżki folderów i kiedy IronZIP sprawdza hasło. Następne zapytanie prosi Cursora o odpowiedź z obu stron, azeby określić, kiedy żadna strona nie obejmuje punktu.

@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

Strony odpowiadają na pytania dotyczące szyfrowania w dwóch częściach. Przykład hasła wywołuje Encrypt z EncryptionMethods.Traditional, a przykład dostępu przełącza to samo wywołanie na AES-256. Żadna strona nie mówi, co Add robi ze ścieżką folderu. Dwie strony wprowadzają w błąd. Przykład dostępu mówi, że błędne hasło powoduje niepowodzenie operacji, co było prawdziwe tylko w przypadku wyodrębniania, a przykład dodawania plików otwiera istniejący ZIP za pomocą FromFile, co tworzy nowy archiwum zawierające ten ZIP jako pojedynczy wpis. Dokumentacja IronZipArchive dokumentuje członków, których żadna strona z przykładami nie pokazuje, takie jak SetPassword i RemoveEncryption.

Uwaga: IronZIP publikuje także plik umiejętności, którego frontmatter nazywa go ironzip. Zapisane jako .cursor/skills/ironzip/SKILL.md, jest odkrywane podczas uruchamiania Cursor, a wpisanie /ironzip w Agent przypina je do jednej wiadomości.

Jak pisać zasady projektowe kodujące konwencje IronZIP?

Zasady projektowe to pliki .mdc pod .cursor/rules, zatwierdzone z kodem, każdy jako Markdown z blokiem frontmatter. System reguł pomija zwykły plik .md pod .cursor/rules, ponieważ taki plik nie ma frontmatter. .Reguły mogą uruchamiać description, globs i alwaysApply, aby zdecydować, kiedy Cursor stosuje zasadę.

Ta zasada jest ograniczona do globów, więc Cursor stosuje ją do każdego żądania, które ma plik z usługi lub jej testów w kontekście, a @ironzip-bundles dołącza je po nazwie. Kilka wzorców znajduje się w jednej linii, oddzielone przecinkami. Zapisz to jako .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

Linia FromFile znajduje się tam, ponieważ otwieranie pakietu z FromFile nie powoduje błędu, a oryginalny pakiet pozostaje niezmieniony.

Zasada dotyczy tylko żądań Agenta. Według FAQ na stronie reguł Cursora, uzupełnienia Tab ignorują zasady, a edycja w linii (Ctrl+K) ignoruje zasady użytkownika.

Jak mapować wywołania System.IO.Compression do IronZIP?

Zasada, która mówi tylko "używaj IronZIP", sprawia, że model opracowuje, na co przekłada się każde wywołanie. Każdy wynik IronZIP był mierzony za pomocą IronZIP 2026.10.2 na kliencie C-1042, którego folder zawiera siedem dokumentów, z których trzy noszą nazwę statement.pdf, a dwa mają nazwę invoice.pdf w różnych folderach miesięcznych.

Wywołanie System.IO.CompressionOczekiwaneIronZIP
ZipFile.CreateFromDirectorySeven entries, folders keptFromDirectory, pokazane w pliku umiejętności, zapakowano tylko contract.pdf
CreateEntryFromFile dla każdego plikuJeden wpis na plikAdd przechowywał siedem wpisów pod czterema nazwami, a ekstrakcja pozostawiła cztery pliki
Delete i CreateEntryFromFile w trybie aktualizacjiPonowiony dokument zachowuje swoją nazwęReplaceEntry nazwał nowy wpis według ścieżki, którą mu podano, tutaj ZipWork/cursor/repo-baseline/TestData/reissue/C-1042/contract.pdf
ZipFile.OpenRead w testachKażdy wpis jest do odczytuPozycje AES wymienione, a odczyt jednej z nich rzucał wyjatek InvalidDataException "unsupported compression method"

Na pakiecie z duplikowanymi nazwami, ReplaceEntry niepowiodło się przed jakimkolwiek przemianowaniem. Rzucił wyjątek ArgumentException "An item with the same key has already been added" w związku z dwoma wpisami invoice.pdf. Szyfrowanie samo w sobie działało. Encrypt z EncryptionMethods.AES256 oznaczył wszystkie siedem wpisów jako zaszyfrowane, a scenariuszowa kopia folderu pod unikalnymi nazwami płaskimi, takimi jak statements_2026-03_statement.pdf, wyodrębniona do siedmiu plików, które odpowiadały oryginałom przez SHA-256. Duplikowane nazwy są najtrudniejszym problemem do złapania, ponieważ pakiet, który traci oświadczenie, nadal posiada siedem wpisów, więc sprawdzanie liczby przechodzi, gdy klient pobiera cztery dokumenty.

Dołącz tłumaczenia do zasady.

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

Jak planować i przeprowadzać migrację do IronZIP?

Obrócić wejście czatu w tryb planu za pomocą Shift+Tab przed wysłaniem następnego zapytania. W trybie planu, Agent może zadawać pytania wyjaśniające podczas badania kodu.

@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

Plan to plik Markdown, który można edytować, dzięki czemu można poprawić błędną mapę przed skompilowaniem czegokolwiek. Gdy plan jest poprawny, zbudować go z trybu planu lub wrócić do trybu agenta z kolejnym zapytaniem, które dodaje kontrole.

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

W naszym kalibrze, bezpośrednie tłumaczenie, które zamieniało każde wywołanie na jego najbliższy członek IronZIP, kompilowało się bez błędów i przeszło cztery z sześciu testów. Dwie porażki dotyczyły sprawdzania wyodrębniania i ponowienia wydania. Port, który podążał za zasadą przeszedł wszystkie sześć.

Jak wyjąć jeden dokument z chronionego pakietu?

BundleBuilder potrzebuje także sposobu na usunięcie jednego dokumentu z pakietu, którego klient jeszcze nie pobrał. Zaznaczyć całą metodę Reissue w BundleBuilder.cs, nacisnąć Ctrl+Shift+L, aby dodać ją do otwartego czatu i wysłać zapytanie w trybie agenta.

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

Wynikowy Wycofanie to straż Contains, następnie Delete, Encrypt z EncryptionMethods.AES256 i Save, w archiwum otwartym z jego hasłem. Wycofanie contract.pdf z C-1042 pozostawiło sześć wpisów, wszystkie nadal zaszyfrowane. W naszym kalibrze pakiet dwóch dokumentów zachował jeden, a konstruktor następnie nie otworzył pakietu.

Dlaczego pakiet jednego dokumentu odrzuca własne hasło?

Konstruktor IronZipArchive odrzuca prawidłowe hasło, gdy chronione archiwum zawiera dokładnie jeden wpis. W IronZIP 2026.10.2 rzucił wyjątkiem odczytującym "Invalid Password!" dla archiwów z jednym wpisem zaszyfrowanych za pomocą AES-256, AES-128 i Tradycyjnego szyfrowania, a przeciążenie tablicy bajtów i FromArchive zrobiły to samo. ExtractArchiveToDirectory z tym samym hasłem wyodrębnił plik bez błędu, a dwa wpisy lub więcej otworzyły się normalnie.

Klient C-1077 ma jeden dokument, list powitalny. Wspomnij jego folder, poprawiony list i program razem.

@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

W naszym kalibrze pakiet został zapisany, następnie lista i ponowienie nie powiodły się, a także sam pakiet, który wymienia nowe pakiety w celu wydrukowania liczby wpisów. Czytanie pakietu przez wyodrębnienie go do tymczasowego folderu, a następnie zapisanie go ponownie z tego folderu na potrzeby ponowienia lub wycofania, wylistowało 2 643-bajtowy list i podmieniło go na poprawioną wersję. Dołącz ten blok poniżej tłumaczeń.

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

Jak pisać testy regresji dla pakietów?

Agent w Chmurze może napisać zestaw testów regresji. Klonuje repozytorium z połączonej kontroli źródła, więc najpierw wykonać port, i dodać IRONZIP_LICENSE_KEY jako sekret w panelu Cloud Agents przed uruchomieniem jednego.

@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

Błędny test hasła musi wyciągnąć pakiet. Na pakiecie trzech wpisów, konstruktor przyjął błędne hasło bez błędu, a licznik wpisów, lista wpisów i nazwa odpowiedziały, jakby było poprawne. ExtractArchiveToDirectory było pierwszym wywołaniem, które go odrzuciło, z wyjątkiem ArgumentException "Invalid password!!". Port, który listuje wpisy przez ekstrakcję, zatem odrzuca błędne hasło przy pierwszym odczycie.

Przewodnik po asystentach kodowania AI IronZIP przeprowadza jedno zadanie IronZIP od początku do końca przeciwko zdefiniowanym kryteriom zdania.

Co wyprodukowały zapytania w rzeczywistym uruchomieniu?

Siedem zapytań zostało wysłanych do Cursora w kolejności, w jednej rozmowie, przeciwko kopii repozytorium ClientDrop wykonanej dla tego przewodnika. Kopia zawierała System.IO.Compression BundleBuilder, sześć testów xUnit, które czytały pakiety z System.IO.Compression, i klienta C-1042. Plik reguł i klient C-1077 zostały dodane bezpośrednio przed zapytaniami, które ich używają, a klucz licencyjny ustawiono tylko jako zmienną środowiskową. Każda liczba poniżej pochodzi z kompilacji i uruchomienia zatwierdzonego kodu po zakończeniu czatu.

  • Wszystkich 6 testów przeszło przed portem, i te same 6 przeszło po nim.
  • Przeniesiony pakiet C-1042 zawierał 7 wpisów pod unikalnymi płaskimi nazwami.
  • IronZIP wyodrębnił 7 plików z tego pakietu, tyle samo jak folder klienta zawierał.
  • pyzipper, czytnik ZIP w Pythonie, który nie dzieli kodu z IronZIP, znalazł szyfrowanie AES-256 na wszystkich 7 wpisach.
  • Wszystkie 7 wyodrębnionych plików pasowało do plików w folderze klienta przez SHA-256.
  • Zapytany, gdzie IronZIP sprawdza hasło, Cursor wymienił konstruktor i zacytował przykład dostępu.
  • Wycofanie rzuciło wyjątkiem KeyNotFoundException dla nazwy, której pakiet nie posiadał.
  • Przed poprawką, kroki pakietu, listy i ponownego wydania dla C-1077 każdy rzucił wyjątkiem "Invalid Password!" z konstruktora IronZipArchive.
  • Po poprawce, lista pokazała welcome-letter.pdf o wielkości 2 643 bajty, a po ponownym wydaniu 2 761 bajty.
  • Ponownie wydany list wyodrębniony przez pyzipper pasował do poprawionego pliku przez SHA-256.
  • Każdy pakiet C-1077 zawierał także pusty wpis nazwany __bundle_keep, który ekstrakcja zapisała jako drugi plik.
  • W końcowym kodzie, wycofanie jednego dokumentu z pakietu dwóch dokumentów pozostawiło jeden wpis, a lista następnie rzuciła "Invalid Password!".
  • Zapytanie testowe dodało 6 testów, i wszystkie 12 przeszło.
  • IronZIP 2026.10.2 był jedynym pakietem w usłudze, i żadne wywołanie System.IO.Compression w nim nie pozostało.
  • Każda kompilacja Release po zakończeniu zapytania kończyła się bez ostrzeżenia lub błędu.
  • Niektóre kroki uruchomiono inaczej niż na stronie. W trybie planu, Cursor przeszukiwał foldery poza repozytorium dla ironzip-bundles przed otwarciem pliku reguł. Dla C-1077, Cursor dodawał wpis __bundle_keep do pakietów z jednym dokumentem i zapisywał to do reguły, zamiast czytania przez ekstrakcję. Zapytanie Agent w Chmurze było wysyłane lokalnie w tej samej rozmowie w trybie agenta, a nie jako Agent w Chmurze.

Zatwierdzanie planu przed jakimkolwiek kodem również ma miejsce w przewodniku Claude Code, gdzie plan odbudował każde archiwum z wyodrębnionej kopii i zatem obsługiwał archiwum z jednym wpisem. przewodnik GitHub Copilot ogranicza swoje zasady TAR do archiwizera logów i jego testów przez wartość applyTo pliku instrukcji specyficznego dla ścieżki, a globy ograniczają tę zasadę w ten sam sposób. Zapis przebiegu wymienia wersję Cursora i model, i podaje całkowity czas zapytania oraz sprzęt maszyny testowej.


Rozwiązywanie problemów


Pytania?

Jeśli są jakiekolwiek pytania, należy skontaktować się z support@ironsoftware.com

Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.

Czytaj więcej

Gotowy, aby rozpocząć?

Pobrania z NuGet 25,383Wersja:2026.11właśnie wydane