Como Usar IronQR com Google Antigravity

Curtis Chau
Curtis Chau
Atualizado: 9 de outubro de 2026

Uma página de upload Blazor pode compilar sem avisos, mas ainda assim falhar ao processar arquivos de usuário corretamente. O processo de compilação não indica se a página carece de interatividade, se imagens grandes excedem os limites de upload, ou se imagens contendo múltiplas passagens são processadas apenas parcialmente. Esses problemas só se tornam aparentes durante testes no mundo real.

Google Antigravity aborda esse desafio. Seu comando /browser seleciona arquivos no controle de upload. IronQR decodifica imagens enviadas no lado do servidor usando QrReader.Read, então a página não precisa de um scanner JavaScript. Este guia demonstra como construir uma página de check-in de visitantes usando ambas as ferramentas e valida os resultados comparando cada arquivo enviado com seus valores esperados e os valores exibidos na página.

Uma nota sobre terminologia. IronQR inclui um modelo de aprendizado de máquina para detectar códigos QR em imagens desafiadoras, conforme detalhado no guia de modos de escaneamento. Neste guia, 'IA' refere-se ao agente de codificação responsável por escrever e testar a página.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronQR

Instale o IronQR executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Abra o projeto Blazor no Antigravity e especifique a configuração de página desejada com /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.
Text

O plano deve declarar duas configurações. Um Aplicativo Web Blazor renderiza uma página estaticamente a menos que a página opte por interatividade, como explica o guia de modos de renderização. OpenReadStream rejeita qualquer arquivo acima de 512.000 bytes, a menos que a chamada aumente esse limite, de acordo com o guia de upload de arquivos Blazor da Microsoft, e fotos de telefone são muito maiores. Quando você executa agy -p com --dangerously-skip-permissions, cada chamada de ferramenta é aprovada, então revise o plano e o diff juntos.

Dê ao agente o nome de variável IRONQR_LICENSE_KEY, nunca o valor. Um agente que escreve arquivos e executa comandos pode copiar uma chave colada para um commit ou um log. IronQR também lê uma entrada IronQr.LicenseKey de appsettings.json, o que é fácil de cometer por acidente. O guia de chaves de licença cobre todas as opções.



O que é o Google Antigravity e como é diferente de um assistente de chat?

Antigravity executa agentes que planejam uma mudança, editam o código, usam um terminal, e dirigem um navegador, depois reportam de volta em Artefatos que você pode revisitar em vez de assistir cada passo. Google descreve o Antigravity 2.0 como um aplicativo de desktop independente para gerenciar agentes, e a CLI é instalada como agy.

Um agente deixado para escolher um pacote pode adivinhar seu nome, e os atacantes registram nomes plausíveis com antecedência e os preenchem com malware, uma prática chamada slopsquatting. Nomeie o pacote IronQR e o namespace IronQr.

Os links de documentação do IronQR para agentes e teste de aceitação em um único prompt estão no guia de assistentes de codificação com IA.

O que você deve verificar no plano, no diff e no Walkthrough?

O Plano de Implementação também deve dizer o que a página mostra para uma imagem sem código e para uma imagem com vários.

No diff de código, verifique como o upload se torna uma AnyBitmap, e procure cada membro do IronQR que o diff usa na referência de API.

Para tarefas de navegador, o Google diz que o Walkthrough geralmente contém capturas de tela e gravações do que o agente fez. Em nossa execução da CLI, cada tarefa na conversa reescreveu a mesma walkthrough.md, então ela só continha o relatório da última tarefa. Copie qualquer tabela que você queira manter antes de enviar o próximo prompt.

Como você testa a página de upload do IronQR em um navegador real?

O comando /browser inicia um subagente do Chrome isolado que abre páginas e captura capturas de tela, conforme a referência de comandos de barra. Peça uma tabela que ele só possa preencher enviando arquivos.

/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.
Text

Uma correção na lista de resultados muda a marcação para cada imagem, então apenas uma nova execução completa mostra que nada regrediu.

Por favor, note: Abra a captura de tela para a maior foto primeiro. Um upload com tamanho excessivo pode falhar sem uma linha no log do servidor, então um relatório construído apenas de logs chamaria essa linha um sucesso.

