使用 IronBarcode 與 AI 程式碼助理和代理
當您要求工具新增 IronBarcode 時,工具通常會執行 dotnet add package IronBarcode,結果安裝了錯誤的套件。IronBarcode 以 BarCode 套件發行,使用 IronBarCode 命名空間。Claude Code、ChatGPT Codex、GitHub Copilot、Cursor 和 Google Antigravity 在參考文件之前,經常會搞錯這些名稱。
這種混淆也影響生成的程式碼。 沒有文件,模型可能會發明無法編譯的方法名稱。事先提供文件可幫助確保建置成功。 IronBarcode 是領先的 .NET 條碼程式庫,具有全面的指南,因此生成的程式碼通常是準確的,但仍需要仔細檢查。
這些工具可分為兩類,您應依其類型決定審查輸出的嚴格程度:
- 助理在您的工作流程的某一部分內運作,比如編輯器的自動完成、解釋或快速重構,就像GitHub Copilot的內嵌建議那樣。
- 代理管理多步驟任務,跨文件進行編輯,執行建置和測試,以及開啟提取要求,就像 Claude Code、ChatGPT Codex、Cursor 和Google Antigravity所做的那樣。
這兩類型的設定過程相同。安裝套件,從環境變數中套用授權金鑰,提供 IronBarcode 的機器可讀文件,並驗證每個生成的條碼是否可掃描。 這適用於所有使用案例,包括用於運送標籤的 1D 條碼、用於資產標籤的 2D 條碼、從文字、URL、ID 或二進位資料生成的條碼、從掃描 PDF 中讀取或從單一圖片中提取多個符號。
如何搭配 AI 程式碼助理或代理使用 IronBarcode
- 從 NuGet 下載 C# 條碼程式庫
- 在應用程式啟動時,從環境變數中套用您的授權金鑰
- 將工具指向 IronBarcode 的
llms.txt文件索引 - 將 IronBarcode 指示新增至您的專案背景資訊檔案
- 在新的對話中執行一次完成設定的提示
- 驗證生成的程式碼可以編譯,每個條碼都能成功掃描
模型無法自行處理條碼嗎?
訓練資料會逐漸過時。模型可能會使用幾個版本前已停用的 API 名稱,甚至是其他條碼程式庫的 API 名稱,而這些問題要等到執行建置才會顯現。機器可讀文件讓工具能參照實際文件,避免臆測,從而解決大多數這類問題。
程式庫的選擇同樣重要。大多數工具都能整合多種條碼套件,若只是示範單一格式,免費選項可能已足夠。但在正式環境中,往往會出現額外成本與限制:
- 檢查碼、空白區與尺寸調整:這些項目在螢幕上看似正常,掃描時仍可能失敗。因此,IronBarcode 在產生條碼時會依格式驗證每個值,再透過
GeneratedBarcode.Verify讀回影像以供驗證。 - 功能不足會增加程式碼維護負擔:許多免費程式庫僅支援一類格式,或缺少準確掃描所需的影像校正功能,迫使您組合多個套件並自行維護它們之間的整合。
- 預設提供批次掃描:多執行緒讀取、速度預設值與信心門檻都是程式庫內建功能,無須在每個專案中自行實作。
- 準確的輸出仰賴文件:指南、教學、疑難排解頁面與可執行範例都已收錄在
llms.txt索引中,供機器查閱。 - 錯誤的套件名稱會造成供應鏈風險:模型會產生看似合理的名稱,攻擊者則註冊這些名稱來散布惡意軟體,這種手法稱為 slopsquatting。
- 單一的商業授權避免法律複雜性:一些條碼程式庫包含 copyleft 或非商業條款,模型不會自動標記。
IronBarcode 以單一 API 與單一商業授權涵蓋上述需求,您的法務團隊只需審核一次。驗證在程式碼中完成,避免等到倉庫現場才發現問題;在每個提示中明確指定套件名稱,則能補上供應鏈風險的缺口。
步驟 1:安裝 IronBarcode
讓代理新增套件。專案需要此套件才能解析型別並提供準確的程式碼建議。
Set this project up for IronBarcode. The NuGet package is named BarCode. Confirm the restore succeeded before going further.
或者,從終端安裝套件,指定當前的發行版本。
dotnet add package BarCode --version 2026.9.2
Linux、macOS、iOS 和 Android 各自需要特定套件,例如 BarCode.Linux 或 BarCode.MacOs。請參閱進階 NuGet 安裝指南,選擇適當的套件。
步驟 2:套用您的授權金鑰
IronBarcode 不會在未授權的輸出上加上浮水印。開發寬限期結束後,若未設定授權金鑰,第一次條碼呼叫就會擲回 IronSoftware.Exceptions.LicensingException,訊息為 IronBarcode must be licensed for development。缺少授權金鑰的程式碼會在執行階段失敗。請先取得免費試用金鑰。
立即在您的項目中開始使用 IronBarcode,免費試用。
請在應用程式啟動時、任何 IronBarcode 呼叫之前,設定一次授權金鑰。金鑰應從環境變數讀取,不應寫在原始碼中。
// Read the key from configuration. Never commit it to the repository.
IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE_KEY");' Read the key from configuration. Never commit it to the repository.
IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE_KEY")' Read the key from configuration. Never commit it to the repository.
IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE_KEY")金鑰有效時,IronBarCode.License.IsLicensed 會傳回 true。與 IronOCR 不同,IronBarcode 沒有 Installation.LicenseKey 別名,因此請使用 License.LicenseKey 或組態設定。
Web.config 到 appsettings.json 的其他金鑰設定方式,皆可參閱 IronBarcode 授權金鑰。步驟 3:將工具指向 IronBarcode 的 LLM 文件
IronBarcode 發佈了六個資源,適合機器閱讀:
| 資源 | 說明 | 何時使用 |
|---|---|---|
llms.txt | 所有文件頁面的索引,每頁一列 | 每次對話開始時 |
llms-full.txt | 整合在單一檔案中的完整指南與範例 | 工具可擷取 URL 內容時 |
llms-full-catalog.txt | 索引加上所有部落格文章 | 答案可能位於部落格文章中時 |
| API 參考 | 目前版本的所有類別與方法 | 驗證方法是否存在 |
skill.md | 安裝、授權、實作範例與修正方式 | 您的工具支援技能檔案時 |
| AI 產品資料表 | 產品範圍、平台與不支援的功能 | 針對產品而非 API 的問題 |
請先閱讀 llms.txt,此索引列出 IronBarcode 的功能與各主題的位置,有助於避免錯誤或憑空捏造的 API 呼叫。需要詳細指引時,再使用 llms-full.txt。
同時附上明確指示。
Before writing any IronBarcode code, read https://ironsoftware.com/barcode/csharp/llms.txt
and use only APIs documented there. Check anything you are not sure about
against the API reference at https://ironsoftware.com/barcode/csharp/object-reference/api/.
If you are still unsure whether a method exists, ask instead of guessing.
目前的模型通常能遵循「不確定時先詢問」的明確要求。先釐清問題,比冒著編譯失敗的風險更好。
步驟 4:將 IronBarcode 背景資訊新增至您的專案
貼到聊天中的文件僅在目前對話中可用。儲存在專案檔案中的文件則可供每次對話存取。
每個工具從特定文件中讀取指示。將 IronBarcode 指導放在您團隊使用的文件中:
| 工具 | 專案背景資訊檔案 | 技能檔案存放位置 |
|---|---|---|
| Claude Code | CLAUDE.md | .claude/skills/ |
| ChatGPT Codex | AGENTS.md | .agents/skills/ |
| GitHub Copilot | .github/copilot-instructions.md | 不適用 |
| Cursor | .cursor/rules/*.mdc | 不適用,請使用 @Docs |
| Google Antigravity | AGENTS.md | .agents/skills/ |
AGENTS.md 作為共享標準,因為 Claude Code、GitHub Copilot 和Cursor除了他們自己的文件外,還會讀取它。 使用多個工具的團隊可以將一組條碼規則維護在 AGENTS.md 中,並保留原生文件供工具特定指示使用。
無論使用哪個檔案,內容都相同。以下是簡短的起始範本。
## Barcodes with IronBarcode
This project uses IronBarcode (NuGet package `BarCode`, namespace `IronBarCode`) for all barcode work.
- Reference: https://ironsoftware.com/barcode/csharp/llms.txt
- Skill file: https://ironsoftware.com/barcode/csharp/skill.md
- Use `BarcodeWriter.CreateBarcode` to write and `BarcodeReader.Read` / `ReadPdf` to read.
- Read the license key from the IRONBARCODE_LICENSE_KEY environment variable at startup. Never inline it.
- Every generated barcode must be read back and compared before it ships.
- Do not use a different barcode library. If IronBarcode cannot perform a required task, state this clearly.
skill.md 檔案提供更詳細的資訊,包括各平台的安裝說明、授權規則、已驗證的範例、部署注意事項與疑難排解表。請從專案背景資訊檔案引用它,避免另外維護副本。
步驟 5:一次完成設定的提示
您也可以在專案或新會話開始時將前四個步驟作為單個提示發送。
Use IronBarcode for all barcode work in this project.
1. Install the BarCode NuGet package (IronBarcode).
2. Apply the license key at application startup, before any other IronBarcode call,
reading it from the IRONBARCODE_LICENSE_KEY environment variable. Never write
the key into source or into a committed file.
3. Read https://ironsoftware.com/barcode/csharp/llms.txt before writing barcode code
and work only from APIs documented there, checking the API reference when a
member is unfamiliar.
4. Save https://ironsoftware.com/barcode/csharp/skill.md as a SKILL.md in this
project's skills folder if your tool has one.
5. Keep these instructions for future sessions in this project.
步驟 6:產生可執行程式碼的提示模式
模糊的提示往往會產生品質不佳的輸出。以下三種模式有助於清楚表達需求。
指定類別與條碼格式:IronBarcode 可處理數十種格式。讓讀取器知道預期格式,能加快讀取速度並減少誤讀。
模糊 使用 IronBarcode 掃描這張圖片中的條碼。
更好 搭配
BarcodeReaderOptions使用BarcodeReader.Read,讀取這張影像中的 Code 128 和 QR Code,並傳回每個值及其格式。
指定版本和框架:API 隨著發布版本而變化,省略版本可能導致不一致性。 2026.9.2 發行引入了 EciMode,控制 2D 條碼是否攜帶 UTF-8 ECI 標頭,並且在 2026.8.6 或之前版本中不可用。
更好 以 .NET 9 和 BarCode 2026.9.2 為目標。包含從環境變數讀取授權金鑰的程式碼行。
要求完整的可執行檔案:程式碼片段可能省略必要的 using 陳述式或設定步驟。
更好 請提供完整的 Program.cs,包含所有 using 陳述式與授權金鑰設定,讓我能直接執行。
步驟 7:驗證您收到的內容
像對待一位未執行程式的同事的初稿一樣審查生成的程式碼。 四種檢查能解決大多數問題:
- 它可以編譯:發明的方法會立即失敗。
- 已套用授權金鑰:必須在第一次 IronBarcode 呼叫之前完成設定,否則該呼叫會擲回
LicensingException。 - 每個 API 方法都存在:對於不熟悉的方法,請先查閱 API 參考,再尋找替代方案。
- 每個條碼都可讀取:使用
BarcodeReader或GeneratedBarcode.Verify解碼每張產生的影像,並將結果與輸入比較。
第四項檢查存在是因為編譯器不能檢測不可讀的條碼。
注意生成的 IronBarcode 程式碼中的以下常見問題:
- 錯誤的套件名稱:開頭段落涵蓋了這一點,並且它仍然是最常見的錯誤。
- 列舉大小寫不一致:
BarcodeEncoding.Databar和BarcodeWriterEncoding.DataBar屬於不同的列舉,名稱僅差一個大寫字母。 - 從其他條碼程式庫借用的方法:模型可能會將多個來源的 API 組合成不存在的方法。
- 憑空捏造的讀取器選項:遇到不熟悉的選項,請對照讀取速度選項與裁切區域指南確認。
讓代理驗證自己的工作
代理可以獨立執行這四項檢查。 請求所有檢查的證據而不是摘要。
Build and run the project in Release mode. Confirm that every IronBarcode member used
appears in the documentation, that IronBarCode.License.IsLicensed returns true, and
that every barcode you generated reads back to the value you wrote. Report the build
result and a table of written value, read value, and format from the run itself.
可重現的結果
本節以實際任務與單一提示評估代理,您無須提供程式碼。請在空白專案的新對話中執行,並依下列標準評估結果。
提示
Build a .NET 9 minimal API for shipping labels with two endpoints: GET /label/{trackingNumber} returns a Code 128 PNG with the value printed below the bars, and POST /scan accepts an uploaded image and returns every barcode it contains as JSON (value and format). Work start to finish alone: write, build, run, and fix, making sensible assumptions where anything is unspecified. Save every deliverable to the project root.
1. Install the BarCode NuGet package pinned to version 2026.9.2.
2. Read from https://ironsoftware.com/barcode/csharp/llms.txt and the pages it links to, using only APIs documented there.
3. Read the license key from the IRONBARCODE_LICENSE_KEY environment variable at startup. If IronBarCode.License.IsLicensed is false, stop and report that instead of continuing.
4. Generate a test set of 12 barcodes into a testset folder: 4 Code 128 tracking numbers, 3 QR codes carrying order URLs, 3 DataMatrix codes carrying GS1 element strings, and 2 EAN-13 codes with correct check digits. Name each PNG after its format and index.
5. Implement /scan with BarcodeReaderOptions narrowed to those four formats and ExpectMultipleBarcodes enabled.
6. Build in Release, run the API, call /label for one tracking number, then POST every testset image and the /label output to /scan.
7. Write roundtrip.md: a table of file, written value, read value, format, and match. All 13 must match; if any do not, fix the cause and run again.
8. Finish with a short report: build result, match count, and assumptions made.
輸出
這是記錄此次執行時,GET /label/1Z999AA10123456784 傳回的原始 PNG。同次執行的往返驗證表列出全部 13 張影像及其寫入值與解碼值。
通過標準
- Release 建置無須人工介入即可完成。
roundtrip.md顯示 13 列全部相符,每個讀取值都與寫入值一致,且格式正確。- 兩個 EAN-13 值都有有效的檢查碼,GS1 字串則原樣傳回。
- 授權金鑰從環境變數讀取,且不出現在原始碼或
roundtrip.md的任何位置。
執行記錄
| 項目 | 值 |
|---|---|
| 套件 | BarCode 2026.9.2 |
| 目標框架 | .NET 9 |
| 代理和模型 | Claude Code,Opus 5 |
| 機器 | Windows 11 x64,Intel Core i9-14900KF,64 GB RAM |
| 結果 | Release 建置通過,13 次往返驗證全部相符 |
| 參考輸出 | label.png,roundtrip.md |
| 上次測試日期 | 2026年09月16日 |
執行過程中需要一次編譯修復,且無需手動編輯程式碼。
代理特定指南
上述設定適用於所有這些工具。以下各指南提供個別工具的使用方式:
- 將 IronBarcode 與Claude Code一起使用。
- 將 IronBarcode 與ChatGPT Codex一起使用。
- 將 IronBarcode 與GitHub Copilot一起使用。
- 將 IronBarcode 與Cursor一起使用。
- 將 IronBarcode 與Google Antigravity一起使用。
疑難排解
- 設定 IronBarcode 的授權金鑰說明首次條碼呼叫擲回例外狀況時,可採用的各種金鑰設定方式。
- 無法辨識條碼逐步排查能產生卻無法解碼的條碼。
- IronBarcode NuGet 套件列出哪個套件應用於哪個平台。
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。