Cómo usar IronZIP con GitHub Copilot
Algunos sistemas .NET escriben registros en una carpeta por servicio, y su equipo de operaciones quiere que cada día de ellos sea un .tar.gz para copiarlo a un host Linux y descomprimirlo con tar -xzf. El trabajo que construye esos paquetes pertenece a la misma solución de Visual Studio que los servicios.
Copilot CLI puede construir ese trabajo en un terminal, Copilot Chat y el modo agente pueden construirlo dentro de Visual Studio o VS Code, y el agente en la nube puede convertir un problema de GitHub sobre él en una solicitud de extracción. IronZIP escribe y descomprime el TAR y el GZIP desde .NET, y dos archivos de instrucciones en el repositorio indican a cada superficie de Copilot en esta guía cómo se comportan sus llamadas TAR.
El ejemplo de crear TAR, el ejemplo de crear GZIP y el ejemplo de extraer GZIP muestran las llamadas en las que se basa esta guía.
Inicio rápidoInicia copilot en la raíz de la solución y envía este aviso. Copilot Chat en Visual Studio nombra archivos con # donde el CLI usa @.
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.
El archivo de instrucciones específico de la ruta establece la regla de nomenclatura TAR de IronZIP, por lo que el aviso lo omite.
Almacena la clave en la variable de entorno IRONZIP_LICENSE_KEY o en un secreto del repositorio, fuera de los avisos y los compromisos. En una sonda que solo configuró esa variable, License.IsLicensed devolvió falso, por lo que Program.cs copia el valor en IronZip.License.LicenseKey. Para configurar la clave en un archivo de configuración, sigue la guía de claves de licencia. Deja la protección de rama y la aprobación humana activadas para las solicitudes de extracción del agente en la nube.
Flujo de trabajo mínimo (5 pasos)
- Descargar la biblioteca ZIP de C# desde NuGet
- Registra las reglas TAR de IronZIP en .github/copilot-instructions.md más un archivo de instrucciones específico de la ruta.
- Copia cada registro bajo su nombre de entrada final, construye el TAR, luego envuélvelo en GZIP.
- Descomprime cada paquete en una carpeta vacía en las pruebas y compara cada archivo por SHA-256.
- Registra el siguiente cambio como un problema para el agente en la nube y revisa su solicitud de extracción con la referencia de API.
¿Cómo estableces las convenciones de IronZIP para Copilot?
La referencia de soporte de GitHub enumera .github/copilot-instructions.md para Copilot CLI, para el agente en la nube y para Copilot Chat tanto en Visual Studio como en VS Code, por lo que las reglas de paquete, licencia y prueba van allí. Visual Studio ignora el archivo hasta que se selecciona la casilla de verificación de instrucciones personalizadas en sus opciones de Copilot Chat.
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.
¿Cómo le das al código del archivo sus propias reglas?
Guarda las reglas del archivo como .github/instructions/archives.instructions.md. GitHub documenta que Copilot CLI incluye un archivo específico de la ruta solo cuando su valor applyTo coincide con un archivo con el que el CLI está trabajando. El comando /instructions enumera los archivos de instrucciones que el CLI encontró y activa o desactiva cada uno.
---
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.
¿Qué retiene el escritor TAR de IronZIP de una ruta de archivo?
Cada servicio aquí nombra su registro por el día, por lo que logs/api/2026-10-10.log y logs/worker/2026-10-10.log comparten un nombre de archivo. Agregados directamente desde sus carpetas con IronZIP 2026.10.2, los cuatro registros para el 10 de octubre se convirtieron en cuatro entradas TAR nombradas 2026-10-10.log. tar -tvzf enumeró los cuatro, y nada lanzó errores. Descomprimido con IronZIP, el paquete contenía un 2026-10-10.log de 19,813 bytes, el registro de trabajador agregado al final.
Con cada registro preparado como una copia nombrada para su servicio, como worker-2026-10-10.log, los paquetes para el 10 y el 9 de octubre y el vacío del 8 de octubre pasaron las 24 verificaciones de un verificador de formato Python que lee paquetes sin IronZIP. Cada entrada tenía modo 700, propietario 0 y la hora del guardado en lugar del propio timestamp del archivo. Dos paquetes de los mismos registros construidos con dos segundos de diferencia difirieron desde el quinto byte, donde GZIP almacena su tiempo.
¿Cómo verificas un paquete después de que se escribe?
Apuntado a una carpeta usada, ExtractTGZArchiveToDirectory reemplazó archivos del mismo nombre y mantuvo el resto, por lo que una verificación que reutiliza una carpeta puede contar un archivo obsoleto.
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.
En la sonda de calibración, el byte invertido hizo que IronZIP lanzara TarException ("El checksum del encabezado no es válido") después de que ya había escrito el primer registro, por lo que un fallo en la descompresión puede dejar una carpeta parcial.
¿Cómo pruebas un paquete de IronZIP?
Una prueba que lee cada paquete con System.Formats.Tar además de IronZIP detecta un error de nomenclatura que una descompresión con IronZIP oculta. La referencia del CLI de GitHub dice /plan empieza una sesión de planificación en la que Copilot CLI puede explorar el código pero está bloqueado para editar archivos del proyecto.
/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.
¿Por qué al restaurar un TAR antiguo se escribe fuera de su carpeta?
Los paquetes de antes de 2026 son archivos TAR simples, y el comando de restauración de un compañero los descomprime con IronTarArchive.ExtractArchiveToDirectory. En una sonda, esa llamada escribió una entrada nombrada ../escaped-dotdot.txt en la carpeta por encima del objetivo, y otra con un nombre absoluto hacia la raíz del disco. ExtractTGZArchiveToDirectory rechazó la misma entrada ../ con InvalidNameException, aunque solo después de descomprimir las entradas anteriores.
Un commit de configuración agrega RestoreCommand.cs, RestoreTests.cs y dos archivos TAR en 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.
Una corrección de referencia escrita para la calibración leyó los nombres con GetArchiveEntryNames, rechazó cualquiera que se resolviera fuera del objetivo, y pasó ambas pruebas de restauración.
¿Qué hace que un problema sea en el que el agente de la nube pueda actuar?
El agente en la nube ve el título, la descripción, los comentarios existentes y las instrucciones adicionales de un problema asignado. GitHub dice que el agente no ve los comentarios añadidos después de la asignación, por lo que la prueba de aceptación va en el cuerpo del problema.
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 no toma nivel de compresión, y su ExtractArchiveToDirectory descomprimió un .tar.bz2 directamente a los archivos dentro del TAR.
¿Por qué fallan las pruebas del agente en la nube en un proyecto de IronZIP?
El agente en la nube trabaja en Ubuntu Linux por defecto. IronZIP envía un único ensamblaje .NET Standard 2.0, y ni su paquete ni IronSoftware.Common, su única dependencia, incluyen un binario nativo, por lo que una restauración es todo lo que necesita el corredor. Sin un secreto de Agentes, IRONZIP_LICENSE_KEY no está configurado en el corredor. Sin una clave, IronTarArchive.Add lanzó LicensingException con "Se requiere Licencia de Producción", y SaveAs en el mismo archivo aún escribió un TAR de 10,240 bytes sin entradas. El código que captura la excepción y continúa escribe paquetes vacíos.
Copilot comienza a trabajar después de que el trabajo copilot-setup-steps termine, y GitHub activa ese trabajo solo cuando .github/workflows/copilot-setup-steps.yml está presente en la rama por defecto.
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.
Guarda la clave en la pestaña de Agentes de Secrets and variables, bajo Seguridad en la Configuración del repositorio, porque el agente en la nube no puede ver acciones, espacios de códigos o secretos de Dependabot.
¿Qué debes verificar antes de fusionar?
La documentación de GitHub muestra /review pasa a copilot -p, por lo que la revisión se ejecuta en su propia sesión, separada de la sesión de codificación.
/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é produjeron los prompts en una ejecución real?
Copilot CLI recibió los seis avisos en orden, sin supervisión, los primeros cinco en una sesión y el aviso de revisión en una llamada copilot -p separada. El objetivo era una solución de registro .NET 9 creada para esta guía, con siete registros en cuatro servicios, un trabajo de consola que solo los contaba, un proyecto xUnit vacío y el documento de formato. Cada figura a continuación, excepto los hallazgos de la revisión y la última viñeta, proviene de verificaciones ejecutadas después de que la sesión terminó. El aviso de aceptación en la guía de asistentes de codificación AI verifica los archivos ZIP y .tgz de dos maneras, por nombres de entradas distintos y por SHA-256 después de la extracción.
- El verificador de formato pasó 2 de 4 verificaciones en el trabajo intacto, que no escribió ningún paquete.
- Después del primer aviso, el verificador pasó 24 de 24 verificaciones para el 10, 9 y 8 de octubre.
- El paquete del 10 de octubre tenía cinco entradas, los cuatro registros bajo nombres con prefijo de servicio y manifest.txt.
- El verificador aún pasó 24 de 24 después del último aviso.
- En el paquete del 10 de octubre, el comando de verificación contó 4 registros y salió 0.
- Una copia con su byte medio invertido hizo que el comando saliera 1 en el TarException.
- Ninguna ejecución del comando dejó una carpeta temporal.
- Ambas pruebas del conjunto planeado pasaron.
- Una de esas pruebas falló en una copia del código final que agregó los registros directamente desde sus carpetas de servicio.
- El commit de configuración dejó las pruebas de restauración en 1 pasada y 1 fallida, y hostile.tar no lanzó ninguna excepción.
- El aviso de restauración cambió RestoreCommand.cs y ningún otro archivo.
- Ambas pruebas de restauración pasaron después de ese aviso.
- El flujo de trabajo de configuración se analizó como un trabajo de copilot-setup-steps de 6 pasos, con la verificación de clave al final.
- La compilación final Release terminó con 0 advertencias y 0 errores.
- La revisión dejó cada archivo sin cambios y reportó tres hallazgos, uno de ellos una restauración en una carpeta que el código nunca verificó que estuviera vacía.
- Algunos pasos se ejecutaron de manera diferente a lo esperado. El aviso de plan se ejecutó en modo plan con piloto automático, por lo que Copilot CLI aprobó su propio plan. Sus pruebas leyeron nombres de entrada con System.Formats.Tar y compararon hashes en los archivos descomprimidos por IronZIP. La propia copia corrupta de Copilot CLI tenía un bit invertido, desempaquetado sin excepción y falló en tres discordancias SHA-256. El problema, el agente en la nube, el flujo de trabajo de configuración en Acciones y el secreto de Agentes necesitan un repositorio de GitHub, por lo que ninguno de ellos se ejecutó.
La guía de Cursor lleva el código de paquetes ZIP a IronZIP, donde Agregar también deja caer la carpeta de cada nombre de entrada, y su paquete portado contenía 7 entradas, cada una bajo un nombre plano único. La guía de Antigravedad de Google también verifica cada archivo extrayéndolo con IronZIP y comparando cada archivo por SHA-256. El registro compartido de ejecución enumera la versión de Copilot CLI, el modelo, el tiempo de ejecución y la máquina de prueba para esta guía.
Solución de problemas
- Crear TAR para agregar archivos a un archivo TAR
- Crear GZIP para comprimir un TAR terminado
- Extraer GZIP para descomprimir un .tar.gz en una llamada
- Extraer TAR para descomprimir un TAR simple
- Claves de Licencia de IronZIP cuando una prueba lanza LicensingException
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.