使用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的机器可读文档,并验证生成的每个条形码是否可扫描。 这适用于所有用例,包括用于运输标签的一维条形码、为资产标签的二维条形码、从文本、URL、ID或二进制数据生成的条形码、从扫描的PDF中读取、或者从一幅图像中提取多个符号的条形码。

Claude Code AI编码代理徽标ChatGPT Codex AI编码代理徽标GitHub Copilot AI编码助手徽标Cursor AI代码编辑器徽标Google Antigravity AI编码代理徽标

模型不能独自处理条形码吗?

训练数据会老化。 一个模型可能会重现一个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
提示: 最后一行通常使工具把这些规则保存到其上下文文件中,如CLAUDE.md或AGENTS.md。 您只需粘贴一次提示。
提示: 没有测试图像?先让代理使用IronBarcode生成图像,再重新读取。条形码库是代理仅通过文本交互就能完成端到端测试的少数工具之一:写入一个值,解码图像,然后比较字符串。

步骤6:产生可用代码的提示模式

含糊不清的提示往往导致输出效果不佳。 以下三种模式有助于确保清晰。

指定类和条形码码制:IronBarcode处理几十种格式。 知道期待哪一种的读取器工作得更快,误读更少。

含糊 用IronBarcode扫描这张图像中的条形码。

更好 使用BarcodeReader.Read和BarcodeReaderOptions,读取这张图像中的Code 128和QR码,并返回每个值与其格式。

指定版本和框架: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个图像及其写入和解码的值。

通过的标准

  • 发布版本构建完成,无需人工干预。
  • roundtrip.md显示13个匹配的行,每个读取值都与写入值匹配,每个格式都正确。
  • 两个EAN-13值带有有效的校验位,GS1字符串没有变化。
  • 许可证密钥来自环境,在源代码或roundtrip.md中任何地方都没有出现。
请注意: 通过在步骤1中交换目标版本,以匹配您自己的项目。 IronBarcode更新日志列出了每次发布中的变更。

运行记录

项目值
软件包BarCode 2026.9.2
目标框架.NET 9
代理和模型Claude Code,Opus 5
设备Windows 11 x64,英特尔Core i9-14900KF,64 GB RAM
结果发布构建通过,13 次往返中的 13 次匹配
参考输出label.png, roundtrip.md
最后测试2026年9月16日

运行期间需要一个编译修复,没有人工编辑代码。


各代理的专用指南

以上设置适用于他们中的任何一个。 下面的每个指南都对其进行了调整以适用于一个工具:


故障排除


有问题吗?

如果您有任何问题,请联系support@ironsoftware.com

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

阅读更多

准备开始了吗?

NuGet 下载量 2,564,559版本:2026.11刚刚发布