Wie man IronZIP mit GitHub Copilot verwendet

Curtis Chau
Curtis Chau
Aktualisiert: 26. Oktober 2026

Einige .NET-Systeme schreiben Protokolle in einen Ordner pro Dienst, und ihr Betriebsteam möchte jeden Tag davon als eine .tar.gz kopieren, um sie auf einen Linux-Host zu verlagern und mit tar -xzf zu entpacken. Der Job, der diese Bündel erstellt, gehört zur gleichen Visual Studio-Lösung wie die Dienste.

Copilot CLI kann diesen Job in einem Terminal erstellen, Copilot Chat und Agent-Modus können ihn in Visual Studio oder VS Code erstellen, und der Cloud-Agent kann ein GitHub-Problem darüber in eine Pull-Anfrage umwandeln. IronZIP schreibt und entpackt TAR und GZIP aus .NET und zwei Anleitungsdateien im Repository erklären jeder Copilot-Oberfläche in diesem Leitfaden, wie ihre TAR-Aufrufe sich verhalten.

Das Beispiel zum Erstellen von TAR, das Beispiel zum Erstellen von GZIP und das Beispiel zum Extrahieren von GZIP zeigen die Aufrufe, auf denen dieser Leitfaden aufbaut.

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.

Starten Sie copilot am Lösungsstamm und senden Sie diese Aufforderung. Copilot Chat in Visual Studio benennt Dateien mit #, wo die CLI @ verwendet.

Read @docs/bundle-format.md, then fill in @src/LogArchiver/Archiving/LogBundle.cs.

Add one public static method that works like this:
- Its signature is Create(string logsRoot, DateOnly day, string outputFolder).
- It writes the day's bundle and returns its path.
- It returns null when the day has no logs.
- It builds the TAR and the GZIP with IronZIP.
- IronZIP comes from the IronZIP package and lives in the IronZip namespace.

Change the bundle command in Program.cs to call Create.
It prints the bundle path, or the message the format document gives for a day without logs.
Run it for 2026-10-10, then list the bundle with tar -tvzf and show me the listing.
Text

Die pfadspezifische Anleitungsdatei gibt die TAR-Namensregel von IronZIP an, daher lässt die Aufforderung sie aus.

Speichern Sie den Schlüssel in der IRONZIP_LICENSE_KEY Umgebungsvariable oder einem Repository-Geheimnis, außerhalb von Aufforderungen und Commits. In einer Untersuchung, die nur diese Variable eingestellt hat, gab License.IsLicensed false zurück, daher kopiert Program.cs den Wert in IronZip.License.LicenseKey. Um den Schlüssel stattdessen in einer Konfigurationsdatei einzustellen, folgen Sie dem Lizenzschlüssel-Leitfaden. Lassen Sie den Zweigschutz und eine menschliche Genehmigung für die Pull-Anfragen des Cloud-Agents eingeschaltet.



Wie setzt man die IronZIP-Konventionen für Copilot?

Die Support-Referenz von GitHub listet .github/copilot-instructions.md für Copilot CLI, den Cloud-Agenten und Copilot Chat sowohl in Visual Studio als auch in VS Code auf, daher werden die Paket-, Lizenz- und Testrichtlinien dorthin übertragen. Visual Studio ignoriert die Datei, bis das benutzerdefinierte Anweisungen-Kontrollkästchen in den Copilot-Chat-Optionen aktiviert ist.

Archive code in this repo follows these rules:

- Archive code uses IronZIP from the IronZIP NuGet package, namespace IronZip.
- Add no other compression package.
- Keep System.Formats.Tar and System.IO.Compression out of src/.
- Tests may use them to read bundles.
- Change the IronZIP version in Directory.Packages.props only for an upgrade task.
- IRONZIP_LICENSE_KEY holds the license key.
- Never put it in code, settings, tests or output, and never echo it.
- Check only that it is set.
- docs/bundle-format.md is the contract for every bundle.
- Do not edit it, and report any place where the code departs from it.
- IronZIP documentation for agents: https://ironsoftware.com/zip/csharp/llms.txt
- Find each IronZIP member in IronZip.xml in the NuGet cache before using it.
- If a member is missing there, say so.

