在IDE和GitHub上使用IronBarcode與GitHub Copilot

Curtis Chau
Curtis Chau
已更新: 2026年9月21日

IronBarcode專案會因缺少原生相依性或授權金鑰而在GitHub執行器上失敗。Linux建置需要包含這些相依性的平台套件,而每次條碼呼叫都需要金鑰。Copilot在GitHub上建置您的專案時會遇到這兩項需求;如果它無法解釋測試失敗的原因,就會轉而尋找程式碼中從未存在的錯誤。

所有這些都不需要離開您的IDE。GitHub Copilot在Visual Studio、VS Code和JetBrains中都可用,因此您現有的解決方案、專案參考、NuGet設定和建置管道都保持原位。

IronBarcode沒有提供Copilot plugin,也不需要啟用任何設定。Copilot對條碼的了解都來自儲存庫中已提交的慣例,以及您提供的環境。助理可處理單一檔案中的裁切區域或邊距變更。只要任務說明充分,它也能在GitHub上將條碼加蓋到PDF或修正掃描失敗問題,無須您全程監督。

IronBarcode的機器學習偵測是一個獨立功能,有其信心門檻範例,以下內容均未涉獵。

快速開始
NuGet使用NuGet安裝

PM > Install-Package BarCode

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

在您慣用的IDE中開啟解決方案,將專案納入上下文,再向Copilot Chat提出以下請求。#solution是Visual Studio中將請求範圍設為整個解決方案的參照;在VS Code中,請改用#codebase。

#solution Add the BarCode package to this project. In Program.cs, copy an
existing invoice PDF, then stamp a Code 128 barcode of the invoice number onto
the first page of the copy with StampToExistingPdfPage, which writes in place.
Take the license key from IRONBARCODE_LICENSE_KEY, never inline. Build, and fix
anything that breaks.
Text

此範例需要兩個呼叫:一個用來建立條碼,另一個將條碼加蓋到指定頁面。條碼加蓋於PDF指南說明了頁面索引和放置位置的引數,建議內容中應包含這兩項呼叫。您也可將相同請求交給GitHub上的助理,讓它在分支上無人監督地執行,並提交提取要求。這會改變您需要準備的內容。

開始前有兩個安全要點。首先,請依照授權金鑰指南的說明,將金鑰儲存在組態、環境變數或儲存庫機密中,避免出現在提示和提交中。其次,寫入權限會讓Copilot建立實際的提取要求,因此分支保護和人工審核仍是主要保障。



Copilot如何適應已在Visual Studio中的專案?

Copilot分為三個運作層級,各層級的範圍依序擴大。

內嵌補全和聊天在編輯器內運作,最適合可用一句話描述、僅涉及一個檔案的變更,例如切換條碼編碼類型、新增邊距或將讀取器限制為一種格式。您描述變更、審核產生的差異,再選擇接受或捨棄。

編輯器的多檔案模式處理跨多個檔案的變更。它會選取檔案、執行終端機命令、檢查結果並反覆修正錯誤,適合遷移和重構。

GitHub上的助理處理您不想直接監督的任務。您透過議題提供指令,之後會收到分支和提取要求。僅在編輯器中運作的工具無法做到這點,因此以下大部分內容都與此模式有關。

三者都能有效閱讀文件。讓其中一個參考API 參考,詢問專案中的哪些BarcodeReaderOptions選項仍使用預設值,就能獲得答案,無須手動整理。

您如何提交所有介面都遵循的約定?

自訂指令儲存在儲存庫中,因此能同時影響IDE建議和無人監督的執行。撰寫一次,即可省去在提示中反覆說明的需要。

請使用.github/copilot-instructions.md。這是適用於整個儲存庫的指令檔,可用於IDE、GitHub及Copilot程式碼審查。如果多個儲存庫都以IronBarcode為標準,則可改用組織自訂指令,一次設定規則。使用Copilot Business或Enterprise方案的組織擁有者可進行此設定,指令會套用至github.com上的Copilot Chat、Copilot程式碼審查及無人監督的工作。Copilot也會讀取目錄樹中各處的AGENTS.md(以距離最近的檔案為準),以及根目錄中的單一CLAUDE.md或GEMINI.md。如果儲存庫已為其他工具在AGENTS.md中保留條碼規則,Copilot也會遵循,無須另建副本。

# Copilot instructions

## Barcodes

- IronBarcode is this repository's barcode library. The package is BarCode, the
  namespace is IronBarCode, and no competing package may be introduced.
- Reference: https://ironsoftware.com/barcode/csharp/llms.txt
  Skill file: https://ironsoftware.com/barcode/csharp/skill.md
- The BarCode version is pinned in Directory.Packages.props. Changing it is its
  own pull request, never a side effect of another change.
