Cómo usar IronQR con Google Antigravity
Una página de carga de Blazor puede construirse sin advertencias, pero aún así fallar al procesar archivos de usuario correctamente. El proceso de compilación no indica si la página carece de interactividad, si las imágenes grandes superan los límites de carga o si las imágenes que contienen múltiples pasadas se procesan solo parcialmente. Estos problemas solo se hacen evidentes durante las pruebas en el mundo real.
Google Antigravity aborda este desafío. Su comando /browser selecciona archivos en el control de carga. IronQR descodifica las imágenes cargadas del lado del servidor utilizando QrReader.Read, por lo que la página no necesita un escáner JavaScript. Esta guía demuestra cómo construir una página de registro de visitantes usando ambas herramientas y valida los resultados comparando cada archivo cargado con sus valores esperados y los valores mostrados en la página.
Una nota sobre la terminología. IronQR incluye un modelo de aprendizaje automático para detectar códigos QR en imágenes desafiantes, como se detalla en la guía de modos de escaneo. En esta guía, 'AI' se refiere al agente de codificación responsable de escribir y probar la página.
Inicio rápidoAbre el proyecto Blazor en Antigravity y especifica la configuración deseada de la página con /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.
El plan tiene que declarar dos configuraciones. Una aplicación web Blazor renderiza una página estáticamente a menos que la página opte por la interactividad, como explica la guía de modos de renderizado. OpenReadStream rechaza cualquier archivo superior a 512,000 bytes a menos que la llamada eleve ese límite, según la guía de carga de archivos Blazor de Microsoft, y las fotos de teléfonos son mucho más grandes. Cuando ejecutas agy -p con --dangerously-skip-permissions, cada llamada a la herramienta es aprobada, por lo que revisa el plan y el diff juntos.
Dale al agente el nombre de variable IRONQR_LICENSE_KEY, nunca el valor. Un agente que escribe archivos y ejecuta comandos puede copiar una clave pegada en un commit o un log. IronQR también lee una entrada IronQr.LicenseKey de appsettings.json, lo cual es fácil de cometer por accidente. La guía de claves de licencia cubre todas las opciones.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de códigos QR C# desde NuGet
- Comienza desde una aplicación web Blazor que se compila y ejecuta en localhost
- Haz la página del escáner interactiva y limita las cargas por encima de tu foto más grande
- Haz que
/browsercargue cada imagen de prueba y capture lo que muestra la página - Compara cada valor mostrado con la lista esperada
¿Qué es Google Antigravity y en qué se diferencia de un asistente de chat?
Antigravity ejecuta agentes que planean un cambio, editan el código, usan un terminal y manejan un navegador, luego informan en Artefactos que puedes revisar en lugar de ver cada paso. Google describe Antigravity 2.0 como una aplicación de escritorio independiente para gestionar agentes, y la CLI se instala como agy.
Un agente que queda para elegir un paquete puede adivinar su nombre, y los atacantes registran nombres plausibles por adelantado y los llenan de malware, una práctica llamada slopsquatting. Nombra el paquete IronQR y el espacio de nombres IronQr.
Los enlaces de documentación de IronQR para agentes y una prueba de aceptación de un solo aviso están en la guía de asistentes de codificación AI.
¿Qué debes revisar en el plan, el diff y el Recorrido?
El Plan de Implementación también debería indicar qué muestra la página para una imagen sin código y para una imagen con varios.
En el diff de código, verifica cómo la carga se convierte en un AnyBitmap, y consulta cada miembro de IronQR que el diff utiliza en la referencia de API.
Para tareas de navegador, Google dice que el Recorrido a menudo contiene capturas de pantalla y grabaciones de lo que hizo el agente. En nuestra ejecución de CLI, cada tarea en la conversación reescribió el mismo walkthrough.md, por lo que solo contenía el informe de la última tarea. Copia cualquier tabla que quieras conservar antes de enviar el siguiente aviso.
¿Cómo pruebas la página de carga de IronQR en un navegador real?
El comando /browser inicia un subagente de Chrome en caja de arena que abre páginas y captura capturas de pantalla, según la referencia de comandos slash. Solicita una tabla que solo pueda completar subiendo archivos.
/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.
Una corrección a la lista de resultados cambia el marcado para cada imagen, por lo que solo una ejecución completa muestra que nada retrocedió.
Cada captura de pantalla se guarda como un artefacto de imagen. Cuando una muestra un problema, como un número de pase cortado, coméntalo en lugar de describirlo en un nuevo aviso.
¿Qué causa valores de QR faltantes o incorrectos?
La mayoría de las filas fallidas se remontan a unas pocas causas, y nombrar la más probable en una tarea de seguimiento ahorra al agente una ronda de prueba y error. Colocamos la página de la guía del escáner Blazor de IronQR en una nueva plantilla de .NET 9 y cargamos las siete imágenes de prueba a través de Chrome sin cabeza con IronQR 2026.10.1. Todos los defectos a continuación se compilaron sin problemas. Con el modo de renderizado agregado, cinco de siete imágenes mostraron el valor correcto.
- Un botón de Escanear que permanece deshabilitado para cada imagen necesita el modo de renderizado que establece el plan Quickstart.
- La foto de 48 MP (17,955,400 bytes) excede el límite de 10,000,000 bytes de la guía y deja el botón deshabilitado sin mensaje. Establece un límite superior a tu foto más grande y muestra un mensaje para archivos más grandes.
- Cuando una imagen de dos pasadas muestra un valor, enumera cada resultado.
¿Cómo configuras el proyecto y sus reglas para Antigravity?
Dale al agente un proyecto que ya se construya y funcione. Créalo con dotnet new blazor --interactivity Server --framework net9.0, ejecútalo una vez y anota el URL en Properties/launchSettings.json. La plantilla elige un puerto diferente para cada proyecto, y el aviso /browser lo necesita.
Luego delega la verificación del paquete y la clave.
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.
Utiliza la versión informada en cada tarea posterior. Sin una clave, la descodificación falla con LicensingException y "Licencia de Producción Requerida", por lo que una variable faltante falla el primer escaneo.
Una vez que la tabla de carga pasa, escribe las reglas. Antigravity carga AGENTS.md y GEMINI.md en cada nivel de carpeta hasta la raíz del espacio de trabajo, según su documentación de reglas, y /learn convierte las correcciones de una sesión en reglas persistentes.
/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.
Cada tarea posterior carga ese archivo, por lo que las solicitudes dejan de repetir el modo de renderizado. Una tarea que cambia una regla también debe cambiar el archivo. En nuestra ejecución, AGENTS.md mantuvo el límite de 30 MB del plan Quickstart después de que el reajuste de carga movió el servicio a 25 MB.
¿Cómo descodificas una carga sin un archivo temporal?
IronQR lee imágenes como AnyBitmap, por lo que la página debe convertir la carga del navegador en uno. La guía del escáner Blazor copia la carga a un archivo temporal nombrado como el nombre del archivo del cliente y lo abre desde el disco. Dos escritorios que cargan archivos con el mismo nombre a la vez pueden colisionar, y Microsoft dice que nunca se guarde una carga bajo un nombre proporcionado por el cliente.
AnyBitmap.FromStream evita el archivo, pero la corriente del navegador detrás de la carga no puede buscar y rechaza lecturas sincrónicas. En IronQR 2026.10.1, una corriente con esos límites pasada directamente lanza NotSupportedException. Copiar la carga a un MemoryStream con CopyToAsync antes de la lectura funciona. Microsoft desaconseja almacenar en buffer cargas completas en la memoria del servidor, por lo que el límite de carga también limita el buffer.
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.
Busca un servicio de este tipo en el diff. Compilamos esta versión contra IronQR 2026.10.1, y una página que lo llamó mostró los valores correctos para las siete imágenes de prueba.
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();
}
}
QrResult.Url se establece solo cuando el valor es un URI válido, lo que es adecuado para un escritorio donde algunas pasadas llevan un enlace y otras solo un número de pase.
¿Por qué es lenta la primera exploración después de un reinicio?
El paquete IronQR incluye IronQrDetection.dll, un ensamblado de 44 MB en 2026.10.1 que es casi completamente un recurso incrustado, y depende de Microsoft.ML.OnnxRuntime 1.20.1 para ejecutar el modelo de detección. QrScanMode.Auto prueba el detector antes de un escaneo básico, que solo se ejecuta cuando el detector no encuentra nada.
En tres procesos de consola nuevos que leen una imagen limpia, la primera lectura Auto tomó de 3.1 a 4.7 segundos y las lecturas posteriores tomaron de 0.5 a 1.0 segundos. Un nuevo lector por lectura no trajo de vuelta la demora, por lo que el costo es por proceso. La primera lectura OnlyBasicScan, incluida la carga del archivo, tomó de 0.33 a 0.56 segundos. En Blazor Server, el primer visitante después de un reinicio o escalado espera a menos que la aplicación cargue el detector al inicio.
/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.
Un calentamiento IHostedService que bloquea el inicio intercambia una carga inicial lenta por una carga lenta de la primera página, y las mediciones del agente muestran cuál construyó.
¿Cuándo deberías enviar más de un agente?
Un agente de prueba y un agente navegador verifican cosas diferentes, los resultados del servicio en el código y lo que el personal ve en la página.
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.
En nuestras pruebas, IronQR devolvió las dos pasadas en un orden diferente en Auto que en OnlyBasicScan, por lo que las pruebas comparan conjuntos.
¿Cómo despliegas el escáner en un contenedor de Linux?
IronQR 2026.10.1 también depende de IronQR.Slim y IronSoftware.ReaderInternals.Windows, y IronQR.Linux intercambia los internos de Windows por 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.
La carpeta de publicación es la evidencia, y puedes inspeccionarla en Windows. Con el paquete de Windows IronQR, una publicación linux-x64 llevaba las bibliotecas de tiempo de ejecución de ONNX pero no ReaderInterop.so, el lector nativo de Linux. Un PackageReference condicionado a RuntimeIdentifier eligió el paquete correcto para cada compilación.
Ambas bibliotecas nativas están vinculadas contra glibc, y ninguno de los paquetes envía una compilación musl, por lo que una imagen base Alpine no tiene nada que cargar. IronSoftware.ReaderInternals.Linux 2026.3.47413 solo envía una compilación linux-x64, por lo que Linux ARM64 está fuera de lo que IronQR.Linux 2026.10.1 cubre. Si los DLLs del detector faltan en la carpeta de salida, IronQR lanza IronQrRuntimesCopyException, y la página de excepción de copia de tiempos de ejecución proporciona la solución. La guía de paquetes NuGet enumera cada paquete de plataforma, y IronQR.Slim solo ejecuta OnlyBasicScan sin el modelo de detección.
¿Qué produjeron los prompts en una ejecución real?
Los ocho avisos anteriores se ejecutaron en orden en una conversación de CLI de Antigravity, sin supervisión con --dangerously-skip-permissions, contra una aplicación web Blazor .NET 9 nueva con modo de renderizado Interactive Server. El repositorio contenía siete imágenes de prueba con valores conocidos, enumerados en TestData/scans/expected.csv. Eran una captura de pantalla limpia, una foto de teléfono de 12 MP y una de 48 MP, una imagen de dos pasadas, una foto inclinada en mala luz, un pase que lleva un URL y una foto de escritorio sin pase. La clave llegó al agente solo a través del entorno. Después de la ejecución, reconstruimos la aplicación en Release, ejecutamos las pruebas y subimos cada imagen a través de Chrome sin cabeza nosotros mismos.
Dado que el plan Quickstart ya limitó las cargas por encima de la foto de 48 MP y enumeró cada resultado, los dos defectos de carga de la página de la guía nunca aparecieron.
- La primera carga después de un reinicio tomó 3,315 ms antes del calentamiento y 901 ms después.
- En la propia tabla de carga del agente, 6 de 7 filas pasaron, luego 7 de 7 una vez ordenados los valores de dos pasadas.
- Nuestra verificación de carga de la aplicación final pasó 7 de 7, y las pruebas xUnit pasaron 8 de 8.
- La compilación de Release terminó con 0 advertencias y 0 errores.
ReaderInterop.soen la publicaciónlinux-x64llegó a 21,475,192 bytes.- Ambos avisos de plan primero escribieron el plan y cambiaron archivos en el mismo turno, y un agente hizo el trabajo del aviso de dos agentes.
- Las capturas de pantalla del navegador y la carpeta de publicación
linux-x64quedaron en el repositorio.
El registro de ejecución del hub enumera la versión de Antigravity, el modelo y el tiempo de ejecución, y la máquina que utilizó la ejecución.
Solución de problemas
- Escáner de Código QR Blazor para la base de página que extiende esta guía
- Aplicar una Clave de Licencia en IronQR para verificar que la clave se aplique antes del primer escaneo
- Leer Códigos QR con Modos de Escaneo para elegir entre Auto y OnlyBasicScan
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.