The tests follow these rules:

- A test that calls IronZIP copies IRONZIP_LICENSE_KEY into License.LicenseKey first.
- IronZIP never reads that variable on its own.
- Write bundles into a temp folder.
- Unpack them into a second empty folder and compare files by SHA-256.
- Never compare archive bytes.
Markdown

Wie gibt man dem Archiv-Code eigene Regeln?

Speichern Sie die Archivregeln als .github/instructions/archives.instructions.md. GitHub dokumentiert, dass Copilot CLI eine pfadspezifische Datei nur einbezieht, wenn ihr applyTo Wert mit einer Datei übereinstimmt, mit der die CLI arbeitet. Der /instructions Befehl listet die Anleitungsdateien auf, die die CLI gefunden hat, und schaltet jede ein oder aus.

---
applyTo: "src/LogArchiver/**,tests/LogArchiver.Tests/**"
---

IronZIP's TAR and GZIP calls behave this way in the log archiver and its tests:

- IronTarArchive.Add keeps only the file name and drops every folder.
- Two files with one name become two entries with that name, and unpacking keeps the last.
- Copy each file into a staging folder under its final entry name and add the copy.
- IronTarArchive.Add on a folder adds nothing and throws nothing.
- A GZIP file holds one stream.
- Save the TAR first, then add that single file to an IronGZipArchive.
- Two files added to one IronGZipArchive come out as one file with both contents joined.
- GetArchiveEntryNames throws on a new archive that was never saved.
- Call it on an archive opened from a file.
- No entry can be added after SaveAs. Start a new archive instead.
- Unpack a .tar.gz with IronGZipArchive.ExtractTGZArchiveToDirectory.
- Always unpack into a new empty folder.
- Unpacking replaces files of the same name and leaves every other file where it was.
- IronTarArchive.ExtractArchiveToDirectory writes an entry named ../x or /x outside the target.
- Check every name from GetArchiveEntryNames first.
- Without a key, IronTarArchive.Add throws LicensingException.
- SaveAs then still writes an empty archive.
- Never catch that exception and continue.
Markdown

Was behält der TAR-Schreiber von IronZIP von einem Dateipfad?

Jeder Dienst hier benennt sein Protokoll nach dem Tag, daher teilen logs/api/2026-10-10.log und logs/worker/2026-10-10.log einen Dateinamen. Direkt aus ihren Ordnern hinzugefügt mit IronZIP 2026.10.2, wurden die vier Protokolle für den 10. Oktober zu vier TAR-Einträgen mit dem Namen 2026-10-10.log. tar -tvzf hat alle vier aufgelistet, und nichts hat einen Fehler geworfen. Mit IronZIP entpackt, hielt das Bündel einen 2026-10-10.log mit 19.813 Bytes, das zuletzt hinzugefügte Arbeiterprotokoll.

Mit jedem Protokoll als Kopie benannt nach seinem Dienst, wie z.B. worker-2026-10-10.log, bestanden die Bündel für den 10., 9. und den leeren 8. Oktober alle 24 Prüfungen eines Python-Format-Prüfers, der Bündel ohne IronZIP liest. Jeder Eintrag hatte den Modus 700, Besitzer 0 und die Zeit des Speicherns anstelle des eigenen Zeitstempels der Datei. Zwei Bündel derselben Protokolle, zwei Sekunden auseinander gebaut, differierten ab dem fünften Byte, wo GZIP seine Zeit speichert.

Wie überprüft man ein Bündel, nachdem es geschrieben wurde?

Gerichtet auf einen benutzten Ordner, ersetzte ExtractTGZArchiveToDirectory Dateien mit demselben Namen und behielt den Rest, sodass eine Überprüfung, die einen Ordner wiederverwendet, eine veraltete Datei zählen kann.

Add a verify <bundle> command to Program.cs beside bundle.

The command runs these steps in order:
1. Unpack the bundle with IronZIP into a fresh temp folder.
2. Read manifest.txt there.
3. Confirm the folder holds manifest.txt plus exactly the files it names.
4. Confirm those files have matching sizes and SHA-256 hashes.

