Cómo usar IronQR con Cursor

Curtis Chau
Curtis Chau
Actualizado: 9 de octubre de 2026

ZXing.Net es el puerto .NET de código abierto de la biblioteca de códigos de barras ZXing. Cuando pides a un agente de IA código C# que lea códigos QR de fotos de clientes, puede aplicar convenciones de ZXing.Net incluso si especificas IronQR, como comparar Result.Text, filtrar en el formato QR_CODE, o envolver el QrImageInput en una declaración using. En IronQR 2026.10.1, deshacer del input de esa manera lanza una NotImplementedException.

Cursor es un editor de código de IA basado en la base de código de VS Code. Ya sea que genere código IronQR o una traducción de ZXing.Net, depende de dos características. El agente sigue los enlaces de documentación que proporcionas y aplica reglas de proyecto de .cursor/rules. Esta guía demuestra ambos con un servicio de entrada de garantía que extrae números de serie y enlaces de registro de fotos de clientes, y mueve ese servicio de ZXing.Net a IronQR. IronQR admite símbolos QR, Micro QR y rMQR.

Esta guía se centra en escribir código con Cursor. Para obtener detalles sobre las opciones de lectura de IronQR, consulta la guía de modos de escaneo, la guía de tipos de QR y la guía de valores y coordenadas.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronQR

Instale IronQR ejecutando el comando arriba en la Consola del Administrador de Paquetes NuGet, o busque el paquete en el Administrador de Paquetes NuGet.

Abre el proyecto de entrada en Cursor y envía esta solicitud desde el panel del 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

Mantén la clave de licencia fuera de los mensajes de chat. El agente crea archivos y ejecuta comandos en el terminal, por lo que una clave pegada puede terminar en el código fuente, confirmaciones o registros. La guía de claves de licencia enumera las ubicaciones de almacenamiento admitidas.



¿Qué modelo de Cursor deberías usar para trabajar con códigos QR?

Composer es el modelo agente propio de Cursor. El selector de modelos también ofrece los modelos Grok de SpaceXAI, que Cursor co-desarrolló, y modelos de OpenAI, Anthropic, Google y otros laboratorios. La prueba a continuación utilizó Grok 4.7.

El trabajo rutinario con fotos, como agregar un campo a un registro de reclamación o volver a ejecutar la carpeta de fotos, se adapta a un modelo rápido. Cuando un lote de fotos deja de decodificar sin razón clara, cambia a un modelo que reflexione más. Los modelos leen solicitudes de manera diferente, así que nombra la carpeta de fotos y los seriales que la salida debería coincidir en cada solicitud.

¿Cómo le das a Cursor la documentación de IronQR?

Coloca el enlace de documentación de IronQR en la solicitud, o guárdalo en una regla confirmada para que nadie tenga que pegarlo. El índice llms.txt enlaza las guías y la referencia de API, y llms-full.txt resume 44 páginas de documentación en un archivo. A partir de octubre de 2026, el menú @ de Cursor adjunta archivos, carpetas, terminales, chats, diferencias de Git y el navegador, así que la documentación de IronQR llega al agente como un enlace.

Los enums de IronQR son fáciles de extraviar. QrScanMode y QrEncoding residen en IronQr.Enum, mientras QrErrorCorrectionLevel reside en IronQr, y el código escrito de memoria falla al construir cuando se equivoca en esto.

@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
Consejos: Trate una respuesta sin una página detrás como no verificada hasta que encuentre el miembro en la referencia de la API.

¿Cómo escribes reglas de proyecto que codifiquen tus convenciones de IronQR?

Las reglas de proyecto son archivos .mdc en .cursor/rules. Son comprometidas con el código, por lo que cada clon recibe las mismas reglas. Un archivo plano .md en esa carpeta es ignorado, porque no tiene frontmatter para indicar cuándo se aplica.

Esta regla establece globs y deja alwaysApply desactivado, así que se adjunta siempre que el lector o sus pruebas estén en contexto y se mantiene fuera de las solicitudes que nunca tocan una foto. Guárdalo 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, tenga en cuenta: Cursor también lee AGENTS.md en la raíz del proyecto y en los subdirectorios. No tiene frontmatter, por lo que no puede ser limitado por patrón de archivo. Mantén la regla IronQR con ámbito de patrón en .cursor/rules.

