Como Usar IronQR com Cursor

Curtis Chau
Curtis Chau
Atualizado: 9 de outubro de 2026

ZXing.Net é o port em código aberto para .NET da biblioteca de código de barras ZXing. Quando você pede a um agente de IA um código C# que lê códigos QR de fotos de clientes, pode aplicar convenções ZXing.Net mesmo que você especifique o IronQR, como comparar Result.Text, filtrar no formato QR_CODE ou encapsular QrImageInput em uma instrução using. No IronQR 2026.10.1, descartar a entrada dessa maneira lança uma NotImplementedException.

Cursor é um editor de código de IA baseado no código-fonte do VS Code. Se ele gera o código IronQR ou uma tradução do ZXing.Net depende de duas funcionalidades. O agente segue os links de documentação que você fornece, e aplica regras de projeto de .cursor/rules. Este guia demonstra ambos com um serviço de entrada de garantia que extrai números de série e links de registro de fotos de clientes, e move esse serviço de ZXing.Net para IronQR. IronQR suporta símbolos QR, Micro QR e rMQR.

Este guia foca em escrever código com o Cursor. Para detalhes sobre as opções de leitura do IronQR, consulte o guia de modos de varredura, o guia de tipos de QR e o guia de valor e coordenadas.

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 de entrada no Cursor e envie esta solicitação do painel do Agente.

@src/WarrantyIntake/ @TestData/claims/ Before writing code, fetch
https://ironsoftware.com/qr/csharp/llms.txt and the scan modes page it links.

Add the IronQR package to src/WarrantyIntake. Give Program.cs a second entry
point so that `dotnet run -- --modes <photo>` reads one photo three times, once
per QrScanMode value, and prints each result's QrType, Value, Url, and four
Points. Set License.LicenseKey from IRONQR_LICENSE_KEY at startup, never from
a literal. Leave Claims/StickerReader.cs and its ZXing.Net reference untouched.
Run the new mode on TestData/claims/claim-0004.jpg and show me what it printed.
Text

Mantenha a chave de licença fora das mensagens de chat. O agente cria arquivos e executa comandos no terminal, então uma chave colada pode acabar no código-fonte, commits ou logs. O guia de chave de licença lista os locais de armazenamento suportados.



Qual modelo do Cursor você deve usar para trabalho com código QR?

Composer é o modelo agêntico próprio do Cursor. O seletor de modelos também oferece os modelos Grok da SpaceXAI, que o Cursor co-desenvolveu, e modelos da OpenAI, Anthropic, Google e outros laboratórios. O teste executado abaixo usou o Grok 4.7.

Trabalho rotineiro com fotos, como adicionar um campo a um registro de reivindicação ou executar novamente a pasta de fotos, adequa-se a um modelo rápido. Quando um lote de fotos para de decodificar sem motivo claro, mude para um modelo que raciocina mais. Os modelos lêem solicitações de maneira diferente, então nomeie a pasta de fotos e os números de série que a saída deve corresponder em cada solicitação.

Como você fornece ao Cursor a documentação do IronQR?

Coloque o link da documentação do IronQR na solicitação, ou mantenha-o em uma regra comitada para que ninguém precise colá-lo. O índice llms.txt liga os guias e a referência de API, e llms-full.txt resume 44 páginas de documentação em um arquivo. Em outubro de 2026, o menu @ do Cursor anexa arquivos, pastas, terminais, chats, diffs de Git e o navegador, então a documentação do IronQR chega ao agente como um link.

Os enums do IronQR são fáceis de perder. QrScanMode e QrEncoding vivem em IronQr.Enum, enquanto QrErrorCorrectionLevel vive em IronQr, e o código escrito de memória falha em compilar quando se erra isso.

@src/WarrantyIntake/Program.cs Answer from https://ironsoftware.com/qr/csharp/llms.txt
and the pages it links, and leave every file as it is.

Which namespace declares QrScanMode and QrEncoding, and which declares
QrErrorCorrectionLevel? Which scan mode does a QrImageInput get when the
constructor is given only an image? What do IronQR's pages say OnlyDetectionModel
returns, and does that match the --modes output from the last turn? Put the
page URL under each answer.
Text
Dicas: Trate uma resposta sem uma página por trás como não verificada até encontrar o membro na referência de API.

