如何在Google Antigravity中使用IronQR
Blazor上传页面可能构建时没有警告,但仍无法正确处理用户文件。 构建过程中无法指示页面是否缺乏互动性、或者大图像超过上传限制、又或者是多重传递的图像仅部分处理。 这些问题仅在实际测试中才会显现。
Google Antigravity解决了这一挑战。 其/browser命令选择上传控件中的文件。 IronQR在服务器端使用QrReader.Read解码上传的图像,因此页面不需要JavaScript扫描器。 本指南演示如何同时使用这两个工具构建访客签到页面,并通过将每个上传文件与其预期值以及页面上显示的值进行比较来验证结果。
关于术语的一个说明。 IronQR包括一个用于在复杂图像中检测QR码的机器学习模型,具体细节请参考扫描模式指南。 在本指南中,'AI'指的是负责编写和测试页面的编码代理。
快速入门在Antigravity中打开Blazor项目,并通过/plan指定所需的页面配置。
/plan This repo is a .NET 9 Blazor Web App with Interactive Server render
mode. Add a visitor check-in page at /scanner. Staff pick a photo of a visitor
pass with InputFile, the server decodes it with IronQR (NuGet package IronQR,
namespace IronQr) by loading the upload into an AnyBitmap and calling
QrReader.Read, and the page lists every value found. Set
IronQr.License.LicenseKey once in Program.cs, read from IRONQR_LICENSE_KEY in
the environment, and never write the key to a file. Add a NavMenu link.
In the Implementation Plan, state the render mode the page will use and the
largest upload it will accept. Then build until dotnet build is clean.
计划需说明两个设置。 Blazor Web App会静态渲染页面,除非页面选择加入互动,如渲染模式指南所述。 除非调用提升该限制,否则OpenReadStream拒绝任何超过512,000字节的文件,根据微软的Blazor文件上传指南,而手机照片往往远大于此。 当您使用agy -p结合--dangerously-skip-permissions运行时,每个工具调用都会被批准,所以请同时查看计划和差异。
给代理分配变量名IRONQR_LICENSE_KEY,而不是值。 能够写入文件和运行命令的代理可以将粘贴的密钥复制到提交或日志中。 IronQR还会读取IronQr.LicenseKey来自appsettings.json的条目,这很容易意外提交。 许可证密钥指南涵盖了每一种选项。
最小工作流程(5 个步骤)
- 从NuGet下载C#二维码库
- 从能在本地主机上构建和运行的Blazor Web App开始
- 使扫描器页面具有互动性,并将上传容量设在您最大的照片之上
- 让
/browser上传每个测试图像,并截屏页面显示的内容 - 将每个显示的值与预期列表进行比较
什么是Google Antigravity,它与聊天助手有何不同?
Antigravity运行代理策划更改,编辑代码,使用终端和驱动浏览器,然后报告您可以审查的成果,而无需观察每一步。Google将Antigravity 2.0描述为一个用于管理代理的独立桌面应用,与CLI一起安装为agy。
自行选择软件包的代理可能会猜测其名称,而攻击者会提前注册合理的名称并填充恶意软件,这种行为称为slopsquatting。 将软件包命名为IronQR,命名空间为IronQr。
IronQR的文档链接用于代理和一次性接受测试在AI编码助手指南中。
您应该在计划、差异和演示中检查哪些内容?
实施计划也应说明页面显示的无代码图像和多代码图像。
在代码差异中,检查上传如何变成AnyBitmap,并在API参考中查找差异使用的每个IronQR成员。
对于浏览器任务,Google说演练通常包含代理操作的截图和录音。 在我们的CLI运行中,对话中的每个任务都重写了相同的walkthrough.md,因此仅记录了最后一个任务的报告。 在发送下一个提示之前复制任何您想保留的表格。
您如何在真实浏览器中测试IronQR上传页面?
/browser命令启动隔离的Chrome子代理以打开页面并截屏,详见斜线命令参考。 要求一个只能通过上传文件填写的表格。
/browser Run the app with dotnet run (the http profile listens on
http://localhost:5181) and open /scanner. Upload each image in TestData/scans
through the page's file input, one at a time, wait until the page shows a
result or a message, and screenshot it. TestData/scans/expected.csv lists the
values each image carries, separated by | when there are several, and an empty
cell means no code. Return a Walkthrough table of file, bytes, expected values,
values the page displayed, and pass or fail. When a row fails, quote the server
log or browser console line that explains it, or say that neither recorded
anything, before you edit anything. Then fix the page, restart the app, and
upload all seven images again. Stop the app at the end.
修复结果列表会更改每个图像的标记,因此只有完整的重跑才能显示没有回归。
每个截图都保存为一个图像工件。 当其中一个显示问题,例如截断的通过编号,请对其评论而不是在新提示中描述。
缺失或错误的QR值是什么原因导致的?
大多数失败的行可追溯到少数原因,并在后续任务中命名可能的原因会为代理节省一轮试错。 我们在IronQR的Blazor扫描器指南中从头创建了一个.NET 9模板,并通过无头Chrome与IronQR 2026.10.1上传了7个测试图像。下面的每个缺陷都顺利编译。 添加渲染模式后,七张图片中的五张显示了正确的值。
- 一个保持禁用状态的扫描按钮需要快速启动计划中指出的渲染模式。
- 48 MP的照片(17,955,400字节)超过了指南的10,000,000字节上限,并留下了未显示信息的禁用按钮。 设置高于您最大照片的上限,并为较大的文件显示信息。
- 当两个传递图像显示一个值时,列出每个结果。
如何为Antigravity设置项目及其规则?
给代理一个已经能够构建和运行的项目。 用dotnet new blazor --interactivity Server --framework net9.0创建它,运行一次,并在Properties/launchSettings.json中记录URL。 模板为每个项目选择不同端口,并且/browser提示需要它。
然后委派包和密钥检查。
Tell me which IronQR version the project references and paste its
PackageReference line. Then show me where the license key is applied. It has
to be set once at startup from IRONQR_LICENSE_KEY, appsettings.json and
appsettings.Development.json must carry no IronQr.LicenseKey entry, and when
the variable is missing the app should log one startup warning that names the
variable but prints no value. Change no other file, and touch Program.cs
only if that warning is missing.
在每个后续任务中使用报告的版本。 没有密钥,解码会因LicensingException和“需要生产许可证”而失败,因此缺少的变量会导致第一次扫描失败。
一旦上传表格通过,写下规则。 Antigravity根据其规则文档在工作区根目录进行的每一层加载AGENTS.md和GEMINI.md,以及/learn将会话的更正转为持久规则。
/learn Write the rules this session established into a new AGENTS.md at the
repository root (the always-on rules file, not .antigravity/rules.md) under a
"QR check-in page" heading. Cover the render mode the scanner page needs, the
upload cap and the reason for its value, showing every decoded value instead
of the first, keeping IRONQR_LICENSE_KEY out of files, and that no scanner
change is done until the /browser upload table passes for every image in
TestData/scans.
后续任务都会加载该文件,因此提示不会重复渲染模式。 更改规则的任务也必须更改文件。 在我们的运行中,AGENTS.md在上传重构将服务移至25 MB后保持了快速启动计划中的30 MB上限。
如何在不使用临时文件的情况下解码上传?
IronQR将图像读取为AnyBitmap,因此页面必须将浏览器上传转换为该格式。 Blazor扫描器指南将上传复制到以客户端文件名命名的临时文件,并从磁盘中打开它。 同时上传相同名称文件的两个桌面可能会冲突,而微软建议永远不要在客户端提供的名称下保存上传。
AnyBitmap.FromStream可以避免文件,但上传背后的浏览器流无法定位,并拒绝同步读取。 在IronQR 2026.10.1中,直接传递这些限制的流会引发NotSupportedException。 在读取之前用CopyToAsync将上传复制到MemoryStream后解决。 微软建议不要将整个上传缓冲到服务器内存中,因此上传上限也会限制缓冲区。
Open an Implementation Plan Artifact for this refactor before editing. Move
the decoding out of the Razor page into Services/PassScanService.cs,
registered as a singleton. The service takes the IBrowserFile, rejects files
over 25 MB with a message the page shows, copies the upload into a
MemoryStream with CopyToAsync, builds the AnyBitmap from that buffer, reads it
with QrReader.ReadAsync and QrScanMode.Auto, and returns value, QrType and Url
for every result. No temporary files and no client file names on disk. Show
the scan time in milliseconds under the results. Then repeat the /browser
upload table for all seven images.
在差异中寻找沿这一思路的服务。 我们将此版本编译为IronQR 2026.10.1,调用该页面可为所有七个测试图像显示正确的值。
using IronQr;
using IronQr.Enum;
using IronSoftware.Drawing;
using Microsoft.AspNetCore.Components.Forms;
public sealed class PassScanService
{
public const long MaxUploadBytes = 25 * 1024 * 1024;
public async Task<List<QrResult>> ScanAsync(IBrowserFile file)
{
using var buffer = new MemoryStream();
await using (var upload = file.OpenReadStream(MaxUploadBytes))
{
await upload.CopyToAsync(buffer);
}
buffer.Position = 0;
using var image = AnyBitmap.FromStream(buffer);
var results = await new QrReader().ReadAsync(new QrImageInput(image, QrScanMode.Auto));
return results.ToList();
}
}
只有当值为有效URI时,QrResult.Url才被设置,这适用于某些传递携带链接而其他传递为简单通过编号的情况。
为什么重启后的第一次扫描较慢?
IronQR包包含IronQrDetection.dll,2026.10.1中的44 MB程序集几乎全部为一个嵌入的资源,并依赖于Microsoft.ML.OnnxRuntime 1.20.1来运行检测模型。 QrScanMode.Auto在基本扫描之前尝试探测器,只有在探测器找不到任何东西时才运行。
在三个干净的控制台进程中读取干净图像,第一次自动读取耗时3.1到4.7秒,后续读取耗时0.5到1.0秒。 每次读取的新读取器没有带回延迟,因此成本是按进程计算的。 加载文件包括在内,第一次OnlyBasicScan读取耗时0.33到0.56秒。 在Blazor Server上,重新启动或扩展后的第一个访客会等待,除非应用在启动时加载检测器。
/browser Measure the cold-start cost of the detection model. Restart the app,
upload TestData/scans/pass-clean.png three times on /scanner, and note the
scan time the page shows each time. Then add an IHostedService that reads one
small blank AnyBitmap with QrReader at startup, off the request path, restart,
repeat the three uploads, and put both sets of timings side by side in the
Walkthrough with a screenshot of each first upload.
一个IHostedService预热阻塞启动,用慢的第一次上传换为慢的第一次页面加载,代理的时间表显示它构建了哪个。
何时应指派多个代理?
测试代理和浏览器代理检查不同的东西,服务的结果在代码中,而工作人员在页面上看到的结果。
Agent A: create an xUnit project QrScanner.Tests that calls PassScanService
for every row of TestData/scans/expected.csv through a test double of
IBrowserFile, and asserts the exact set of values in any order. Add one test
that a file over the cap is rejected before IronQR reads it. Never compare
QR images byte for byte.
Agent B: start only after Agent A's tests pass against the current code. Use
/browser to upload the same seven images on /scanner, attach a screenshot of
each result to the Walkthrough, and state there that the tests passed first.
在我们的测试中,IronQR在自动模式下与在OnlyBasicScan模式下的两次传递顺序不同,这就是为什么测试比较集合的原因。
如何将扫描器部署到Linux容器?
IronQR 2026.10.1还依赖于IronQR.Slim和IronSoftware.ReaderInternals.Windows,而IronQR.Linux将Windows内部替换为IronSoftware.ReaderInternals.Linux。
This app will ship in a linux-x64 container built from
mcr.microsoft.com/dotnet/aspnet:9.0. Do not change any C#. Make the project
reference IronQR for Windows builds and IronQR.Linux when RuntimeIdentifier is
linux-x64, add a Dockerfile that publishes for linux-x64 and passes
IRONQR_LICENSE_KEY in at run time, then run dotnet publish -r linux-x64
--self-contained false -o publish-linux and list every .so file in that
folder with the NuGet package it came from. Docker is not installed on this
machine, so stop before docker build.
发布文件夹是证据,您可以在Windows上检查它。 使用Windows IronQR包,linux-x64发布携带ONNX运行时库,但不包括ReaderInterop.so,Linux原始读取器。 一个在RuntimeIdentifier上的PackageReference条件为每个构建选择正确的包。
两个本地主库都链接到glibc,两个包都没有出现musl构建,因此Alpine基础镜像没有可加载的内容。 IronSoftware.ReaderInternals.Linux 2026.3.47413仅提供linux-x64构建,因此ARM64 Linux不在IronQR.Linux 2026.10.1覆盖范围内。 如果探测器的DLL缺少输出文件夹,IronQR会抛出IronQrRuntimesCopyException,运行时复制异常页面提供了解决方法。 NuGet包指南列出了每个平台包,只有IronQR.Slim运行OnlyBasicScan而没有检测模型。
在实际运行中这些提示生成了什么?
以上八个提示在一次Antigravity CLI对话中按顺序运行,无人参与,使用--dangerously-skip-permissions,针对全新的.NET 9 Blazor Web App,启用交互式服务器渲染模式。 存储库中包含七张已知值的测试图像,列于TestData/scans/expected.csv中。 它们是一个干净的截图、一张12 MP和一张48 MP的手机照片、一个两次传递的图像、一个光线差环境中的倾斜照片、一个包含URL的传递和一个没有传递的桌面照片。 密钥仅通过环境到达代理。 运行结束后,我们在Release模式下重建应用,运行测试,然后通过无头Chrome自己上传每张图像。
因为快速启动计划已经将上传上限设在了48 MP照片之上,并列出了每个结果,所以指南页面的两个上传缺陷从未出现。
- 重启后的第一次上传在预热前用时3,315毫秒,预热后用时901毫秒。
- 在代理自己的上传表中,7行中有6行通过,后在排序两次传递值后,7行中有7行通过。
- 我们对最终应用的上传检查通过7次,xUnit测试通过8次。
- 发行版构建以 0 个警告和 0 个错误完成。
ReaderInterop.so在linux-x64发布中达到21,475,192字节。- 两个计划优先提示在同一回合编写了计划并更改了文件,其中一个代理执行了两个代理提示的工作。
- 浏览器截图和
linux-x64发布文件夹留在了仓库中。
中心的运行记录列出了Antigravity版本、模型和运行时间,以及运行所用的机器。
故障排除
- Blazor二维码扫描器为本指南扩展的基础页面
- 在IronQR中应用许可证密钥检查在第一次扫描前应用了密钥
- 通过扫描模式读取QR码选择自动和OnlyBasicScan之间
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。