It reports the outcome this way:
- Print one line for each problem, and exit 1 if there is one.
- If there is none, print the file count and exit 0.
- If IronZIP cannot unpack the bundle, print its exception and exit 1.
- Delete the temp folder either way.

Run verify on the 2026-10-10 bundle.
Then run it on a copy of that bundle in a temp folder with the middle byte flipped.
Show me both results.
Text

In der Kalibrierungssonde ließ das gekippte Byte IronZIP einen TarException („Header-Prüfsumme ist ungültig“) werfen, nachdem es bereits das erste Protokoll geschrieben hatte, sodass ein fehlgeschlagenes Entpacken einen teilweisen Ordner hinterlassen kann.

Wie testet man ein IronZIP-Bündel?

Ein Test, der jedes Bündel mit System.Formats.Tar sowie IronZIP liest, fängt einen Benennungsfehler auf, den ein IronZIP-Entpacken verbirgt. Die CLI-Referenz von GitHub sagt, dass /plan eine Planungssitzung startet, in der Copilot CLI den Code erkunden kann, aber daran gehindert wird, Projektdateien zu bearbeiten.

/plan an xUnit suite in tests/LogArchiver.Tests for LogBundle.Create.
Each test copies the logs folder to a temp directory and writes its bundles there.

Read each bundle back in two ways:
- unpacked by IronZIP into an empty folder
- listed with System.Formats.Tar over a GZipStream, which needs no IronZIP

The suite shows each of these points:
- The 2026-10-10 bundle has one top-level entry per service log plus manifest.txt.
- No entry name is repeated.
- Each unpacked log matches its source by SHA-256.
- The rotated .log.1 file and other days are left out.
- A day without logs writes nothing.
- Only the bundle remains in the output folder.

After I approve the plan, write the tests and run them with dotnet test.
Tell me how many passed and how many failed.
Text

Warum schreibt das Wiederherstellen eines alten TARs außerhalb seines Ordners?

Bündel vor 2026 sind einfache TAR-Dateien, und der Wiederherstellungsbefehl eines Teamkollegen entpackt sie mit IronTarArchive.ExtractArchiveToDirectory. In einer Untersuchung schrieb dieser Aufruf einen Eintrag namens ../escaped-dotdot.txt in den Ordner über dem Ziel und einen mit einem absoluten Namen zum Wurzelverzeichnis des Laufwerks. ExtractTGZArchiveToDirectory verweigerte denselben ../ Eintrag mit InvalidNameException, jedoch erst nach dem Entpacken der vorherigen Einträge.

Ein Setup-Commit fügt RestoreCommand.cs, RestoreTests.cs und zwei TAR-Dateien unter TestData/restore hinzu.

A teammate added @src/LogArchiver/Archiving/RestoreCommand.cs.
It restores the plain .tar archives kept from before 2026.
RestoreTests now fails on TestData/restore/hostile.tar.

Before changing any code, do these three things:
1. Run that test.
2. Print the entry names IronZIP reports for both .tar files in TestData/restore.
3. Explain how a file ends up outside the target folder.

Then fix it in RestoreCommand.cs alone.
An archive with any entry that would be written outside the target must be refused.
Refuse it before a single file is written.
Leave TestData and the tests untouched.
Run dotnet test and report the result.
Text

Eine Referenzkorrektur, die für die Kalibrierung geschrieben wurde, las die Namen mit GetArchiveEntryNames, verweigerte alle, die sich außerhalb des Ziels auflösten, und bestand beide Wiederherstellungstests.

Was macht ein Problem aus, auf das der Cloud-Agent reagieren kann?

Der Cloud-Agent sieht den Titel, die Beschreibung, vorhandene Kommentare und zusätzliche Anweisungen eines zugewiesenen Problems. GitHub sagt, der Agent sieht keine Kommentare, die nach der Zuordnung hinzugefügt wurden, daher steht der Akzeptanztest im Body des Problems.

Title: Write a .tar.bz2 copy of each bundle for cold storage

