使用 IronBarcode 與 AI 程式碼助理和代理

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

當您要求工具新增 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 中讀取或從單一圖片中提取多個符號。

Claude Code AI 程式碼代理標誌ChatGPT Codex AI 程式碼代理標誌GitHub Copilot AI 程式碼助理標誌Cursor AI 程式碼編輯器標誌Google Antigravity AI 程式碼代理標誌

模型無法自行處理條碼嗎?

訓練資料會逐漸過時。模型可能會使用幾個版本前已停用的 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.
Text

或者,從終端安裝套件,指定當前的發行版本。

dotnet add package BarCode --version 2026.9.2
SHELL

Linux、macOS、iOS 和 Android 各自需要特定套件,例如 BarCode.Linux 或 BarCode.MacOs。請參閱進階 NuGet 安裝指南,選擇適當的套件。


步驟 2:套用您的授權金鑰

IronBarcode 不會在未授權的輸出上加上浮水印。開發寬限期結束後,若未設定授權金鑰,第一次條碼呼叫就會擲回 IronSoftware.Exceptions.LicensingException,訊息為 IronBarcode must be licensed for development。缺少授權金鑰的程式碼會在執行階段失敗。請先取得免費試用金鑰。

立即在您的項目中開始使用 IronBarcode,免費試用。

第一步:
arrow pointer

請在應用程式啟動時、任何 IronBarcode 呼叫之前,設定一次授權金鑰。金鑰應從環境變數讀取,不應寫在原始碼中。

// 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.
Text

目前的模型通常能遵循「不確定時先詢問」的明確要求。先釐清問題,比冒著編譯失敗的風險更好。

請注意: IronBarcode 也提供可直接使用的技能檔案,供支援此功能的工具載入。下一步說明應在何處引用它。

步驟 4:將 IronBarcode 背景資訊新增至您的專案

貼到聊天中的文件僅在目前對話中可用。儲存在專案檔案中的文件則可供每次對話存取。

每個工具從特定文件中讀取指示。將 IronBarcode 指導放在您團隊使用的文件中:

工具專案背景資訊檔案技能檔案存放位置
Claude CodeCLAUDE.md.claude/skills/
ChatGPT CodexAGENTS.md.agents/skills/
GitHub Copilot.github/copilot-instructions.md不適用
Cursor.cursor/rules/*.mdc不適用,請使用 @Docs
Google AntigravityAGENTS.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.
Markdown

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.
Text
提示: 最後一行通常會讓工具將這些規則儲存到步驟 4 所述的背景資訊檔案,例如 CLAUDE.md 或 AGENTS.md。您只需貼上提示一次。
提示: 沒有測試影像嗎? 首先要求代理使用 IronBarcode 生成它們,然後讀取回來。 條碼程式庫是代理可以在僅限文字狀況下端到端測試的少數項目之一。 它寫入一個值,解碼影像,並比較字串。

步驟 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:驗證您收到的內容

像對待一位未執行程式的同事的初稿一樣審查生成的程式碼。 四種檢查能解決大多數問題:

  1. 它可以編譯:發明的方法會立即失敗。
  2. 已套用授權金鑰:必須在第一次 IronBarcode 呼叫之前完成設定,否則該呼叫會擲回 LicensingException。
  3. 每個 API 方法都存在:對於不熟悉的方法,請先查閱 API 參考,再尋找替代方案。
  4. 每個條碼都可讀取:使用 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.
Text

可重現的結果

本節以實際任務與單一提示評估代理,您無須提供程式碼。請在空白專案的新對話中執行,並依下列標準評估結果。

請注意: 開始之前,您需要 .NET 9 SDK、可執行命令的 AI 程式碼代理、網路連線,以及儲存在 IRONBARCODE_LICENSE_KEY 環境變數中的 IronBarcode 試用或正式授權金鑰。IronBarcode 在沒有金鑰時會擲回錯誤,而非加上浮水印,因此缺少金鑰就無法通過此測試。

提示

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

輸出

驗收測試執行時由 GET /label 傳回的 Code 128 出貨標籤,追蹤號碼為 1Z999AA10123456784

這是記錄此次執行時,GET /label/1Z999AA10123456784 傳回的原始 PNG。同次執行的往返驗證表列出全部 13 張影像及其寫入值與解碼值。

通過標準

  • Release 建置無須人工介入即可完成。
  • roundtrip.md 顯示 13 列全部相符,每個讀取值都與寫入值一致,且格式正確。
  • 兩個 EAN-13 值都有有效的檢查碼,GS1 字串則原樣傳回。
  • 授權金鑰從環境變數讀取,且不出現在原始碼或 roundtrip.md 的任何位置。
請注意: 請將步驟 1 的版本替換為您專案的目標版本,並固定使用該版本。IronBarcode 更新記錄列出各版本的變更。

執行記錄

項目值
套件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日

執行過程中需要一次編譯修復,且無需手動編輯程式碼。


代理特定指南

上述設定適用於所有這些工具。以下各指南提供個別工具的使用方式:


疑難排解


問題?

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

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

閱讀更多

準備好開始了嗎?

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