Como Usar IronZIP com GitHub Copilot

Curtis Chau
Curtis Chau
Atualizado: 26 de outubro de 2026

Alguns sistemas .NET gravam logs em uma pasta por serviço, e sua equipe de operações quer cada dia deles como um .tar.gz para copiar para um host Linux e descompactar com tar -xzf. O trabalho que constrói esses pacotes pertence à mesma solução do Visual Studio que os serviços.

O Copilot CLI pode construir esse trabalho em um terminal, o modo de chat e agente do Copilot pode construí-lo dentro do Visual Studio ou VS Code, e o agente na nuvem pode transformar um problema do GitHub sobre isso em uma solicitação de pull. O IronZIP escreve e descompacta o TAR e o GZIP do .NET, e dois arquivos de instrução no repositório informam a todas as superfícies do Copilot neste guia como suas chamadas TAR se comportam.

O exemplo de criação de TAR, o exemplo de criação de GZIP e o exemplo de extração de GZIP mostram as chamadas nas quais este guia se baseia.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronZip

Instale o IronZIP executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Inicie copilot na raiz da solução e envie este prompt. O Copilot Chat no Visual Studio nomeia arquivos com # onde o 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.
Text

O arquivo de instrução específico do caminho indica a regra de nomenclatura do TAR do IronZIP, para que o prompt a omita.

Armazene a chave na variável de ambiente IRONZIP_LICENSE_KEY ou em um segredo do repositório, fora dos prompts e commits. Em uma sonda que definiu apenas essa variável, License.IsLicensed retornou falso, então Program.cs copia o valor para IronZip.License.LicenseKey. Para definir a chave em um arquivo de configuração, siga o guia de chave de licença. Deixe a proteção de branch e uma aprovação humana ativadas para as pull requests do agente em nuvem.



Como você configura as convenções do IronZIP para o Copilot?

A referência de suporte do GitHub lista .github/copilot-instructions.md para o Copilot CLI, para o agente da nuvem e para o Copilot Chat no Visual Studio e no VS Code, portanto, o pacote, a licença e as regras de teste vão para lá. O Visual Studio ignora o arquivo até que a caixa de seleção de instruções personalizadas nas opções de Chat do Copilot seja selecionada.

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

Como você dá ao código do arquivo suas próprias regras?

Salve as regras do arquivo como .github/instructions/archives.instructions.md. O GitHub documenta que o Copilot CLI inclui um arquivo específico do caminho apenas quando seu valor applyTo corresponde a um arquivo com o qual o CLI está trabalhando. O comando /instructions lista os arquivos de instrução que o CLI encontrou e ativa ou desativa cada um.

---
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

O que o escritor TAR do IronZIP mantém de um caminho de arquivo?

Cada serviço aqui nomeia seu log após o dia, então logs/api/2026-10-10.log e logs/worker/2026-10-10.log compartilham um nome de arquivo. Adicionados diretamente de suas pastas com IronZIP 2026.10.2, os quatro logs de 10 de outubro se tornaram quatro entradas TAR nomeadas 2026-10-10.log. tar -tvzf listou todos os quatro, e nada foi lançado. Desempacotado com IronZIP, o pacote continha um 2026-10-10.log de 19.813 bytes, o log do worker adicionado por último.

Com cada log agendado como uma cópia nomeada pelo seu serviço, como worker-2026-10-10.log, os pacotes de 10 e 9 de outubro e o vazio de 8 de outubro passaram em todas as 24 verificações de um verificador de formato Python que lê pacotes sem IronZIP. Cada entrada tinha modo 700, proprietário 0 e o tempo do salvamento em vez do carimbo de data e hora do próprio arquivo. Dois pacotes dos mesmos logs construídos com dois segundos de diferença variaram a partir do quinto byte, onde o GZIP armazena seu tempo.

Como você verifica um pacote depois que ele é escrito?

Apontado para uma pasta usada, ExtractTGZArchiveToDirectory substituiu arquivos com o mesmo nome e manteve o resto, então uma verificação que reutiliza uma pasta pode contar um arquivo 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.
Text

Na sonda de calibração, o byte invertido fez o IronZIP lançar TarException ("Header checksum is invalid") depois que já havia escrito o primeiro log, então uma descompactação falhada pode deixar uma pasta parcial.

Como você testa um pacote IronZIP?

Um teste que lê cada pacote com System.Formats.Tar, assim como o IronZIP, captura uma falha de nomenclatura que uma descompactação do IronZIP oculta. A referência CLI do GitHub diz que /plan inicia uma sessão de planejamento em que o Copilot CLI pode explorar o código, mas está bloqueado para editar arquivos do projeto.

/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

Por que restaurar um TAR antigo escreve fora de sua pasta?

Pacotes de antes de 2026 são arquivos TAR simples, e o comando de restauração de um colega os descompacta com IronTarArchive.ExtractArchiveToDirectory. Em uma sonda, essa chamada escreveu uma entrada nomeada ../escaped-dotdot.txt na pasta acima do destino, e outra com um nome absoluto para a raiz do drive. ExtractTGZArchiveToDirectory recusou a mesma entrada ../ com InvalidNameException, embora apenas após desempacotar as entradas anteriores.

Um commit de configuração adiciona RestoreCommand.cs, RestoreTests.cs e dois arquivos TAR sob 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.
Text