This issue touches the following:
- Files: src/LogArchiver/Archiving/LogBundle.cs, tests/LogArchiver.Tests
- IronZIP version: whatever Directory.Packages.props pins
- Target framework: .NET 9

After the change, the bundle command behaves like this:
- bundle <date> also writes out/cold/logs-<date>.tar.bz2.
- That file holds the same TAR as the .tar.gz.
- The pull request text proposes the matching docs/bundle-format.md rule.
- That rule goes in a separate pull request.

Today, cold storage bills by size and receives the .tar.gz only.

The work stays inside these limits:
- Build the TAR once and compress that one file twice.
- Use IronGZipArchive and IronBZip2Archive for the two copies.
- Keep the .tar.gz unchanged.
- No new packages.

The issue is done when these checks pass:
- dotnet test passes.
- A new test unpacks the .tar.bz2 with IronBZip2Archive.ExtractArchiveToDirectory.
- It unpacks into an empty folder.
- It finds every log and manifest.txt identical to the .tar.gz contents.
Markdown

IronBZip2Archive nimmt keine Komprimierungsstufe, und sein ExtractArchiveToDirectory entpackte eine .tar.bz2 direkt in die Dateien im TAR.

Warum scheitern die Tests des Cloud-Agenten bei einem IronZIP-Projekt?

Der Cloud-Agent arbeitet standardmäßig auf Ubuntu Linux. IronZIP liefert eine einzelne .NET Standard 2.0 Assembly, und weder sein Paket noch IronSoftware.Common, seine einzige Abhängigkeit, enthält eine native Binärdatei, daher benötigt der Runner nur eine Wiederherstellung. Ohne ein Agents-Geheimnis ist IRONZIP_LICENSE_KEY auf dem Runner nicht gesetzt. Ohne Schlüssel warf IronTarArchive.Add LicensingException mit "Production License Required", und SaveAs auf demselben Archiv schrieb immer noch einen 10.240-Byte TAR ohne Einträge. Ein Code, der die Ausnahme abfängt und fortfährt, schreibt leere Bündel.

Copilot beginnt die Arbeit, nachdem der copilot-setup-steps Job beendet ist, und GitHub löst diesen Job nur aus, wenn .github/workflows/copilot-setup-steps.yml im Standardzweig vorhanden ist.

Write the cloud agent's setup file, .github/workflows/copilot-setup-steps.yml.

The file holds one job with these settings:
- Name the job copilot-setup-steps.
- Give it contents: read.
- Run it on workflow_dispatch plus pull requests that edit this file.

The job runs these steps in order:
1. Fetch the repository.
2. Set up the .NET 9 SDK.
3. Restore.
4. Build the solution in Release.
5. Print tar --version, since the agent can compare its bundles with GNU tar.
6. Print a warning that names IRONZIP_LICENSE_KEY when that variable is empty.

IronZIP will not add entries without the key, which is why step 6 warns.
Step 6 always exits 0.
Print the YAML.
Text

Speichern Sie den Schlüssel unter dem Reiter Agents von Geheimnisse und Variablen, unter Sicherheit in den Einstellungen des Repositorys, da der Cloud-Agent keine Aktionen, Codespaces oder Dependabot-Geheimnisse sehen kann.

Was sollten Sie prüfen, bevor Sie zusammenführen?

Die Dokumentation von GitHub zeigt, dass /review an copilot -p weitergegeben wird, sodass die Überprüfung in einer eigenen Sitzung läuft, getrennt von der Kodiersitzung.

/review every commit after the first on this branch.
Compare those commits with docs/bundle-format.md and the two instruction files in .github.

Report each of these:
- an IronTarArchive.Add whose path does not already end in the final entry name
- a GetArchiveEntryNames on an archive that was never saved or opened
- an Add after SaveAs
- any unpacking into a folder that may hold files already
- an IronTarArchive.ExtractArchiveToDirectory without a check of every entry name first
- a catch that could hide a LicensingException
- an IronZIP member absent from IronZip.xml in the NuGet cache

Give the file and line of each finding, and modify nothing.
Text

Was haben die Aufforderungen in einem realen Lauf erzeugt?