Las reglas se aplican a las solicitudes de Agent. Según la documentación de Cursor, no afectan a Tab, y las reglas de usuario no se aplican a las ediciones en línea. Verifique usted mismo las sugerencias de esas características contra la regla.

¿Cómo mapear llamadas de ZXing.Net a IronQR?

Una regla que solo dice "usa IronQR" deja que el modelo adivine en qué se convierte cada llamada de ZXing.Net. Enumerar los equivalentes elimina las conjeturas.

ZXing.Net o QRCoderIronQR
BarcodeReader llamadas de decodificaciónQrReader con Read, que devuelve cada código
Result.TextQrResult.Value
QR_CODE verificaciones de formato y filtrosUna verificación en QrResult.QrType después de la lectura
La opción de escaneo más profundoUn modo de escaneo en la entrada
Result.ResultPoints, centros de patrónQrResult.Points, las cuatro esquinas
El generador de QRCoderQrWriter.Write y sus llamadas de guardado

El enum BarcodeFormat de ZXing.Net no tiene miembro Micro QR ni rMQR, y su README enumera el Código QR pero ninguno de los símbolos más pequeños, por lo que un lector ZXing.Net no devuelve nada para una pegatina que solo lleva un serial Micro QR.

Agrega la tabla a la regla como dos líneas más.

- 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

¿Cómo planificar y ejecutar una migración a IronQR?

Cambia el chat a Modo Plan con Shift+Tab antes de enviar esta solicitud, y Cursor redacta el plan como un archivo que puedes 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

Corrige cualquier cosa que el plan haya entendido mal, luego haz clic en Construir o envía la siguiente solicitud en 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

Elegida desde el menú @, @ironqr-photos adjunta la regla por nombre incluso cuando sus globs perderían un archivo. Una construcción limpia no muestra si ahora los seriales Micro QR regresan. El recuento de coincidencias sí lo hace.

¿Qué característica de Cursor encaja con cada cambio?

Elija una según qué tan lejos llegue el cambio. Tab maneja una edición siguiente predecible, y la edición en línea maneja una selección que una frase cubre. El agente toma un cambio que necesita varios archivos, la regla o un bucle de construcción. El Modo Plan rinde beneficios cuando deshacer un cambio incorrecto cuesta más que planificarlo, y un Agente en la Nube es adecuado para trabajos que nadie necesita vigilar.

Una nueva línea de productos añade una etiqueta de cable rectangular que lleva su serial en un código rMQR, que IronQR informa como QrEncoding.RMQRCode. Selecciona el bucle de resultados en el lector y presiona Ctrl+Shift+L (Cmd+Shift+L en macOS) para agregar la selección al chat, luego envía esta solicitud en 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

El lector de la migración ya devolvió SN-61518 para la foto de la etiqueta, porque trató cualquier valor que no sea una URL como un serial. La edición reemplaza esa conjetura con una verificación en el tipo de símbolo, por lo que un valor Micro QR o rMQR se convierte en el serial incluso cuando su texto parece una URL.

¿Cómo depurar valores faltantes de códigos QR?

Cada modo de escaneo cambia lo que regresa.

  • Auto es el predeterminado. La referencia de API de IronQR lo describe como el modelo de aprendizaje automático, con una lectura básica de fuerza bruta como respaldo cuando el modelo no encuentra nada.
  • La lectura de fuerza bruta se ejecuta sola bajo OnlyBasicScan, omitiendo el modelo.
  • OnlyDetectionModel localiza códigos sin decodificarlos. La guía de modos de escaneo enumera su salida como coordenadas.

Si el modelo informa una caja que no puede decodificar, el respaldo nunca se ejecuta y Auto no devuelve valor. Las fotos de caja entera golpean esto, con una pegatina de aproximadamente 110 píxeles de ancho en un marco de 4000 por 3000. Verifica que la corrección del agente reintenta con OnlyBasicScan cuando no llega ningún valor.

@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

Toma cada serial de la salida impresa de IronQR, y pide el comando que lo produjo.

El orden de las esquinas también depende del modo. Cuando el modelo localiza el código, los cuatro puntos se recorren de arriba a la izquierda, arriba a la derecha, abajo a la izquierda, abajo a la derecha, como indica la guía de modos de escaneo. OnlyBasicScan devuelve las esquinas del código en sentido horario, rotadas con la pegatina. Calcula contornos a partir de las coordenadas en lugar de asumir un orden.

