如何使用IronZIP與GitHub Copilot

Curtis Chau
Curtis Chau
已更新: 2026年10月26日

某些.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範例顯示了本指南所依賴的調用。

快速開始
NuGet使用NuGet安裝

PM > Install-Package IronZip

在 NuGet 包管理器控制台中運行上述命令安裝 IronZIP,或在 NuGet 包管理器中搜索該包。

在解決方案根目錄啟動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.
Text

路徑特定的指令文件聲明了IronZIP的TAR命名規則,因此提示中省略了它。

將密鑰存儲在IRONZIP_LICENSE_KEY環境變量或存儲庫秘密中,避免提示和提交。 在只設置該變量的探測中,License.IsLicensed返回false,因此Program.cs將值複製到IronZip.License.LicenseKey。 要改為在配置文件中設置密鑰,請參考授權金鑰指南。 保持分支保護和人工批准在雲代理的拉取請求上。



如何為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.
Markdown

如何給存檔代碼設置自己的規則?

將存檔規則保存為.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.
Markdown

IronZIP的TAR寫入器保留了文件路徑的哪些部分?

這裡每個服務都以日期來命名其日誌,所以logs/api/2026-10-10.log和logs/worker/2026-10-10.log共享一個文件名。 直接從其文件夾中添加的四個日志在October 10使用IronZIP 2026.10.2時成為四個TAR條目,名為2026-10-10.log。 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.
Text

在校準探測中,翻轉的字節使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.
Text

為什麼恢復舊的TAR會寫到文件夾外?

2026年前的捆綁包是普通TAR文件,同事的恢復命令用IronTarArchive.ExtractArchiveToDirectory解壓它們。 在一個探測中,那個調用將一個名為../escaped-dotdot.txt的條目寫到目標上方的文件夾中,還有一個絕對名稱寫到驅動器的根目錄。ExtractTGZArchiveToDirectory拒絕了同一個../條目,拋出了InvalidNameException,但只有在解壓前面的條目之後。

設置提交添加了RestoreCommand.cs、RestoreTests.cs和兩個TAR文件到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

為校準而編寫的引用修正利用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.
Markdown

IronBZip2Archive不接受壓縮級別,而其ExtractArchiveToDirectory將.tar.bz2直接解壓至TAR內的文件。

為什麼雲代理的測試在IronZIP項目上失敗?

默認情況下,雲代理在Ubuntu Linux上工作。 IronZIP提供了單一的.NET Standard 2.0程序集,其包和IronSoftware.Common作為其唯一依賴項,都不包含本機二進制文件,所以只需恢復即可滿足運行器的需要。 沒有代理機密,IRONZIP_LICENSE_KEY不會在運行器上設置。 沒有密鑰,IronTarArchive.Add拋出LicensingException,顯示"需要生產許可證",而SaveAs同一存檔仍然寫入了沒有條目的10,240字節TAR。 捕捉異常並繼續的代碼寫入空捆綁包。

Copilot在copilot-setup-steps工作完成後開始工作,而GitHub只有在默認分支上存在.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.
Text

將密鑰保存到秘密和變量的代理選項卡下,存儲庫設置中的安全性,因為雲代理無法看到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.
Text

在實際運行中,這些提示產生了什麼結果?

Copilot CLI按順序接收到六個提示,前五個提示在一個會話中收到,審核提示在一個單獨的copilot -p調用中收到。 目標是一個為本指南編寫的.NET 9日志解決方案,包含跨四個服務的七個日志,一個僅計數它們的控制台工作,一個空的xUnit項目和格式文件。 除審核結果和最後一個要點外的所有數據均來自會話結束後運行的檢查。 AI編碼助手指南中的驗收提示以不同的兩種方式檢查ZIP和.tgz檔案,通過不同的條目名稱並在提取後通過SHA-256檢查。

  • 格式檢查器通過了未改動的工作的4個檢查中的2個,該工作未寫入捆綁包。
  • 第一個提示後,檢查器對10月10日、9日和8日的所有24個檢查均通過。
  • 10月10日的捆綁包包含五個條目,四個日志使用服務前綴的名稱和manifest.txt。
  • 最後一個提示後,檢查器仍然通過了24個檢查中的24個檢查。
  • 在10月10日的捆綁包上,驗證命令數了4個日志並退出0。
  • 它的中間字節反轉的副本使命令在TarException上退出1。
  • 該命令的兩次運行都沒有留下臨時文件夾。
  • 計劃套件的兩次測試均通過。
  • 其中一項測試失敗於添加了日志的最終代碼的副本,那是直接從它們的服務文件夾中添加的。
  • 設置提交使得恢復測試在1次通過和1次失敗中完成,且hostile.tar未拋出異常。
  • 恢復提示更改了RestoreCommand.cs而沒有改變其他文件。
  • 該提示後的兩次恢復測試都通過。
  • 設置工作流程解析為一個copilot-setup-steps任務,共6步,最後一步檢查密鑰。
  • 最後的Release構建以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的版本、模型、運行時間和該指南的測試機器。


疑難排解


問題?

如果您有任何疑問,請聯繫support@ironsoftware.com

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

閱讀更多

準備好開始了嗎?

NuGet 下載次數 25,383版本:2026.11剛剛發布