Como você escreve regras de projeto que codificam suas convenções IronQR?

Regras de projeto são arquivos .mdc em .cursor/rules. Elas são comprometidas com o código, então cada clone obtém as mesmas regras. Um arquivo .md simples naquela pasta é ignorado, pois não tem frontmatter para dizer quando ele se aplica.

Esta regra define globs e deixa alwaysApply desativado, então se anexa sempre que o leitor ou seus testes estejam em contexto e fica fora de solicitações que nunca tocam em uma foto. Salve-o como .cursor/rules/ironqr-photos.mdc.

---
description: IronQR conventions for reading QR codes from customer photos
globs: src/WarrantyIntake/Claims/**/*.cs, tests/**/*.cs
alwaysApply: false
---

# Reading customer photos with IronQR

- Read and write QR codes with IronQR only. The NuGet package is IronQR, or
  IronQR.Linux for a Linux build, and the namespace is IronQr. Do not add
  ZXing.Net, QRCoder, or any other QR package, and remove them where they
  are already referenced.
- Documentation: https://ironsoftware.com/qr/csharp/llms.txt
- Never inline a license key. Read it from the IRONQR_LICENSE_KEY environment
  variable.
- Do not put QrImageInput in a using statement. Its IDisposable.Dispose throws
  NotImplementedException in IronQR 2026.10.1.
- Load only image files with AnyBitmap.FromFile. It throws on a CSV.
- Compare QrResult.Value with stored strings, never Url.ToString().
- Do not invent IronQR members. If one is uncertain, say so and cite the page.
Markdown
Por favor, note: Cursor também lê AGENTS.md na raiz do projeto e em subdiretórios. Não tem frontmatter, então não pode ser delimitado por padrão de arquivo. Mantenha a regra IronQR de escopo de padrão em .cursor/rules.

As regras se aplicam a solicitações de Agente. De acordo com a documentação do Cursor, elas não afetam o Tab, e regras de usuário não se aplicam a edições inline. Verifique sugestões desses recursos contra a regra você mesmo.

Como você mapeia chamadas do ZXing.Net para IronQR?

Uma regra que apenas diz "use IronQR" deixa o modelo adivinhar no que cada chamada do ZXing.Net se torna. Listar os equivalentes remove a adivinhação.

ZXing.Net ou QRCoderIronQR
BarcodeReader chamadas de decodificaçãoQrReader com Read, que retorna todos os códigos
Result.TextQrResult.Value
QR_CODE cheques e filtros de formatoUm cheque em QrResult.QrType após a leitura
A opção de varredura mais profundaUm modo de varredura na entrada
Result.ResultPoints, centros de padrãoQrResult.Points, os quatro cantos
Gerador do QRCoderQrWriter.Write e suas chamadas de salvamento

O enum BarcodeFormat do ZXing.Net não tem membro Micro QR ou rMQR, e seu README lista QR Code mas nenhum símbolo menor, então um leitor de ZXing.Net não retorna nada para um adesivo que carrega apenas um número de série Micro QR.

Adicione a tabela à regra como mais duas linhas.

- Translate ZXing.Net instead of porting it. Result.Text becomes QrResult.Value,
  BarcodeFormat checks become QrResult.QrType checks, and ResultPoints (finder
  pattern centres) become QrResult.Points (corners).
- Write test stickers with QrWriter.Write(...).Save().SaveAs(path), not QRCoder.
Markdown

Como você planeja e executa uma migração para IronQR?

Mude o chat para o Modo de Planejamento com Shift+Tab antes de enviar esta solicitação, e o Cursor rascunha o plano como um arquivo que você pode editar.

@src/WarrantyIntake/Claims/ @tests/WarrantyIntake.Tests/ @TestData/claims/expected.csv

StickerReader decodes claim photos with ZXing.Net and the tests draw stickers
with QRCoder. Newer products carry a Micro QR serial that ZXing.Net never
returns. Plan the move of both projects to IronQR. For each ZXing.Net or
QRCoder call, name the IronQR member that replaces it and the file it sits in,
state which QrScanMode the reader will use and why, and keep ClaimSticker and
the public Read(string) signature unchanged. No code until I approve.
Text

Corrija qualquer erro no plano, depois clique em Build, ou envie a próxima solicitação no Agente.