¿Cómo escribir pruebas de regresión para la lectura de QR?

Las pruebas que comparan valores decodificados con una lista conocida sobreviven a las actualizaciones de la biblioteca, mientras que las pruebas que comparan bytes de imágenes pueden fallar cada vez que cambian los renderizados. Un agente en la nube puede ejecutar este aviso en una VM aislada en la nube. Agrega IRONQR_LICENSE_KEY como un secreto en el tablero de los agentes en la nube antes de iniciar uno.

@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

La última afirmación es importante para una pegatina cuyo valor completo es una dirección desnuda. Leer la imagen de muestra de la guía de modos de escaneo de IronQR dio un Value de http://en.m.wikipedia.org y un Url que se imprimió con una barra inclinada, porque Uri normaliza la dirección. Con enlaces como los de este servicio, donde el serial es el último segmento del camino, la afirmación no puede fallar.

La guía de asistentes de codificación de IA de IronQR ejecuta una tarea de IronQR de principio a fin contra criterios de paso definidos.

¿Qué paquete de IronQR deberías implementar?

IronQR.Slim proporciona el espacio de nombres IronQr y el escaneo básico. El paquete completo IronQR agrega el detector y el tiempo de ejecución ONNX. La guía de paquetes NuGet de IronQR dice que un proyecto solo Slim también necesita el paquete IronSoftware.ReaderInternals para su sistema operativo.

@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

Con IronQR.Slim solo, Auto no tiene modelo y va directamente al escaneo básico, y OnlyDetectionModel lanza una IronQrException. La referencia de API de IronQR advierte que las lecturas sin el modelo son más lentas y de menor calidad. Prueba con tus propias fotos de clientes antes de cambiar de paquetes.

¿Qué produjeron los prompts en una ejecución real?

Los ocho avisos fueron a Cursor en orden contra un repositorio de entrada de garantía de muestra. Contiene una aplicación de consola con un lector ZXing.Net, un proyecto xUnit que dibuja pegatinas con QRCoder y doce fotos de reclamaciones con seriales conocidos. La regla, la foto de la etiqueta de cable y las fotos de caja entera fueron añadidas inmediatamente antes de los avisos que las usan. La clave de licencia se estableció solo en el entorno. Después de la ejecución, nuevas construcciones Release de cada confirmación de la migración al releer las carpetas de fotos reprodujeron los conteos de coincidencia del lector IronQR y los resultados de las pruebas a continuación.

  • Las fotos de reclamaciones coincidieron 8 de 12 con el lector ZXing.Net y 12 de 12 después del cambio a IronQR.
  • Leído una vez por modo de escaneo, claim-0004 dio dos códigos con valores bajo Auto y OnlyBasicScan, y dos resultados con valores vacíos bajo OnlyDetectionModel.
  • El cambio rMQR dejó las fotos de reclamaciones en 13 de 13 antes y después.
  • Antes de la corrección, Auto leyó 0 de 4 fotos de caja entera. OnlyDetectionModel encontró 3, 1, 3 y 2 cajas sin valor, mientras que OnlyBasicScan leyó 4 de 4.
  • Después de la corrección, las fotos de caja entera leyeron 4 de 4 y las fotos de reclamaciones 13 de 13.
  • La suite de xUnit pasó 22 de 22 pruebas.
  • La publicación para win-x64 produjo 75,624,980 bytes con IronQR y 19,510,306 con IronQR.Slim. Nuestra reconstrucción dio 75,624,288 y 19,509,614.
  • En IronQR.Slim el lector aún coincidía con 13 de 13 fotos de reclamaciones y 4 de 4 fotos de caja entera.
  • Cada compilación de Release tuvo 0 errores y no necesitó ediciones a mano.
  • No todos los pasos se ejecutaron tal como están escritos aquí. Los avisos fueron enviados a mano, las menciones fueron pegadas como texto, y el agente encontró el archivo de regla buscando su nombre. El plan fue aprobado enviando el siguiente aviso sin hacer clic en Construir, y el aviso del agente en la nube se ejecutó localmente en el modo del agente.

El registro de ejecuciones contiene las versiones de los paquetes, el modelo, el tiempo y la máquina de prueba para cada guía.


Solución de problemas


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

Leer más

¿Listo para empezar?

Descargas de NuGet 82,442Versión:2026.11recién lanzado