Uma correção de referência escrita para calibração leu os nomes com GetArchiveEntryNames, recusou qualquer um que resolvesse fora do destino e passou em ambos os testes de restauração.

O que faz de um problema algo que o agente de nuvem pode atuar?

O agente na nuvem vê o título da issue atribuída, descrição, comentários existentes e instruções adicionais. O GitHub diz que o agente não vê comentários adicionados após a atribuição, então o teste de aceitação vai no corpo da issue.

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 não aceita nível de compressão, e seu ExtractArchiveToDirectory descompactou um .tar.bz2 diretamente para os arquivos dentro do TAR.

Por que os testes do agente na nuvem falham em um projeto IronZIP?

O agente na nuvem trabalha no Ubuntu Linux por padrão. O IronZIP envia um único assembly .NET Standard 2.0, e nem seu pacote nem IronSoftware.Common, sua única dependência, incluem um binário nativo, então uma restauração é tudo o que o executor precisa. Sem um segredo dos Agentes, IRONZIP_LICENSE_KEY não é configurado no executor. Sem chave, IronTarArchive.Add lançou LicensingException com "Produção Licença Requerida", e SaveAs no mesmo arquivo ainda escreveu um TAR de 10.240 bytes sem entradas. Código que captura a exceção e continua escreve pacotes vazios.

O Copilot começa a trabalhar após o término do trabalho copilot-setup-steps, e o GitHub aciona esse trabalho apenas quando .github/workflows/copilot-setup-steps.yml está presente no branch padrão.

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

Salve a chave na guia Agentes de Segredos e variáveis, em Segurança nas Configurações do repositório, porque o agente na nuvem não pode ver segredos de Actions, Codespaces ou Dependabot.

O que você deve verificar antes de fazer o merge?

A documentação do GitHub mostra /review passado para copilot -p, então a revisão é executada em sua própria sessão, separada da sessão de codificação.

/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

O que os prompts produziram em uma execução real?

O Copilot CLI recebeu os seis prompts em ordem, sem supervisão, os primeiros cinco em uma sessão e o prompt de revisão em uma chamada copilot -p separada. O alvo era uma solução de log .NET 9 feita para este guia, com sete logs distribuídos em quatro serviços, um trabalho de console que apenas os contava, um projeto xUnit vazio e o documento de formato. Cada figura abaixo, exceto os achados da revisão e o último ponto, vem de verificações realizadas após o término da sessão. O prompt de aceitação no guia de assistentes de codificação AI verifica arquivos ZIP e .tgz da mesma forma em duas abordagens, por nomes de entrada distintos e por SHA-256 após a extração.

  • O verificador de formato aprovou 2 de 4 verificações no trabalho intocado, que não escreveu nenhum pacote.
  • Após o primeiro prompt, o verificador aprovou 24 de 24 verificações para 10, 9 e 8 de outubro.
  • O pacote de 10 de outubro continha cinco entradas, os quatro logs sob nomes prefixados por serviços e manifest.txt.
  • O verificador ainda aprovou 24 de 24 após o último prompt.
  • No pacote de 10 de outubro, o comando verificar contou 4 logs e saiu com 0.
  • Uma cópia com seu byte do meio invertido fez o comando sair com 1 na TarException.
  • Nenhuma das execuções do comando deixou uma pasta temporária.
  • Ambos os testes da suíte planejada passaram.
  • Um desses testes falhou em uma cópia do código final que adicionou os logs diretamente de suas pastas de serviço.
  • O commit de configuração deixou os testes de restauração com 1 aprovado e 1 falhou, e hostile.tar não lançou nenhuma exceção.
  • O prompt de restauração alterou RestoreCommand.cs e nenhum outro arquivo.
  • Ambos os testes de restauração passaram após esse prompt.
  • O fluxo de trabalho de configuração foi analisado como um trabalho de 6 etapas copilot-setup-steps, com a verificação da chave por último.
  • A última build de lançamento terminou com 0 avisos e 0 erros.
  • A revisão deixou todos os arquivos inalterados e relatou três achados, um deles uma restauração em uma pasta que o código nunca verificou estava vazia.
  • Alguns passos foram executados de forma diferente da página. O prompt de plano rodou no modo plano com piloto automático, então o Copilot CLI aprovou seu próprio plano. Seus testes leram nomes de entrada com System.Formats.Tar e compararam hashes nos arquivos que o IronZIP descompactou. A própria cópia corrompida do Copilot CLI tinha um bit invertido, descompactado sem exceção e falhou em três discordâncias de SHA-256. A issue, o agente na nuvem, o fluxo de trabalho de configuração em Ações e o segredo de Agentes precisam de um repositório no GitHub, então nenhum deles foi executado.

O guia do Cursor porta o código do pacote ZIP para o IronZIP, onde Add também remove a pasta de cada nome de entrada, e seu pacote portado continha 7 entradas, cada uma com um nome simples único. O guia do Google Antigravity também verifica cada arquivo extraindo-o com IronZIP e comparando cada arquivo por SHA-256. O registro de execução compartilhado lista a versão do Copilot CLI, o modelo, o tempo de execução e a máquina de teste para este guia.


Solução de problemas


Questões?

Se você tiver dúvidas, entre em contato com support@ironsoftware.com

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Pronto para começar?

Downloads no NuGet 25,383Versão:2026.11recém-lançado