如何使用IronQR搭配Google Antigravity
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位元組的文件,除非調用提高該限制,根據Microsoft的Blazor檔案上傳指南,手機照片大多遠超此限。 當您運行agy -p與--dangerously-skip-permissions時,每個工具調用都得到批准,因此需一起檢查計劃和差異。
給代理變數名為IRONQR_LICENSE_KEY,而不是值。 編寫文件和運行命令的代理可以將粘貼的金鑰複製到提交或日誌中。 IronQR也會從appsettings.json讀取IronQr.LicenseKey條目,很容易不小心提交。 授權金鑰指南涵蓋了所有選項。
最小工作流程(5 個步驟)
- 從NuGet下載C# QR Code程式庫
- 從在localhost上建置和運行的Blazor Web App開始
- 使掃描儀頁面具備互動性並將上傳限制設定在您的最大照片之上
- 用
/browser上傳每個測試圖片並截圖顯示的頁面內容 - 將每個顯示的值與預期列表進行比較
Google Antigravity是什麼,它與聊天助手有何不同?
Antigravity運行代理來計劃更改、編輯代碼、使用終端,並驅動瀏覽器,然後報告您可檢查的工件,而無需觀察每一步。Google將Antigravity 2.0描述為管理代理的獨立桌面應用程式,而命令行介面 (CLI)安裝為agy。
留給代理選擇套件可能會猜測其名稱,而攻擊者提前註冊合理的名稱並將其填充惡意軟體,這種做法稱為slopsquatting。 將套件命名為IronQR,將命名空間命名為IronQr。
IronQR的文件連結代理和單提示接受測試的文件在AI編碼協助指南中。
在計劃、差異和過場中應該檢查什麼?
實施計劃還應說明頁面顯示的圖像是否不含碼和多個圖像。
在程式碼差異中,檢查看上傳如何變為AnyBitmap,並在API參考文件中查找差異中使用的每個IronQR成員。
對於瀏覽器任務,Google表示過場通常會包含代理所做動作的截屏和錄音。 在我們的命令行運行中,對話中的每個任務重寫了相同的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上傳了七張測試圖片。以下每個缺陷都乾淨地編譯。 添加渲染模式後,七張圖片中的五張顯示了正確的值。
- 對於每個圖片都保持未啟用的掃描按鈕需要快速入門計劃中所述的渲染模式。
- 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掃描器指南將上傳複製到以客戶端文件名命名的臨時文件,並從磁碟打開它。 兩個同時上傳相同名稱文件的桌面可能會衝突,Microsoft表示絕不應將上傳保存為用戶端提供的名稱。
AnyBitmap.FromStream避免了文件,但上傳背後的瀏覽器流不可尋找且拒絕同步讀取。 在IronQR 2026.10.1中,具有這些限制的流直接傳入會引發NotSupportedException。 在讀取之前複製上傳到MemoryStream與CopyToAsync可以工作。 Microsoft不建議在伺服器內存中緩衝整個上傳,因此上傳上限也會限制緩衝。
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秒。 每次讀取一個新讀者並沒有帶回延遲,所以成本是每次進程的。 第一次僅基本掃描讀取,包括加載文件,花費了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在自動和僅基本掃描下以不同的順序返回兩個通行,這就是為什麼測試比較集合。
如何將掃描儀部署到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原生閱讀器。 一個PackageReference根據RuntimeIdentifier條件為每個構建選擇了正確的套件。
兩個原生庫都鏈接到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照片之上,並且列出了每個結果,因此指南頁上的兩個上傳缺陷從未出現。
- 在預熱之前第一次上傳重啟後花費3315毫秒,預熱後901毫秒。
- 在代理自己的上傳表中,7行中的6行先通過,兩通行值排序後7在7中通過。
- 我們對最終應用的上傳檢查7在7中通過,xUnit測試8在8中通過。
- 發行版編譯完成,有0個警告和0個錯誤。
ReaderInterop.so在linux-x64發布中達到21,475,192位元組。- 兩個計劃優先提示在同一回合寫了計劃和更改了文件,一個代理完成了雙代理提示的工作。
- 瀏覽器截圖和
linux-x64發布文件夾保留在倉庫中。
中心的運行記錄列出Antigravity版本、模型與運行時長,以及運行使用的機器。
疑難排解
- 這份指南擴展的Blazor QR碼掃描器基礎頁面
- 在首次掃描前檢查鑰匙是否應用的IronQR中應用授權金鑰
- 在自動和OnlyBasicScan之間進行選擇的通過掃描模式讀取QR碼
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。