Comment utiliser IronQR avec Cursor

Curtis Chau
Curtis Chau
Mis à jour : 9 octobre 2026

ZXing.Net est le port open-source .NET de la bibliothèque de code-barres ZXing. Lorsque vous demandez à un agent d'IA un code C# qui lit des codes QR à partir de photos de clients, il peut appliquer les conventions ZXing.Net même si vous spécifiez IronQR, comme comparer Result.Text, filtrer sur le format QR_CODE, ou encapsuler le QrImageInput dans une déclaration using. Dans IronQR 2026.10.1, la suppression de l'entrée de cette manière génère une NotImplementedException.

Cursor est un éditeur de code AI basé sur le code de base de VS Code. Qu'il génère un code IronQR ou une traduction ZXing.Net dépend de deux fonctionnalités. L'agent suit les liens de documentation que vous fournissez et applique les règles du projet depuis .cursor/rules. Ce guide démontre les deux avec un service d'entrée de garantie qui extrait les numéros de série et les liens d'enregistrement à partir de photos de clients, et déplace ce service de ZXing.Net vers IronQR. IronQR supporte les symboles QR, Micro QR et rMQR.

Ce guide se concentre sur l'écriture de code avec Cursor. Pour plus de détails sur les options de lecture d'IronQR, reportez-vous au guide des modes de numérisation, au guide des types de QR, et au guide des valeurs et coordonnées.

Démarrage rapide
NuGetInstaller avec NuGet

PM > Install-Package IronQR

Installez IronQR en exécutant la commande ci-dessus dans la console du gestionnaire de packages NuGet, ou recherchez le package dans le gestionnaire de packages NuGet.

Ouvrez le projet d'entrée dans Cursor et envoyez cette requête depuis le panneau Agent.

@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

Gardez la clé de licence hors des messages de chat. L'agent crée des fichiers et exécute des commandes terminales, donc une clé collée peut se retrouver dans le code source, les commits ou les journaux. Le guide des clés de licence répertorie les emplacements de stockage pris en charge.



Quel modèle Cursor devriez-vous utiliser pour les travaux sur les codes QR ?

Composer est le propre modèle agentique de Cursor. Le sélecteur de modèle offre également les modèles Grok de SpaceXAI, que Cursor a co-développés, ainsi que des modèles d'OpenAI, Anthropic, Google et d'autres laboratoires. Le test réalisé ci-dessous a utilisé Grok 4.7.

Le travail de routine sur les photos, tel que l'ajout d'un champ à un enregistrement de réclamation ou le relancement du dossier photo, convient à un modèle rapide. Lorsqu'un lot de photos cesse de se décoder sans raison apparente, passez à un modèle qui raisonne plus longtemps. Les modèles lisent les requêtes différemment, alors nommez le dossier photo et les numéros de série que la sortie doit correspondre dans chaque requête.

Comment donner la documentation IronQR à Cursor ?

Mettez le lien de la documentation d'IronQR dans la requête ou conservez-le dans une règle engagée pour que personne n'ait à le coller. L'llms.txt index lie les guides et la référence API, et llms-full.txt résume 44 pages de documentation dans un fichier. En octobre 2026, le menu @ de Cursor attache des fichiers, dossiers, terminaux, chats, différences Git et le navigateur, donc la documentation IronQR atteint l'agent comme un lien.

Les énumérations d'IronQR sont faciles à égarer. QrScanMode et QrEncoding résident dans IronQr.Enum, tandis que QrErrorCorrectionLevel se trouve dans IronQr, et le code écrit de mémoire échoue à se compiler en cas d'erreur.

@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
Conseils: Traitez une réponse sans page derrière elle comme non vérifiée jusqu'à ce que vous trouviez le membre dans la référence API.

Comment écrire des règles de projet qui codent vos conventions IronQR ?

Les règles de projet sont des fichiers .mdc dans .cursor/rules. Ils sont validés avec le code, donc chaque clone obtient les mêmes règles. Un fichier .md simple dans ce dossier est ignoré, car il n'a pas de frontmatter pour indiquer quand il s'applique.

Cette règle définit globs et laisse alwaysApply désactivé, donc elle s'attache chaque fois que le lecteur ou ses tests sont en contexte et reste en dehors des requêtes qui ne touchent jamais une photo. Enregistrez-la comme .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
Veuillez noter: Cursor lit également AGENTS.md à la racine du projet et dans les sous-répertoires. Elle n'a pas de frontmatter, donc elle ne peut pas être appliquée en fonction du modèle de fichier. Conservez la règle IronQR à portée de motif dans .cursor/rules.