Copilot CLI erhielt die sechs Eingabeaufforderungen in Reihenfolge, unbeaufsichtigt, die ersten fünf in einer Sitzung und die Überprüfungsaufforderung in einem separaten Copilot -p Aufruf. Das Ziel war eine .NET 9 Protokoll-Lösung, die für diesen Leitfaden erstellt wurde, mit sieben Protokollen über vier Dienste, einem Konsolenjob, der sie nur zählte, einem leeren xUnit-Projekt und dem Formatdokument. Jede Figur unten außer den Überprüfungsbefunden und dem letzten Aufzählungspunkt stammt aus Überprüfungen, die nach dem Ende der Sitzung durchgeführt wurden. Die Akzeptanz-Aufforderung im Leitfaden für KI-Coding-Assistenten überprüft ZIP- und .tgz-Archive auf die gleiche Weise, durch unterscheidbare Eintragsnamen und durch SHA-256 nach dem Extrahieren.

  • Der Format-Prüfer bestand 2 von 4 Überprüfungen beim unangetasteten Job, der kein Bündel schrieb.
  • Nach der ersten Aufforderung bestand der Prüfer 24 von 24 Überprüfungen für den 10., 9. und 8. Oktober.
  • Das Bündel vom 10. Oktober enthielt fünf Einträge, die vier Protokolle unter dienst-spezifischen Namen und manifest.txt.
  • Der Prüfer bestand immer noch 24 von 24 nach der letzten Aufforderung.
  • Bei dem Bündel vom 10. Oktober zählte der Überprüfungsbefehl 4 Protokolle und beendete mit 0.
  • Eine Kopie mit invertiertem mittleren Byte ließ den Befehl mit 1 auf dem TarException enden.
  • Keine der beiden Ausführungen des Befehls hinterließ einen temporären Ordner.
  • Beide Tests der geplanten Suite bestanden.
  • Einer dieser Tests scheiterte an einer Kopie des endgültigen Codes, die die Protokolle direkt aus ihren Dienstordnern hinzufügte.
  • Das Setup-Commit ließ die Wiederherstellungstests bei 1 bestanden und 1 fehlgeschlagen, und hostile.tar warf keine Ausnahme.
  • Die Wiederherstellungsaufforderung änderte RestoreCommand.cs und keine andere Datei.
  • Beide Wiederherstellungstests wurden nach dieser Aufforderung bestanden.
  • Der Setup-Workflow wurde als ein Copilot-Setup-Schritte-Job von 6 Schritten geparst, mit der Schlüsselüberprüfung als letztem.
  • Der finale Release-Build beendete mit 0 Warnungen und 0 Fehlern.
  • Die Überprüfung ließ jede Datei unverändert und meldete drei Befunde, einer davon eine Wiederherstellung in einen Ordner, von dem der Code nie überprüft hat, dass er leer war.
  • Einige Schritte liefen anders als die Seite. Die Plan-Aufforderung lief im Plan-Modus mit Autopilot, sodass Copilot CLI seinen eigenen Plan genehmigte. Seine Tests lasen Eintragsnamen mit System.Formats.Tar und verglichen Hashes der von IronZIP entpackten Dateien. Die eigene beschädigte Kopie des Copilot CLI hatte ein Bit gekippt, wurde ohne Ausnahme entpackt und fiel bei drei SHA-256-Unstimmigkeiten durch. Die Aufgabe, der Cloud-Agent, der Setup-Workflow auf Aktionen und das Agents-Geheimnis benötigen ein GitHub-Repository, daher hat keiner von ihnen ausgeführt.

Der Cursor-Leitfaden portiert ZIP-Bündelcode auf IronZIP, wo Add auch den Ordner von jedem Eintragsnamen entfernt, und sein portiertes Bündel enthielt 7 Einträge, jeweils unter einem einzigartigen flachen Namen. Der Google-Antigravitations-Leitfaden überprüft ebenfalls jedes Archiv, indem es mit IronZIP extrahiert wird und jede Datei mit SHA-256 verglichen wird. Der geteilte Laufbericht listet die Version von Copilot CLI, das Modell, die Laufzeit und die Testmaschine für diesen Leitfaden auf.


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