如何在GitHub Copilot中使用IronZIP
.NET系统中的一些会将日志写入每个服务的一个文件夹中,他们的操作团队希望将它们的每天作为一个.tar.gz复制到Linux主机并用tar -xzf解压。 构建这些包的作业与服务属于同一个Visual Studio解决方案。
Copilot CLI可以在终端中构建该作业,Copilot Chat和代理模式可以在Visual Studio或VS Code中构建它,云代理可以将关于它的GitHub问题转化为请求。IronZIP从.NET中写入和解压TAR和GZIP,存储库中的两个指令文件告诉本指南中的每个Copilot界面TAR调用的行为。
创建TAR示例,创建GZIP示例和提取GZIP示例展示了本指南构建的调用。
快速入门在解决方案根目录启动copilot并发送此提示。 Visual Studio中的Copilot Chat以#为文件命名,而CLI使用@。
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.
路径特定的指令文件声明了IronZIP的TAR命名规则,因此提示中省去了它。
将密钥存储在IRONZIP_LICENSE_KEY环境变量或存储库机密中,避免在提示和提交中使用。 在仅设置该变量的探针中,License.IsLicensed返回false,因此Program.cs将值复制到IronZip.License.LicenseKey。 如果要在配置文件中设置密钥,请参见许可密钥指南。 为云代理的拉取请求保留分支保护和人工审核。
最小工作流程(5 个步骤)
- 从NuGet下载C# ZIP库
- 在.github/copilot-instructions.md中记录IronZIP的TAR规则以及一个路径特定的指令文件
- 复制每个日志至其最终条目名称后,构建TAR,然后用GZIP封装
- 将每个包解压到测试中的空文件夹中,并通过SHA-256比较每个文件
- 将下一个更改作为云代理的问题提交,并审查其拉取请求的API参考
如何为Copilot设置IronZIP约定?
GitHub的支持参考列出了Copilot CLI、云代理以及Visual Studio和VS Code中的Copilot Chat使用.github/copilot-instructions.md,因此将包、许可证和测试规则放在那里。 Visual Studio忽略该文件,直到在其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.
如何为存档代码设定自己的规则?
将存档规则保存为.github/instructions/archives.instructions.md。 GitHub文档显示,只有在其applyTo值与CLI正在处理的文件匹配时,Copilot CLI才会包含路径特定的文件。 /instructions命令列出了CLI找到的指令文件,并逐个启用或禁用。
---
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.
IronZIP的TAR写入器从文件路径中保留了什么?
这里每个服务都以日期对日志命名,因此logs/api/2026-10-10.log和logs/worker/2026-10-10.log共享一个文件名。 直接从他们的文件夹中添加的日志与IronZIP 2026.10.2,四个10月10日的日志成为了四个名为2026-10-10.log的TAR条目。 tar -tvzf列出了所有四个文件,没有抛出任何异常。 用IronZIP解压缩后,包中包含了一个大小为19,813字节的2026-10-10.log,这是最后添加的工作日志。
将每个日志作为其服务命名的副本,如worker-2026-10-10.log,将10月10日和9日的包以及空的10月8日全部通过一个Python格式检查器的24次检查,该检查器读取不使用IronZIP的包。每个条目的模式是700,所有者是0,保存时间而不是文件自身的时间戳。两秒间隔构建的相同日志的两个包从第五字节起不同,GZIP在此存储其时间。
如何在写入后检查包?
在一个用过的文件夹中,ExtractTGZArchiveToDirectory替换了同名文件并保留了其余文件,因此重用文件夹的检查可以统计过时文件。
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.
在校准探针中,翻转的字节导致IronZIP在已经写入第一个日志后抛出TarException("Header checksum is invalid"),因此解压失败可能导致部分文件夹。
如何测试IronZIP包?
一个用System.Formats.Tar和IronZIP读取每个包的测试捕获到了IronZIP解压隐藏的命名故障。 GitHub的CLI参考说/plan开始了一个计划会话,在此期间Copilot CLI可以探索代码,但被阻止编辑项目文件。
/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.
为什么恢复旧的TAR会写到其文件夹外?
2026年之前的包是普通的TAR文件,队友的还原命令用IronTarArchive.ExtractArchiveToDirectory解压了它们。 在探针中,那个调用写了一条命名为../escaped-dotdot.txt的条目到目标之上的文件夹中,还写了一条绝对名称的到驱动器的根目录。ExtractTGZArchiveToDirectory拒绝了同样的../条目,并抛出了InvalidNameException,不过是在解压前面的条目之后。
设置提交添加了RestoreCommand.cs、RestoreTests.cs和两个在TestData/restore下的TAR文件。
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.
用于校准的参考修复通过GetArchiveEntryNames读取了名称,拒绝了任何解析到目标之外的名称,并通过了两个还原测试。
是什么让云代理能够处理一个问题?
云代理看到已分配问题的标题、描述、现有评论和额外说明。 GitHub表示代理无法看到分配后的添加评论,因此验收测试应放在问题正文中。
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不接受压缩级别,并且其ExtractArchiveToDirectory直接将.tar.bz2解压至TAR内的文件。
云代理的测试为何在IronZIP项目上失败?
云代理默认在Ubuntu Linux上运行。 IronZIP提供了一个.NET Standard 2.0程序集,其包和IronSoftware.Common这一唯一依赖项都不包含本地二进制文件,因此恢复是运行者所需的全部。 没有Agents机密,IRONZIP_LICENSE_KEY不会在运行者上设置。 没有密钥,IronTarArchive.Add抛出了LicensingException,提示"需要生产许可证",而在同一存档上的SaveAs仍然写出了一个10240字节的TAR而无条目。 捕获异常并继续的代码写出了空包。
Copilot在copilot-setup-steps作业完成后开始工作,GitHub仅在.default branch中存在.github/workflows/copilot-setup-steps.yml时才触发该作业。
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.
将密钥保存于Secrets and variables的Agents选项卡中,因为云代理看不到Actions、Codespaces或Dependabot机密。
合并前应检查什么?
GitHub的文档显示/review传递给了copilot -p,因此审查会在其自己的会话中运行,独立于编码会话。
/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.
在实际运行中这些提示生成了什么?
Copilot CLI按顺序接收了六个提示,无人值守,前五个在一个会话中,而审查提示在一个单独的copilot -p调用中。 目标是一个为本指南制作的.NET 9日志解决方案,包含了四个服务的七个日志、一个仅计数它们的控制台作业、一个空的xUnit项目和格式文档。 下文中的每个数据和最后一个要点除审查发现外,都来自会话结束后运行的检查。 AI编码助手指南中的验收提示以相同的两种方式检查ZIP和.tgz存档,通过不同的条目名和提取后的SHA-256。
- 格式检查器在未改动作业上通过了2次检查中的4次,没有写出包。
- 在第一个提示之后,检查器通过了10月10日、9日和8日的24个检查中的24个。
- 10月10日的包包含五个条目,四个日志按服务前缀命名和manifest.txt。
- 在最后一个提示后,检查器仍然通过了24次检查中的24个。
- 在10月10日的包上,验证命令统计了4个日志,并退出0。
- 一个中间字节反转的副本使命令因TarException而退出1。
- 该命令的两次运行都没有留下已删除的文件夹。
- 计划套件的两次测试都通过了。
- 那些测试之一未能在添加了日志直接从其服务文件夹的最终代码副本上通过。
- 设置提交在restore测试中左下1通过和1失败,并且hostile.tar没有抛出异常。
- restore提示只修改了RestoreCommand.cs,没有其他文件。
- 在该提示之后,restore测试都通过了。
- 设置流程被解析为一个有6步的copilot-setup-steps作业,最后是密钥检查。
- 最终发布构建以0警告和0错误结束。
- 审查未改变任何文件,并报告了三个发现,其中之一是恢复到了代码从未检查其是否为空的文件夹中。
- 有些步骤与页面中的运行不一样。 计划提示在计划模式下运行自动驾驶,所以Copilot CLI批准了其自己的计划。 其测试通过System.Formats.Tar读取条目名称,并比较了IronZIP解压缩的文件上的散列。 Copilot CLI自己腐损的副本翻转了一个字节,没有抛出异常并在三个SHA-256不匹配上失败。 问题、云代理、Actions上的设置流程和Agents机密需要一个GitHub存储库,因此它们都没有运行。
Cursor指南将ZIP包代码移植到IronZIP,Add也去掉了每个条目名称中的文件夹,其移植的包包含7个条目,每个都有一个独特的平面名称。 Google Antigravity指南也通过用IronZIP提取并通过SHA-256比较每个文件来检查每个存档。共享运行记录列出了Copilot CLI的版本、模型、运行时间和本指南的测试机器。
故障排除
- 创建TAR用于将文件添加到TAR存档
- 创建GZIP用于压缩完成的TAR
- 提取GZIP用于一键解压.tar.gz
- 提取TAR用于解压普通TAR
- 当测试抛出LicensingException时使用IronZIP许可证密钥
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。