Cada captura de tela é salva como um artefato de imagem. Quando uma mostra um problema, como um número de passagem cortado, comente sobre isso ao invés de descrevê-lo em um novo prompt.

O que causa valores QR ausentes ou incorretos?

A maioria das linhas falhadas pode ser rastreada para algumas causas, e nomear a mais provável em uma tarefa de acompanhamento poupa ao agente uma rodada de tentativa e erro. Colocamos a página do guia de scanner Blazor do IronQR em um novo template .NET 9 e enviamos as sete imagens de teste através do Chrome sem cabeçalho com o IronQR 2026.10.1. Cada defeito abaixo compilou corretamente. Com o modo de renderização adicionado, cinco de sete imagens mostraram o valor correto.

  • Um botão de Escanear que permanece desativado para cada imagem precisa do modo de renderização que o plano Quickstart declara.
  • A foto de 48 MP (17.955.400 bytes) excede o limite de 10.000.000 bytes do guia e deixa o botão desativado sem mensagem. Defina um limite acima da sua maior foto e mostre uma mensagem para arquivos maiores.
  • Quando uma imagem de duas passagens mostra um valor, liste cada resultado.

Como você configura o projeto e suas regras para o Antigravity?

Dê ao agente um projeto que já compila e executa. Crie-o com dotnet new blazor --interactivity Server --framework net9.0, execute-o uma vez e anote o URL em Properties/launchSettings.json. O template escolhe uma porta diferente para cada projeto, e o prompt /browser precisa dela.

Então delegue a verificação de pacote e chave.

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.
Text

Use a versão reportada em cada tarefa posterior. Sem uma chave, a decodificação falha com LicensingException e "Production License Required", então uma variável ausente falha na primeira verificação.

Uma vez que a tabela de upload passar, escreva as regras. Antigravity carrega AGENTS.md e GEMINI.md em cada nível de pasta até a raiz do espaço de trabalho, conforme sua documentação de regras, e /learn transforma as correções de uma sessão em regras 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.
Text

Cada tarefa posterior carrega esse arquivo, então os prompts param de repetir o modo de renderização. Uma tarefa que muda uma regra também deve mudar o arquivo. Na nossa execução, AGENTS.md manteve o limite de 30 MB do plano Quickstart após a reformulação do upload mover o serviço para 25 MB.

Como você decodifica um upload sem um arquivo temporário?

IronQR lê imagens como AnyBitmap, então a página precisa transformar o upload do navegador em um. O guia de scanner Blazor copia o upload para um arquivo temporário nomeado após o nome do arquivo do cliente e o abre do disco. Duas mesas que enviam arquivos com o mesmo nome ao mesmo tempo podem colidir, e a Microsoft diz para nunca salvar um upload sob um nome fornecido pelo cliente.

AnyBitmap.FromStream evita o arquivo, mas o fluxo do navegador por trás do upload não pode buscar e rejeita leituras síncronas. No IronQR 2026.10.1, um fluxo com esses limites passado diretamente lança NotSupportedException. Copiar o upload em um MemoryStream com CopyToAsync antes da leitura funciona. A Microsoft aconselha contra o armazenamento de uploads inteiros na memória do servidor, então o limite de upload também limita o 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.
Text

Procure um serviço ao longo dessas linhas no diff. Compilamos esta versão contra o IronQR 2026.10.1, e uma página que a chamou mostrou os valores corretos para todas as sete imagens de teste.

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();
    }
}
C#

QrResult.Url é definido apenas quando o valor é um URI válido, o que se adequa a uma mesa em que algumas passagens carregam um link e outras um simples número de passagem.

Por que a primeira verificação após uma reinicialização é lenta?

O pacote IronQR inclui IronQrDetection.dll, uma assembly de 44 MB em 2026.10.1 que é quase totalmente um recurso incorporado, e depende de Microsoft.ML.OnnxRuntime 1.20.1 para executar o modelo de detecção. QrScanMode.Auto tenta o detector antes de uma verificação básica, que só corre quando o detector não encontra nada.

