Comment utiliser IronZIP avec GitHub Copilot
Certains systèmes .NET écrivent des logs dans un dossier par service, et leur équipe d'opérations veut chacun d'eux sous forme de .tar.gz pour les copier sur un hôte Linux et les décompresser avec tar -xzf. Le travail qui construit ces ensembles appartient à la même solution Visual Studio que les services.
Copilot CLI peut construire ce travail dans un terminal, Copilot Chat et le mode agent peuvent le construire à l'intérieur de Visual Studio ou VS Code, et l'agent cloud peut transformer un problème GitHub à ce sujet en une demande de pull. IronZIP écrit et décompresse le TAR et le GZIP depuis .NET, et deux fichiers d'instructions dans le dépôt indiquent à chaque interface Copilot de ce guide comment se comportent ses appels TAR.
L'exemple de création de TAR, l'exemple de création de GZIP et l'exemple d'extraction de GZIP montrent les appels sur lesquels ce guide se base.
Démarrage rapideDémarrez copilot à la racine de la solution et envoyez cette invite. Copilot Chat dans Visual Studio nomme les fichiers avec # là où le CLI utilise @.
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.
Le fichier d'instructions spécifique au chemin indique la règle de nommage TAR d'IronZIP, donc l'invite l'omet.
Stockez la clé dans la variable d'environnement IRONZIP_LICENSE_KEY ou un secret du dépôt, hors des invites et des commits. Dans une sonde qui a seulement défini cette variable, License.IsLicensed a renvoyé faux, donc Program.cs copie la valeur dans IronZip.License.LicenseKey. Pour définir la clé dans un fichier de configuration à la place, suivez le guide de la clé de licence. Laissez la protection de la branche et une approbation humaine activées pour les demandes de pull de l'agent cloud.
Flux de travail minimal (5 étapes)
- Téléchargez la bibliothèque ZIP C# depuis NuGet
- Enregistrez les règles TAR d'IronZIP dans .github/copilot-instructions.md plus un fichier d'instructions spécifiques au chemin
- Copiez chaque log sous son nom d'entrée final, construisez le TAR, puis enveloppez-le dans GZIP
- Décompressez chaque ensemble dans un dossier vide lors des tests et comparez chaque fichier par SHA-256
- Déposez le prochain changement comme un problème pour l'agent cloud et révisez sa demande de pull avec la référence API
Comment définir les conventions IronZIP pour Copilot ?
La référence de support de GitHub liste .github/copilot-instructions.md pour Copilot CLI, pour l'agent cloud et pour Copilot Chat à la fois dans Visual Studio et VS Code, donc le package, la licence et les règles de test y vont. Visual Studio ignore le fichier tant que la case à cocher des instructions personnalisées dans ses options de Copilot Chat n'est pas sélectionnée.
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.
Comment pouvez-vous donner ses propres règles au code d'archivage ?
Enregistrez les règles d'archive sous .github/instructions/archives.instructions.md. GitHub documente que Copilot CLI inclut un fichier spécifique au chemin uniquement lorsque sa valeur applyTo correspond à un fichier avec lequel le CLI travaille. La commande /instructions liste les fichiers d'instructions que le CLI a trouvés et active ou désactive chacun d'eux.
---
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.
Que conserve l'écrivain TAR d'IronZIP d'un chemin de fichier ?
Chaque service nomme ici son log d'après le jour, donc logs/api/2026-10-10.log et logs/worker/2026-10-10.log partagent un nom de fichier. Ajoutés directement à partir de leurs dossiers avec IronZIP 2026.10.2, les quatre logs pour le 10 octobre sont devenus quatre entrées TAR nommées 2026-10-10.log. tar -tvzf a listé les quatre, et rien n'a échoué. Décompressé avec IronZIP, l'ensemble contenait un 2026-10-10.log de 19 813 octets, le log du worker ajouté en dernier.
Avec chaque log mis en scène comme une copie nommée pour son service, tel que worker-2026-10-10.log, les ensembles pour le 10 et le 9 octobre et le 8 octobre vide ont passé les 24 vérifications d'un vérificateur de format Python qui lit les ensembles sans IronZIP. Chaque entrée avait le mode 700, le propriétaire 0 et l'heure de la sauvegarde plutôt que le propre horodatage du fichier. Deux ensembles des mêmes logs construits deux secondes de différence divergeaient à partir du cinquième octet, là où GZIP stocke son temps.
Comment vérifier un ensemble après qu'il est écrit ?
Pointé vers un dossier utilisé, ExtractTGZArchiveToDirectory a remplacé les fichiers du même nom et conservé le reste, donc une vérification qui réutilise un dossier peut compter un fichier obsolète.
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.
Dans la sonde de calibration, l'octet inversé a fait lancer à IronZIP une TarException ("Checksum d'en-tête invalide") après avoir déjà écrit le premier log, donc une décompression échouée peut laisser un dossier partiel.
Comment tester un ensemble IronZIP ?
Un test qui lit chaque ensemble avec System.Formats.Tar ainsi qu'IronZIP attrape une faute de nommage qu'une décompression IronZIP cache. La référence CLI de GitHub dit que /plan commence une session de planification dans laquelle Copilot CLI peut explorer le code mais est bloqué pour éditer les fichiers du projet.
/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.
Pourquoi restaurer un ancien TAR écrit en dehors de son dossier ?
Les ensembles d'avant 2026 sont des fichiers TAR simples, et la commande de restauration d'un collègue les décompresse avec IronTarArchive.ExtractArchiveToDirectory. Dans une sonde, cet appel a écrit une entrée nommée ../escaped-dotdot.txt dans le dossier au-dessus de la cible, et une avec un nom absolu à la racine du lecteur. ExtractTGZArchiveToDirectory a refusé la même entrée ../ avec InvalidNameException, bien que seulement après avoir décompressé les entrées avant elle.
Un commit de configuration ajoute RestoreCommand.cs, RestoreTests.cs et deux fichiers TAR sous TestData/restore.
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.
Une correction de référence écrite pour la calibration a lu les noms avec GetArchiveEntryNames, refusé ceux qui résolvaient en dehors de la cible, et réussi les deux tests de restauration.
Qu'est-ce qui rend un problème sur lequel l'agent cloud peut agir ?
L'agent cloud voit le titre d'un problème assigné, la description, les commentaires existants et des instructions supplémentaires. GitHub dit que l'agent ne voit pas les commentaires ajoutés après l'assignation, donc le test d'acceptation est placé dans le corps du problème.
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.
IronBZip2Archive ne prend aucun niveau de compression, et sa ExtractArchiveToDirectory a décompressé un .tar.bz2 directement vers les fichiers à l'intérieur du TAR.
Pourquoi les tests de l'agent cloud échouent-ils sur un projet IronZIP ?
L'agent cloud fonctionne par défaut sur Ubuntu Linux. IronZIP fournit un seul assemblage .NET Standard 2.0, et ni son package ni IronSoftware.Common, sa seule dépendance, n'inclut un binaire natif, donc une restauration est tout ce dont le coureur a besoin. Sans secret d'Agents, IRONZIP_LICENSE_KEY n'est pas défini sur le coureur. Sans clé, IronTarArchive.Add a lancé LicensingException avec "Licence de production requise", et SaveAs sur le même archive a quand même écrit un TAR de 10 240 octets sans entrée. Le code qui attrape l'exception et continue écrit des ensembles vides.
Copilot commence le travail après que le travail copilot-setup-steps soit terminé, et GitHub ne déclenche ce travail que lorsque .github/workflows/copilot-setup-steps.yml est présent sur la branche par défaut.
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.
Enregistrez la clé sous l'onglet Agents de Secrets et variables, sous Sécurité dans les Paramètres du dépôt, car l'agent cloud ne peut pas voir les secrets des Actions, des Codespaces ou de Dependabot.
Que faut-il vérifier avant de fusionner ?
La documentation de GitHub montre /review passée à copilot -p, donc la révision s'exécute dans sa propre session, séparée de la session de codage.
/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.
Qu'est-ce que les messages ont produit lors d'une réelle exécution ?
Copilot CLI a reçu les six invites dans l'ordre, sans surveillance, les cinq premières dans une session et l'invite de révision dans un appel copilot -p séparé. La cible était une solution de log .NET 9 créée pour ce guide, avec sept logs répartis sur quatre services, un travail de console qui ne faisait que les compter, un projet xUnit vide et le document de format. Toutes les figures ci-dessous sauf les résultats de la révision et la dernière puce proviennent de vérifications effectuées après la fin de la session. L'invite d'acceptation dans le guide des assistants de codage AI vérifie les archives ZIP et .tgz de deux manières identiques, par des noms d'entrée distincts et par SHA-256 après extraction.
- Le vérificateur de format est passé 2 des 4 vérifications sur le travail inchangé, qui n'a écrit aucun ensemble.
- Après la première invite, le vérificateur est passé 24 des 24 vérifications pour le 10, 9 et 8 octobre.
- L'ensemble du 10 octobre contenait cinq entrées, les quatre logs sous les noms préfixés par le service et manifest.txt.
- Le vérificateur a toujours passé 24 des 24 après la dernière invite.
- Sur l'ensemble du 10 octobre, la commande de vérification a compté 4 logs et s'est terminée à 0.
- Une copie avec son octet du milieu inversé a fait que la commande s'est terminée à 1 sur la TarException.
- Aucune exécution de la commande n'a laissé un dossier temporaire.
- Les deux tests de la suite planifiée ont réussi.
- Un de ces tests a échoué sur une copie du code final qui ajoutait les logs directement à partir de leurs dossiers de service.
- Le commit de configuration a laissé les tests de restauration à 1 réussi et 1 échoué, et hostile.tar n'a lancé aucune exception.
- L'invite de restauration a changé RestoreCommand.cs et aucun autre fichier.
- Les deux tests de restauration ont réussi après cette invite.
- Le workflow de mise en place a été analysé comme un travail copilot-setup-steps de 6 étapes, avec la vérification de la clé en dernier.
- La construction finale Release s'est terminée avec 0 avertissements et 0 erreurs.
- La révision a laissé chaque fichier inchangé et a rapporté trois constatations, dont une restauration dans un dossier que le code n'a jamais vérifié s'il était vide.
- Certaines étapes ont été exécutées différemment de la page. L'invite de plan s'est exécuté en mode plan avec autopilote, donc Copilot CLI a approuvé son propre plan. Ses tests ont lu les noms d'entrée avec System.Formats.Tar et comparé les hachages sur les fichiers décompressés par IronZIP. La propre copie corrompue de Copilot CLI avait un bit inversé, décompressé sans exception et échoué sur trois mauvais correspondances SHA-256. Le problème, l'agent cloud, le workflow de mise en place sur Actions et le secret des Agents ont besoin d'un dépôt GitHub, donc aucun d'eux n'a fonctionné.
Le guide Cursor porte le code du bundle ZIP à IronZIP, où Add enlève également le dossier de chaque nom d'entrée, et son bundle porté contenait 7 entrées, chacune sous un nom plat unique. Le guide Google Antigravity vérifie également chaque archive en la décompressant avec IronZIP et en comparant chaque fichier par SHA-256. Le dossier d'exécution partagé liste la version de Copilot CLI, le modèle, le temps d'exécution et la machine de test pour ce guide.
Dépannage
- Créer TAR pour ajouter des fichiers à une archive TAR
- Créer GZIP pour compresser un TAR terminé
- Extraire GZIP pour décompresser un .tar.gz en un seul appel
- Extraire TAR pour décompresser un TAR simple
- Clés de licence IronZIP lorsqu'un test lance LicensingException
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.