Les règles s'appliquent aux demandes Agent. Selon la documentation de Cursor, elles n'affectent pas Tab, et les règles utilisateur ne s'appliquent pas aux modifications en ligne. Vérifiez vous-même les suggestions de ces fonctionnalités par rapport à la règle.

Comment mapper les appels ZXing.Net à IronQR ?

Une règle qui ne dit que "utiliser IronQR" laisse le modèle deviner ce que chaque appel ZXing.Net devient. Lister les équivalents enlève la devinette.

ZXing.Net ou QRCoderIronQR
BarcodeReader appels de décodageQrReader avec Read, qui retourne chaque code
Result.TextQrResult.Value
QR_CODE vérifications et filtres de formatUn contrôle sur QrResult.QrType après la lecture
L'option de numérisation approfondieUn mode de numérisation sur l'entrée
Result.ResultPoints, centres de motifQrResult.Points, les quatre coins
Le générateur de QRCoderQrWriter.Write et ses appels de sauvegarde

L'énumération BarcodeFormat de ZXing.Net n'a pas de membre Micro QR ou rMQR, et son README liste le QR Code mais pas les symboles plus petits, donc un lecteur ZXing.Net ne retourne rien pour un autocollant qui ne contient qu'un numéro de série Micro QR.

Ajoutez le tableau à la règle comme deux lignes supplémentaires.

- 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

Comment planifier et exécuter une migration vers IronQR ?

Passez le chat en mode Plan en utilisant Shift+Tab avant d'envoyer cette requête, et Cursor rédige le plan en tant que fichier que vous pouvez modifier.

@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

Corrigez tout ce que le plan a mal compris, puis cliquez sur Build, ou envoyez la prochaine demande dans Agent.

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

Choisie depuis le menu @, @ironqr-photos attache la règle par nom même lorsque ses globes manqueraient un fichier. Une génération propre ne montre pas si les numéros de série Micro QR reviennent maintenant. Le nombre de correspondances le fait.

Quel élément de Cursor convient à chaque changement ?

Choisissez-en un selon la portée du changement. Tab gère une prochaine édition prévisible, et l'édition en ligne gère une sélection qu'une phrase couvre. Agent prend un changement qui nécessite plusieurs fichiers, la règle ou une boucle de construction. Le mode Plan se révèle payant lorsque défaire une mauvaise modification coûte plus cher que de la planifier, et un agent de Cloud convient au travail que personne n'a besoin de surveiller.

Une nouvelle ligne de produit ajoute une étiquette de câble rectangulaire qui porte son numéro de série dans un code rMQR, que IronQR signale comme QrEncoding.RMQRCode. Sélectionnez la boucle de résultats dans le lecteur et appuyez sur Ctrl+Shift+L (Cmd+Shift+L sur macOS) pour ajouter la sélection au chat, puis envoyez cette requête dans Agent.

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

Le lecteur de la migration a déjà renvoyé SN-61518 pour la photo de l'étiquette, car il considère toute valeur qui n'est pas une URL comme un numéro de série. L'édition remplace cette estimation par une vérification du type de symbole, de sorte qu'une valeur Micro QR ou rMQR devient le numéro de série même lorsque son texte ressemble à une URL.

Comment déboguer les valeurs manquantes de code QR ?

Chaque mode de numérisation change ce qui revient.

  • Auto est le mode par défaut. La référence API d'IronQR le décrit comme le modèle d'apprentissage automatique, avec une lecture brute-force de base comme recours lorsque le modèle ne trouve rien.
  • La lecture brute-force s'exécute seule sous OnlyBasicScan, avec le modèle sauté.
  • OnlyDetectionModel localise les codes sans les décoder. Le guide des modes de numérisation répertorie sa sortie comme coordonnées.

Si le modèle signale une boîte qu'il ne peut pas décoder, le recours ne se déclenche jamais et Auto ne retourne aucune valeur. Les photos de boîte entière rencontrent ce problème, avec une étiquette d'environ 110 pixels de large dans un cadre de 4000 par 3000. Vérifiez que la correction de l'agent réessaie avec OnlyBasicScan lorsque aucune valeur ne revient.

@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

Prenez chaque numéro de série de la sortie imprimée d'IronQR et demandez la commande qui l'a produit.

L'ordre des coins dépend aussi du mode. Lorsque le modèle localise le code, les quatre points sont en haut à gauche, en haut à droite, en bas à gauche, en bas à droite, comme indiqué dans le guide des modes de numérisation. OnlyBasicScan retourne les coins propres du code dans le sens horaire, tournés avec l'autocollant. Calculez les contours à partir des coordonnées plutôt que de supposer un ordre.