Build the approved plan and follow @ironqr-photos. Remove the ZXing.Net and
QRCoder package references, run dotnet build and dotnet test, then run the app
over TestData/claims and compare each printed row with
TestData/claims/expected.csv. Report how many rows matched before the change
and after it, and show the diff.
Text

Escolhido do menu @, @ironqr-photos anexa a regra por nome mesmo quando seus globos perderiam um arquivo. Uma construção limpa não mostra se os números de série Micro QR agora voltam. A contagem de correspondência sim.

Qual recurso do Cursor se adapta a cada mudança?

Escolha um de acordo com a abrangência da mudança. O Tab lida com uma edição previsível a seguir, e a edição inline lida com uma seleção que uma frase cobre. O Agente faz uma alteração que precisa de vários arquivos, a regra, ou um loop de construção. O Modo de Planejamento compensa quando desfazer uma mudança errada custa mais do que planejá-la, e um Agente em Nuvem é adequado para trabalho que ninguém precisa assistir.

Uma nova linha de produtos adiciona uma etiqueta de cabo retangular que carrega seu número de série em um código rMQR, que o IronQR relata como QrEncoding.RMQRCode. Selecione o loop de resultados no leitor e pressione Ctrl+Shift+L (Cmd+Shift+L no macOS) para adicionar a seleção ao chat, em seguida, envie esta solicitação no Agente.

In StickerReader.Read, treat a result whose QrType is QrEncoding.RMQRCode the
same way as a Micro QR result, so its Value becomes the serial.
Text

O leitor da migração já retornou SN-61518 para a foto da etiqueta, porque tratou qualquer valor que não seja um URL como um número de série. A edição substitui essa adivinhação por uma verificação no tipo de símbolo, então um valor Micro QR ou rMQR torna-se o número de série mesmo quando seu texto parece um URL.

Como você depura valores de código QR ausentes?

Cada modo de varredura altera o que volta.

  • Auto é o padrão. A referência da API do IronQR descreve-o como o modelo de aprendizado de máquina, com uma leitura de força bruta básica como reserva quando o modelo não encontra nada.
  • A leitura por força bruta roda sozinha sob OnlyBasicScan, com o modelo ignorado.
  • OnlyDetectionModel localiza códigos sem decodificá-los. O guia de modos de varredura lista sua saída como coordenadas.

Se o modelo reporta uma caixa que não pode decodificar, a reserva nunca executa e Auto não retorna valor. Fotos de caixa inteira atingem isso, com um adesivo de cerca de 110 pixels de largura em um quadro de 4000 por 3000. Verifique se a correção do agente tenta novamente com OnlyBasicScan quando nenhum valor retorna.

@src/WarrantyIntake/Claims/StickerReader.cs @TestData/claims/far/

Customers who photograph the whole box send pictures like these. Since the move
to IronQR none of them returns a serial, though the ZXing.Net reader read every
one. Before changing code, read each photo with all three QrScanMode values and
show what each mode returned. Then fix StickerReader without losing any photo
it reads today, and report the match count for TestData/claims and for
TestData/claims/far against their expected.csv files.
Text

Tome cada número de série da saída impressa do IronQR, e peça o comando que o produziu.

A ordem dos cantos também depende do modo. Quando o modelo localiza o código, os quatro pontos correm superior esquerdo, superior direito, inferior esquerdo, inferior direito, como afirma o guia de modos de varredura. OnlyBasicScan retorna os próprios cantos do código em sentido horário, rodados com o adesivo. Calcule contornos a partir das coordenadas em vez de assumir uma ordem.

Como você escreve testes de regressão para leitura de QR?

Testes que comparam valores decodificados com uma lista conhecida sobrevivem a atualizações de biblioteca, enquanto testes que comparam bytes de imagem podem falhar sempre que a renderização muda. Um Agente em Nuvem pode executar este prompt em uma VM de nuvem isolada. Adicione IRONQR_LICENSE_KEY como um segredo no painel de Agentes em Nuvem antes de iniciar um.