Em três processos de console novos lendo uma imagem limpa, a primeira leitura Auto levou de 3,1 a 4,7 segundos e as leituras posteriores levaram de 0,5 a 1,0 segundos. Um novo leitor por leitura não trouxe o atraso de volta, então o custo é por processo. A primeira leitura OnlyBasicScan, incluindo o carregamento do arquivo, levou de 0,33 a 0,56 segundos. No Blazor Server, o primeiro visitante após uma reinicialização ou expansão espera a menos que o aplicativo carregue o detector na inicialização.

/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.
Text

Um aquecimento IHostedService que bloqueia a inicialização troca um upload inicial lento por um carregamento de página inicial lento, e os tempos do agente mostram qual deles ele construiu.

Quando você deve despachar mais de um agente?

Um agente de teste e um agente de navegador verificam coisas diferentes, os resultados do serviço no código e o que a equipe vê na 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.
Text

Em nossos testes, IronQR retornou as duas passagens em uma ordem diferente no modo Auto do que no OnlyBasicScan, por isso os testes comparam conjuntos.

Por favor, note: No aplicativo de desktop, dê a cada agente sua própria tarefa e compare os dois Walkthroughs.

Como você implanta o scanner em um container Linux?

IronQR 2026.10.1 também depende de IronQR.Slim e IronSoftware.ReaderInternals.Windows, e IronQR.Linux troca as internas do 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.
Text

A pasta de publicação é a evidência, e você pode inspecioná-la no Windows. Com o pacote IronQR do Windows, uma publicação linux-x64 carregou as bibliotecas ONNX Runtime, mas não ReaderInterop.so, o leitor nativo Linux. Um PackageReference condicionado a RuntimeIdentifier escolheu o pacote certo para cada build.

Ambas as bibliotecas nativas linkam contra glibc, e nenhum pacote envia uma build musl, então uma imagem base Alpine não tem nada para carregar. IronSoftware.ReaderInternals.Linux 2026.3.47413 envia apenas uma build linux-x64, então Linux ARM64 está fora do que IronQR.Linux 2026.10.1 cobre. Se as DLLs do detector não estiverem na pasta de saída, IronQR lança IronQrRuntimesCopyException, e a página de exceção de cópia de runtimes fornece a correção. O guia de pacotes NuGet lista cada pacote de plataforma, e IronQR.Slim sozinho executa OnlyBasicScan sem o modelo de detecção.

O que os prompts produziram em uma execução real?

Os oito prompts acima foram executados em ordem em uma conversa CLI do Antigravity, sem supervisão com --dangerously-skip-permissions, contra um Blazor Web App .NET 9 fresco com modo de renderização Interactive Server. O repositório continha sete imagens de teste com valores conhecidos, listados em TestData/scans/expected.csv. Eram uma captura de tela limpa, uma foto de telefone de 12 MP e uma de 48 MP, uma imagem de duas passagens, uma foto inclinada em pouca luz, uma passagem que carrega um URL, e uma foto de mesa sem passagem. A chave chegou ao agente apenas através do ambiente. Após a execução, reconstruímos o aplicativo em Release, executamos os testes e enviamos cada imagem através do Chrome sem cabeçalho nós mesmos.

Como o plano Quickstart já limitava uploads acima da foto de 48 MP e listava cada resultado, os dois defeitos de upload da página do guia nunca apareceram.

  • O primeiro upload após uma reinicialização levou 3.315 ms antes do aquecimento e 901 ms depois disso.
  • Na própria tabela de upload do agente, 6 de 7 linhas passaram, depois 7 de 7 uma vez que os valores de duas passagens foram ordenados.
  • Nossa verificação de upload do aplicativo final passou 7 de 7, e os testes xUnit passaram 8 de 8.
  • A compilação Release terminou com 0 avisos e 0 erros.
  • ReaderInterop.so na publicação linux-x64 totalizou 21.475.192 bytes.
  • Ambos os prompts de primeiro plano escreveram o plano e mudaram arquivos na mesma vez, e um agente fez o trabalho do prompt de dois agentes.
  • Capturas de tela do navegador e a pasta de publicação linux-x64 foram deixadas no repositório.

O registro de execução do hub lista a versão do Antigravity, modelo e tempo de execução, e a máquina que a execução usou.


Solução de problemas


Questões?

Se você tiver dúvidas, entre em contato com support@ironsoftware.com

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Pronto para começar?

Downloads no NuGet 82,442Versão:2026.11recém-lançado