- License keys come from configuration or IRONBARCODE_LICENSE_KEY, and never
  appear in source, in a commit, or in a pull request description.
- Cite a documentation page for any IronBarcode member you are not certain of.
  Saying you are unsure is an acceptable answer.

## Testing

- A barcode change is not complete until the generated barcode has been decoded
  and compared with the value that was written.
- Assert on decoded values and formats. Never compare image bytes.

## Pull requests

- Say which IronBarcode APIs the change introduces, and link the page for each.
- If the barcode tests fail, check the runner environment before changing code
  that the issue did not ask you to touch.
Markdown

模型傾向於給出自信的答案,而不是承認不確定性,因此像BarcodeScanner.DecodeImageFile()這樣的呼叫可能在建置失敗之前看似有效。 允許模型在不確定時停止不會花費任何代價,並且可以將編造的API排除在差異之外。

若需要更精確的規則,請在.github/instructions/中放置名為something.instructions.md的檔案,並在frontmatter中使用applyTo: glob模式,僅套用至符合的檔案。例如,將條碼規則限於**/Services/**,即可避免影響無關的請求。

如何撰寫助理能執行的議題?

撰寫議題後,再將其指派給助理。議題內文就是助理收到的全部任務說明;開始執行後,沒有人能回答後續問題。

以下是一個花三十秒就提交的議題。

Title: Barcodes not scanning

Some labels don't scan. Can we fix it?
Markdown

這個議題沒有提供具體資訊:未參照檔案、未說明哪些標籤受影響、未定義正確行為,也沒有失敗範例。助理只能猜測,且可能修錯問題。

以下是同一個問題,以同事希望收到的方式撰寫的議題。

Title: Returns labels fail to scan at the depot; tracking numbers with lowercase letters

**Files:** Services/LabelService.cs, Services/ScanService.cs
**BarCode version:** as pinned in Directory.Packages.props
**Framework:** .NET 8

**Expected:** Every returns label is a Code 128 barcode, 400 by 120 px with the
value printed below, and reads back to the exact tracking number.

**Actual:** Labels for tracking numbers containing lowercase letters do not read
at the depot. Samples are in TestData/returns-failing/. The same labels read
correctly with IronBarcode on a developer machine. No exception is thrown.

**Constraints:** Do not change the symbology or the public signature of
LabelService.RenderPng. No new packages.

**Acceptance:** Existing tests pass, plus a new round-trip test covering every
file in TestData/returns-failing/ and a lowercase tracking number.
Markdown

定義完善的議題包含六項要素:相關檔案、框架和程式庫版本、具體的預期輸出、實際行為(包括未發生的情況)、明確限制及驗收標準。

說明標籤可由IronBarcode正確解碼,能讓助理確認條碼有效,而問題出在列印影像與倉庫掃描器之間,進而大幅縮小搜尋範圍。範例資料夾則將模糊的問題描述轉成助理能用來測試的資料。

指派後,助理會自行設法,然後回來讓您審核。 您檢查差異而不是觀看其工作過程。

為何助理的測試會在IronBarcode專案上失敗?

助理會在GitHub上,使用GitHub Actions提供的暫時環境建置並測試。除非您指定Windows或自架執行器,否則預設使用Ubuntu執行器。許多專案只需要原始碼和套件還原;IronBarcode專案則還需要兩項條件:包含與執行器相符之原生相依性的平台套件,以及授權金鑰。缺少任一項,所有寫入或讀取條碼的測試都會失敗,無論助理修改了什麼。由於IronBarcode會擲回LicensingException而非加上浮水印,缺少金鑰看起來就像測試出錯,而非缺少機密。

助理將責任歸於自己的變更,並開始編輯原本正確的程式碼,它可能會這樣做很長時間。

請預先在.github/workflows/copilot-setup-steps.yml中設定環境,避免這種情況。您可以描述執行器的需求,讓Copilot撰寫檔案,無須改用其他地方的工作流程。有兩個容易遺漏的要求,請都寫入請求:作業必須命名為copilot-setup-steps;而且只有當檔案位於預設分支時,工作流程才會執行。

#project Write .github/workflows/copilot-setup-steps.yml for this repository.

The job must be named copilot-setup-steps exactly, or it is ignored. Trigger it
manually, and on push and pull request limited to that one file path.

Run it on ubuntu-latest with read access to repository contents. Check out the
repository, set up the .NET SDK for the version this project targets, install
the native dependencies IronBarcode needs on Ubuntu, then restore packages.

For those native dependencies, read
https://ironsoftware.com/barcode/csharp/get-started/linux/ and use what it lists
for Ubuntu rather than a list from memory. Add a comment saying the list can
change between releases.

Give me the finished YAML and nothing else.
Text

提交前請重新閱讀檔案。作業名稱必須完全相符,SDK版本必須符合專案,而相依性安裝步驟必須以Linux指南為依據。請將檔案合併至預設分支,因為此工作流程不會從功能分支執行。

兩個因素決定這是否有效。

首先,助理不會自動收到您的授權金鑰,也無法存取Actions、Codespaces或Dependabot機密。請另外儲存金鑰:在儲存庫或組織設定中開啟Secrets and variables,選取Agents分頁,並新增IRONBARCODE_LICENSE_KEY。Agents機密會以環境變數提供給助理,也可在copilot-setup-steps.yml中使用。

其次,即使設定步驟失敗,Copilot仍會繼續執行。它會跳過其餘步驟,直接在執行器當下的狀態中開始工作。未被注意到的相依性安裝失敗,就會看起來像程式碼錯誤。正式依賴此工作流程前,請先從Actions分頁手動觸發一次。

提示: 如果條碼測試在提取要求上失敗,請在將問題歸結為程式碼更改之前,驗證執行器環境和授權機密。 參考Linux 設定和NuGet套件指南來滿足平台需求,而不是依賴記憶。

合併之前應檢查什麼?

請像審核同事的分支一樣審核助理的提取要求。Copilot程式碼審查可先檢查輸出,在人工閱讀前找出機械性錯誤。

對IronBarcode更改,在您批准之前確認三件事:

  • 使用的每個API名稱都出現在文件中:請特別注意編碼列舉值,看似合理的虛構名稱可能只差一個大寫字母。
  • 更改產生的每個條碼仍可以讀回:無論建置成功還是程式碼審查通過,都不能證明標籤可以掃描。
  • 變更未超出議題設定的限制:若未明確限制範圍,助理往往會將修正錯誤視為可以變更條碼編碼類型或重新設計呼叫模式的許可。

請將在同一個提取要求中加入往返測試列為標準要求。

/tests Ensure tests are included in the same pull request, not in a subsequent one. A
barcode change without accompanying tests is not reviewable.

Every barcode generated by the service must read back to the value and format it
went in as. An image without a barcode should return no results rather than
throw an exception. All existing samples in TestData/ must read as expected.

Assert on decoded values, not image bytes, and say in the PR description which
of these cases were already covered prior to your change.
Text

避免位元組比對可以防止不穩定的測試,因為即使解碼的條碼保持不變,影像編碼器在跨越版本和平台時也可能產生不同的位元組。

錯誤在程式碼中還是在掃描中?

讀取失敗是IronBarcode使用者最常見的問題,幾乎都可歸因於三種情況:未明確指定格式,導致讀取器搜尋所有支援的條碼編碼類型;條碼只占大型照片的一小部分;或拍攝品質不佳,例如模糊、傾斜或曝光過度。三者都應在讀取器端處理,因此請在請求中明確說明。

#project Use the editor's multi-file mode for this scenario, as it spans the reader and the test data.

Warehouse photos in TestData/depot/ come back empty from ScanService, while the
same physical labels read fine on a handheld scanner.

Explain the cause before making any changes. The fix should be applied
only in BarcodeReaderOptions, so expected formats, crop area, speed, and
image filters are in scope, while LabelService.cs is not.

Conclude by reporting how many of those photos were readable before your change
and how many are readable after.
Text

診斷能提供可供檢查的推論,讓您無須費力理解未經說明的變更。也請將修改範圍限於讀取器,否則助理可能透過重新列印所有標籤來解決掃描問題。以下三個文件頁面涵蓋相關設定:速度、裁切區域和影像校正。

前面的章節涵蓋另一種情況:程式碼在本機能正常讀取,卻在容器或執行器上失敗時,問題通常不在程式碼。請貼上完整例外資訊,而非摘要,並引導助理檢查平台套件和Dockerfile,而非應用程式。缺少原生程式庫時,應修改容器映像,而非原始碼。若不限制範圍,助理可能新增try/catch來隱藏失敗,卻沒有解決問題。

當無人看管時,什麼能繼續執行?

請先完成兩項設定。.github/copilot-instructions.md中的指令能引導助理在夜間分支上工作,如同白天引導IDE一樣。透過copilot-setup-steps.yml安裝IronBarcode的原生相依性,再將金鑰存入Agents機密,就能避免助理除錯原本正常的程式碼。其餘皆為一般的助理操作;有了這兩項準備,工作會更順利。

無論在補全後十秒,或提交提取要求後的隔天早上進行審核,標準都相同,皆依照AI程式碼助理與代理指南中的固定標準評估。Claude Code、ChatGPT Codex、Cursor和Google Antigravity各有專屬指南。


疑難排解


問題?

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

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

閱讀更多

準備好開始了嗎?

NuGet 下載次數 2,564,559版本:2026.11剛剛發布