Comment écrire des tests de régression pour la lecture de QR ?

Les tests qui comparent les valeurs décodées avec une liste connue survivent aux mises à niveau de la bibliothèque, tandis que les tests qui comparent les octets d'image peuvent échouer à chaque modification du rendu. Un agent de cloud peut exécuter cette invite dans une VM cloud isolée. Ajoutez IRONQR_LICENSE_KEY comme un secret dans le tableau de bord de Cloud Agents avant d'en démarrer un.

@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 dernière assertion est importante pour un autocollant dont la valeur complète est une adresse directe. La lecture de l'image d'échantillon du guide des modes de numérisation d'IronQR a donné un Value de http://en.m.wikipedia.org et un Url qui s'est imprimé avec une barre oblique finale, car Uri normalise l'adresse. Avec des liens comme ceux de ce service, où le numéro de série est le dernier segment du chemin, l'assertion ne peut pas échouer.

Le guide des assistants de codage IA d'IronQR effectue une tâche IronQR de bout en bout selon des critères de réussite définis.

Quel paquet IronQR devriez-vous déployer ?

IronQR.Slim fournit l'espace de noms IronQr et la numérisation de base. Le package complet IronQR ajoute le détecteur et l'exécution ONNX. Le guide des packages NuGet d'IronQR indique qu'un projet Slim uniquement a également besoin du package IronSoftware.ReaderInternals pour son système d'exploitation.

@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

Avec IronQR.Slim seul, Auto n'a pas de modèle et passe directement à la numérisation de base, et OnlyDetectionModel génère une IronQrException. La référence API d'IronQR avertit que les lectures sans le modèle sont plus lentes et de moindre qualité. Testez avec vos propres photos de clients avant de changer de package.

Qu'est-ce que les messages ont produit lors d'une réelle exécution ?

Les huit invites ont été envoyées à Cursor dans l'ordre contre un dépôt d'entrée de garantie d'échantillon. Il contient une application console avec un lecteur ZXing.Net, un projet xUnit qui dessine des autocollants avec QRCoder, et douze photos de réclamation avec des numéros de série connus. La règle, la photo de l'étiquette de câble et les photos de boîte entière ont été ajoutées juste avant les invocations qui les utilisent. La clé de licence a été définie uniquement dans l'environnement. Après l'exécution, les nouvelles constructions Release de chaque commit de la migration ont relancé les dossiers photo et reproduit les comptes de correspondance du lecteur IronQR et les résultats des tests ci-dessous.

  • Les photos de réclamation correspondaient 8 sur 12 avec le lecteur ZXing.Net et 12 sur 12 après le passage à IronQR.
  • Lues une fois par mode de numérisation, claim-0004 a donné deux codes avec des valeurs sous Auto et OnlyBasicScan, et deux résultats avec des valeurs vides sous OnlyDetectionModel.
  • Le changement rMQR a laissé les photos de réclamation à 13 sur 13 avant et après.
  • Avant la correction, Auto lisait 0 sur 4 photos de boîte entière. OnlyDetectionModel a trouvé 3, 1, 3 et 2 boîtes sans valeur, tandis que OnlyBasicScan a lu 4 sur 4.
  • Après la correction, les photos de boîte entière ont lu 4 sur 4 et les photos de réclamation 13 sur 13.
  • La suite xUnit a passé 22 tests sur 22.
  • La publication pour win-x64 a produit 75 624 980 octets avec IronQR et 19 510 306 avec IronQR.Slim. Notre reconstruction a donné 75 624 288 et 19 509 614.
  • Sur IronQR.Slim, le lecteur a toujours correspondu à 13 sur 13 photos de réclamation et 4 sur 4 photos de boîte entière.
  • Chaque construction Release comportait 0 erreurs et n'avait besoin d'aucune modification manuelle.
  • Chaque étape n'a pas été exécutée telle qu'écrite ici. Les invites ont été envoyées à la main, les mentions ont été collées en tant que texte, et Agent a trouvé le fichier de règle en recherchant son nom. Le plan a été approuvé en envoyant l'invite suivante sans jamais cliquer sur Build, et l'invite de l'agent de cloud a été exécutée localement en mode Agent.

Le dossier d'exécution contient les versions des packages, le modèle, le timing et la machine de test pour chaque guide.


Dépannage


Des questions ?

Si vous avez des questions, contactez support@ironsoftware.com

Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes et créer des manuels bien structurés et visuellement attrayants.

Lire la suite

Prêt à commencer ?

Téléchargements NuGet 82,442Version :2026.11tout juste publié