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 웹 앱은 페이지가 상호작용성을 선택하지 않는 한 페이지를 정적으로 렌더링합니다. 이는 렌더링 모드 가이드에서 설명합니다. 마이크로소프트의 Blazor 파일 업로드 가이드에 따라, OpenReadStream는 호출이 해당 한계를 높이지 않는 한 512,000바이트를 초과하는 파일을 거부하며, 휴대폰 사진은 훨씬 큽니다. 당신이 agy -p를 --dangerously-skip-permissions와 함께 실행할 때, 모든 도구 호출이 승인되므로, 계획과 차이를 함께 검토하세요.
에이전트에게 IRONQR_LICENSE_KEY라는 변수명을 주고, 값을 주지 마세요. 파일을 작성하고 명령을 실행하는 에이전트는 커밋이나 로그에 붙여넣은 키를 복사할 수 있습니다. IronQR는 또한 appsettings.json에서 IronQr.LicenseKey 엔트리를 읽으며, 이는 우연히 커밋하기 쉽습니다. 라이선스 키 가이드는 모든 옵션을 다룹니다.
최소 워크플로우(5단계)
- NuGet에서 C# QR 코드 라이브러리를 다운로드하세요
- 로컬 호스트에서 구축되고 실행되는 Blazor 웹 앱에서 시작합니다.
- 스캐너 페이지를 상호작용 가능하게 만들고, 가장 큰 사진보다 업로드를 제한합니다.
/browser가 모든 테스트 이미지를 업로드하고 페이지에 나타난 것을 스크린샷으로 캡처합니다.- 표시된 각 값을 예상 목록과 비교합니다.
Google Antigravity란 무엇이며 채팅 보조와 어떻게 다른가요?
Antigravity는 변화를 계획하고, 코드를 수정하며 터미널을 사용하고, 브라우저를 제어한 다음, 각 단계를 시청하지 않고도 검토할 수 있는 Artifacts로 보고하는 에이전트를 실행합니다. Google은 Antigravity 2.0을 에이전트를 관리하기 위한 독립형 데스크탑 앱으로 묘사하며, CLI는 agy로 설치됩니다.
패키지를 선택해야 하는 에이전트는 이름을 추측할 수 있으며, 공격자들은 미리 그럴듯한 이름으로 등록하고 이를 악성 코드로 채우는 경우도 있습니다. 이를 슬롭스쿼팅이라 부릅니다. 패키지 이름을 IronQR로 하고 네임스페이스를 IronQr로 하세요.
IronQR의 에이전트를 위한 문서 링크와 한 번의 프롬프트로 수락되는 테스트는 AI 코딩 보조 가이드에 있습니다.
계획, 차이점, Walkthrough에서 무엇을 확인해야 하나요?
실행 계획에는 코드가 없는 이미지와 여러 개의 코드가 있는 이미지에 대해 페이지가 무엇을 보여주는지도 명시되어야 합니다.
코드 차이점에서 업로드가 어떻게 AnyBitmap가 되는지 확인하고, 차이점에서 사용하는 모든 IronQR 멤버를 API 레퍼런스에서 확인하세요.
브라우저 작업의 경우, Google은 Walkthrough가 종종 에이전트가 수행한 작업의 스크린샷이나 녹화를 포함한다고 설명합니다. 우리의 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.
결과 목록에 대한 수정은 모든 이미지의 마크업을 변경하기 때문에, 모든 재실행을 완료했을 때만 문제가 없음을 보여줍니다.
모든 스크린샷은 이미지 아티팩트로 저장됩니다. 문제가 발생하면, 예를 들어 지나치게 잘린 패스 번호 등, 새로운 프롬프트에서 설명하지 말고 주석을 달아주세요.
결정적 결함의 원인은 무엇인가요?
대부분의 실패 행은 몇 가지 원인으로 귀결되며, 후속 작업에서 가능성 있는 원인을 명명하는 것이 에이전트에게 반복적인 시행착오를 예방합니다. IronQR의 Blazor 스캐너 가이드에서 페이지를 새 .NET 9 템플릿에 추가하고, IronQR 2026.10.1를 사용하여 헤드리스 Chrome을 통해 7개의 테스트 이미지를 업로드했습니다. 아래의 모든 결함은 클린하게 컴파일되었습니다. 렌더 모드를 추가하였더니, 7개의 이미지 중 5개가 올바른 값을 보여주었습니다.
- 모든 이미지에 대해 비활성화된 상태로 유지되는 스캔 버튼은 빠른 시작 계획에서 명시한 렌더 모드가 필요합니다.
- 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과 "Production License Required" 에러와 함께 실패하므로, 변수 손실은 첫 번째 스캔에서 실패합니다.
업로드 테이블이 통과한 후 규칙을 문서로 작성하세요. 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.
이후의 모든 작업이 해당 파일을 로드하므로 프롬프트에서 렌더 모드를 반복하지 않도록 합니다. 규칙을 변경하는 작업은 파일도 함께 변경해야 합니다. 우리의 실행에서는, 업로드 리팩터가 서비스를 25 MB로 이동한 후에도 AGENTS.md가 빠른 시작 계획의 30 MB 제한을 유지했습니다.
임시 파일 없이 업로드를 디코딩하는 방법
IronQR는 이미지를 AnyBitmap로 읽으므로 페이지는 브라우저 업로드를 이로 변환해야 합니다. Blazor 스캐너 가이드는 클라이언트 파일 이름을 기반으로 하는 임시 파일에 업로드를 복사하고, 디스크에서 열립니다. 동시에 동일한 이름으로 파일을 업로드하는 두 개의 데스크는 충돌할 수 있으며, Microsoft는 클라이언트가 제공한 이름으로 파일을 저장하지 말라고 권고합니다.
브라우저 뒤에 있는 업로드 스트림은 탐색할 수 없으며, 동기화된 읽기를 거부하므로 AnyBitmap.FromStream는 파일을 피합니다. IronQR 2026.10.1에서는, 이러한 제한을 가진 스트림이 직접 전달되면 NotSupportedException을 발생시킵니다. 복사하여 읽기 전에 CopyToAsync와 함께 업로드를 MemoryStream에 넣으면 작동합니다. 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을 사용하여 컴파일하였으며, 이를 호출한 페이지는 모든 7개 테스트 이미지에 대해 올바른 값을 보여주었습니다.
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는 기본 스캔 이전에 감지기를 시도하며, 감지기가 아무것도 찾지 못할 때만 실행됩니다.
깨끗한 이미지를 읽는 세 개의 새로운 콘솔 프로세스에서, 처음 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는 Auto가 아니고 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 네이티브 리더를 포함하지 않았습니다. 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 웹 앱의 Interactive Server 렌더 모드에서 순서대로 실행되었습니다. 저장소에는 알려진 값이 포함된 7개의 테스트 이미지가 TestData/scans/expected.csv에 나열되어 있었습니다. 이들은 깨끗한 스크린샷, 12 MP 및 48 MP 휴대폰 사진, 두 개의 패스를 가진 이미지, 나쁜 조명에서 기울어진 사진, URL을 포함한 패스, 패스가 없는 데스크 사진이었습니다. 키는 환경을 통해서만 에이전트에게 도달했습니다. 실행 후, 우리는 앱을 Release 모드로 재구축하고, 테스트를 실행하였으며, 직접 헤드리스 Chrome을 통해 모든 이미지를 업로드하였습니다.
빠른 시작 계획은 이미 48 MP 사진을 초과하여 업로드를 한정하고 모든 결과를 나열했으므로, 안내서 페이지의 두 가지 업로드 결함은 나타나지 않았습니다.
- 재시작 후 첫 업로드는 워밍업 전 3,315ms가 걸렸고, 워밍업 후에는 901ms가 걸렸습니다.
- 에이전트 자체의 업로드 테이블에서, 7개 중 6개 행이 통과했고, 두 패스 값을 정렬한 후에는 7개 중 7개가 통과했습니다.
- 최종 앱의 업로드 체크에서 7개 중 7개가 통과했으며, xUnit 테스트도 8개 중 8개가 통과했습니다.
- 릴리스 빌드는 경고 0 및 오류 0으로 완료되었습니다.
ReaderInterop.so는linux-x64게시에서 21,475,192 바이트에 도달했습니다.- 두 계획 우선 프롬프트는 동일한 턴에서 계획을 작성하고 파일을 변경했으며, 하나의 에이전트가 두 에이전트 프롬프트의 작업을 수행했습니다.
- 브라우저 스크린샷 및
linux-x64게시 폴더가 저장소에 남겨졌습니다.
허브의 실행 기록은 Antigravity 버전, 모델, 실행 시간을 나열하며, 실행에 사용된 기계를 나열합니다.
문제 해결
- 본 가이드의 기반 페이지 Blazor QR 코드 스캐너
- 첫 번째 스캔 전에 키가 적용되었는지 확인하기 위해 IronQR에서 라이선스 키 적용
- Auto와 OnlyBasicScan 중에서 선택하기 위해 스캔 모드로 QR 코드 읽기
질문?
질문이 있으시면 support@ironsoftware.com으로 문의하세요.
커티스 차우는 칼턴 대학교에서 컴퓨터 과학 학사 학위를 취득했으며, Node.js, TypeScript, JavaScript, React를 전문으로 하는 프론트엔드 개발자입니다. 직관적이고 미적으로 뛰어난 사용자 인터페이스를 만드는 데 열정을 가진 그는 최신 프레임워크를 활용하고, 잘 구성되고 시각적으로 매력적인 매뉴얼을 제작하는 것을 즐깁니다.