在IDE和GitHub上使用IronBarcode与GitHub Copilot
由于缺少原生依赖项和许可证密钥,IronBarcode项目会在GitHub运行器上失败。Linux构建需要包含这些依赖项的平台包,每次条形码调用都需要密钥。Copilot在GitHub上构建项目时会遇到这两个问题;无法解释的测试失败会让它去查找代码中并不存在的错误。
这些都不需要您离开IDE。GitHub Copilot可以在Visual Studio、VS Code和JetBrains中使用,因此您的现有解决方案、项目引用、NuGet设置和构建管道都可以保持不变。
IronBarcode没有专用的Copilot插件,也没有需要开启的设置。Copilot对条形码的了解来自存储库,包括您提交的约定和为它提供的环境。助手可以在单个文件中调整裁剪区域或边距。如果任务说明足够充分,它也能将条形码加盖到PDF上,或在GitHub上修复扫描失败问题,无需您全程监督。
IronBarcode自己的机器学习检测是一个独立的功能,有其自己的置信度阈值示例,下面的内容都不涉及它。
快速入门在您使用的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.
该示例需要两次调用:先创建条形码,再将其加盖到指定页面。在PDF上加盖条形码的指南介绍了页面索引和位置参数,建议代码中应包含这两次调用。您也可以将同一请求交给GitHub上的助手,让它在分支上无人值守地执行并提交拉取请求;这需要您做好不同的准备。
开始前请注意两点安全事项。首先,按照许可证密钥指南的说明,将许可证密钥存入配置、环境变量或存储库机密,不要放入提示或提交中。其次,写入权限允许Copilot创建真实的拉取请求,因此分支保护和人工审查仍是主要保障。
5个步骤的简化工作流
- 从NuGet下载C#条形码库
- 提交
.github/copilot-instructions.md,包含项目的IronBarcode约定。 - 使用内联聊天进行小编辑,对于较大的编辑使用编辑器的多文件模式。
- 对于无人监督的工作,提交详细的问题并交给GitHub上的助手。
- 审查拉取请求,对照API参考逐一核实API名称。
GitHub 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.
模型往往会自信地回答,而不愿承认不确定,因此像BarcodeScanner.DecodeImageFile()这样的调用在构建失败之前可能看起来一直有效。允许模型在不确定时停下来并无损失,还能避免编造的API出现在代码差异中。
对于更具体的规则,请在.github/instructions/中创建名为something.instructions.md的文件。在前置元数据中使用applyTo: glob模式,将规则限定到匹配的文件。例如,将条形码规则限定为**/Services/**,可以避免它们影响无关请求。
如何编写助手可以据以执行的任务问题?
先编写问题,再将其分配给助手。问题正文就是助手收到的完整任务说明;一旦开始执行,就没有人在旁回答后续问题。
这是一个在三十秒内提交的问题。
Title: Barcodes not scanning
Some labels don't scan. Can we fix it?
这个问题没有提供具体信息:没有引用文件,没有指出受影响的标签,没有定义正确行为,也没有失败样本。助手只能猜测,可能会修错地方。
这是用队友希望的方式写出的相同故障。
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.
定义明确的问题包含六个要素:相关文件、框架和库版本、具体的预期输出、实际行为(包括哪些情况并未发生)、明确的约束,以及清晰的验收标准。
“标签能被IronBarcode正确解码”这一信息告诉助手,条形码本身有效,故障出在打印图像到仓库扫描仪的环节,从而大幅缩小排查范围。样本文件夹则将模糊的反馈变成助手可以测试的数据。
任务分配后,助手会自行执行,再带着结果回来供您审查。您只需检查差异,无需全程观看。
为什么助手的测试会在IronBarcode项目上失败?
助手通过GitHub Actions在GitHub的临时环境中构建和测试。除非指定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.
提交前先检查文件。作业名称必须完全匹配,SDK版本必须与项目匹配,安装依赖项的步骤必须依据Linux指南,不能凭空猜测。将文件合并到默认分支,因为工作流不会从功能分支运行。
两个要点决定了这是否有效。
首先,助手不会自动获得许可证密钥,也无法访问Actions、Codespaces或Dependabot机密。请单独存储密钥:在存储库或组织设置中打开“Secrets and variables”,选择Agents选项卡,再添加IRONBARCODE_LICENSE_KEY。Agents机密会作为环境变量提供给助手,在copilot-setup-steps.yml中也可使用。
其次,即使设置步骤失败,Copilot仍会继续执行。它会跳过剩余步骤,在运行器当前的状态下开始工作。悄然失败的依赖项安装随后就会表现得像代码错误。在依赖该工作流之前,请先从Actions选项卡手动触发一次。
合并前应检查什么?
像审查队友的分支一样审查助手的拉取请求。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.
避免字节比较可防止测试出现波动,因为即使解码的条形码保持不变,不同的图像编码器可能会在版本和平台之间生成不同的字节。
错误是在代码还是扫描中?
读取失败是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.
先诊断原因,您就能核查推理,而不必梳理未经解释的更改。同时应将更改限定在读取器端,否则助手可能通过重新打印所有标签来解决扫描问题。以下三个文档页面介绍了相关设置:速度、裁剪区域和图像校正。
前文介绍了另一种情况:代码在本机上能正确读取,却在容器或运行器上失败,此时问题通常不在代码。请粘贴完整异常而非摘要,并让助手检查平台包和Dockerfile,而非应用程序。缺少原生库应在镜像中解决,而不是修改源代码。如果不限定范围,助手可能会添加try/catch,掩盖故障而没有真正修复。
如何让无人值守的任务持续正常运行?
先做好两项配置。.github/copilot-instructions.md中的指令既能指导白天的IDE操作,也能指导助手夜间在分支上执行任务。通过copilot-setup-steps.yml安装IronBarcode的原生依赖项,并在Agents机密中保存密钥,可避免助手调试原本没有问题的代码。其他操作都属于助手的常规用法,有了这两项配置,执行会更顺利。
无论是在补全完成十秒后审查,还是在收到拉取请求后的第二天早晨审查,标准都相同,均依据AI编码助手和代理指南中的固定标准评估。Claude Code、ChatGPT Codex、Cursor和Google Antigravity也各有专门指南。
故障排除
- 拉取请求中的所有条形码测试均失败时,请参阅在IronBarcode中应用许可证密钥。
- 标签在本地能够扫描、在仓库却无法扫描时,请参阅条形码未被识别。
- 需要固定指令文件中应指定的包时,请参阅IronBarcode NuGet包。
- 运行器需要安装哪些原生依赖项,请参阅在Linux上使用IronBarcode。
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。