@tests/WarrantyIntake.Tests/ @TestData/claims/ Write xUnit tests for StickerReader
that prove every row in TestData/claims/expected.csv and
TestData/claims/far/expected.csv matches, that a Micro QR and an rMQR sticker
made with QrWriter read back to their serials, that a photo with no code gives a
null serial and no exception, and that a link sticker's serial comes from Value,
not Url.ToString(). Copy TestData into the test output. Run dotnet test and
report passed and failed counts.
Text

A última asserção é importante para um adesivo cujo valor total é um endereço simples. Ler a imagem de amostra do guia de modos de varredura do IronQR deu um Value de http://en.m.wikipedia.org e um Url que imprimiu com uma barra no final, porque Uri normaliza o endereço. Com links como os deste serviço, onde o número de série é o último segmento do caminho, a asserção não pode falhar.

O guia de assistentes de codificação de IA do IronQR executa uma tarefa IronQR do início ao fim contra critérios de aprovação definidos.

Qual pacote IronQR você deve implantar?

IronQR.Slim fornece o namespace IronQr e a varredura básica. O pacote completo IronQR adiciona o detector e o runtime ONNX. O guia de pacotes NuGet do IronQR diz que um projeto apenas Slim também precisa do pacote IronSoftware.ReaderInternals para seu sistema operacional.

@src/WarrantyIntake/WarrantyIntake.csproj @src/WarrantyIntake/Claims/StickerReader.cs

The service ships as a win-x64 folder, and someone asked whether IronQR.Slim
could replace IronQR. Settle it with numbers. Publish for win-x64 as things
stand and record the folder size. Then swap to IronQR.Slim plus the native
package its documentation says it needs, publish again, and rerun
TestData/claims and TestData/claims/far against their expected.csv files. Keep
the swap only if every row still matches, and list which QrScanMode values the
reader can still use afterward.
Text

Com IronQR.Slim sozinho, Auto não tem modelo e vai direto para a varredura básica, e OnlyDetectionModel lança uma IronQrException. A referência da API do IronQR adverte que leituras sem o modelo são mais lentas e de qualidade inferior. Teste com suas próprias fotos de clientes antes de trocar de pacote.

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

Os oito prompts foram enviados para o Cursor na ordem contra um repositório de entrada de garantia de exemplo. Ele contém um aplicativo de console com um leitor ZXing.Net, um projeto xUnit que desenha adesivos com QRCoder e doze fotos de reivindicação com números de série conhecidos. A regra, a foto da etiqueta de cabo e as fotos de caixa inteira foram adicionadas imediatamente antes dos prompts que as usam. A chave de licença foi definida apenas no ambiente. Após a execução, novas compilações de Release de cada commit da migração ao reler as pastas de fotos e reproduziram as contagens de correspondência do leitor IronQR e os resultados de teste abaixo.

  • Fotos de reivindicação corresponderam 8 de 12 com o leitor ZXing.Net e 12 de 12 após a mudança para o IronQR.
  • Lido uma vez por modo de varredura, claim-0004 deu dois códigos com valores sob Auto e OnlyBasicScan, e dois resultados com valores vazios sob OnlyDetectionModel.
  • A mudança do rMQR deixou as fotos de reivindicações em 13 de 13 antes e depois.
  • Antes da correção, Auto leu 0 de 4 fotos de caixa inteira. OnlyDetectionModel encontrou 3, 1, 3 e 2 caixas sem valor, enquanto OnlyBasicScan leu 4 de 4.
  • Após a correção, as fotos de caixa inteira leram 4 de 4 e as fotos de reivindicações 13 de 13.
  • O conjunto xUnit passou 22 de 22 testes.
  • A publicação para win-x64 produziu 75.624.980 bytes com IronQR e 19.510.306 com IronQR.Slim. Nossa reconstrução deu 75.624.288 e 19.509.614.
  • Em IronQR.Slim o leitor ainda correspondeu 13 de 13 fotos de reivindicação e 4 de 4 fotos de caixa inteira.
  • Cada build Release teve 0 erros e não precisou de edições manuais.
  • Nem todos os passos correram como escrito aqui. Os prompts foram enviados manualmente, menções foram coladas como texto, e o Agente encontrou o arquivo de regras buscando pelo seu nome. O plano foi aprovado enviando o próximo prompt com Build nunca clicado, e o prompt do Agente em Nuvem executado localmente no modo Agente.

O registro de execução contém as versões do pacote, modelo, tempo e máquina de teste para cada guia.


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