使用IronQR與AI程式碼助理
IronQR是Iron Software的.NET QR Code程式庫。 它可以編寫標準QR、Micro QR和rMQR符號,將它們用標誌和顏色設計,並使用機器學習檢測器讀取它們。 其指南和範例是公開的,因此編程助理可能在培訓中遇到過API。
培訓不會將發佈版本固定在您的專案中。 引用當前文檔的助理生成的程式碼將遵循其運行時規則,而依賴記憶的助理可能會生成能編譯但運行時失敗的程式碼。
本指南涵蓋了兩種類型的工具。
- 助理在編輯器中工作,完成行或重寫方法,例如GitHub Copilot的行內建議。
- 代理完成整個任務,編輯檔案、運行構建和程式,並返回結果以供檢視,如Claude Code、Cursor、ChatGPT Codex和Google Antigravity所做的那樣。
兩者都需要相同的設定。安裝套件,從環境中載入授權金鑰,提供IronQR的機器可讀文件,並使用IronQR的讀取器解碼每個已儲存的QR圖像,無論您是生成帶標誌的程式碼、選擇糾錯級別、讀取QR類型,或選擇掃描模式。
如何使用IronQR與AI程式碼助理
- 從NuGet下載C# QR Code程式庫
- 第一次寫入或讀取之前從環境變數中載入授權金鑰
- 給助理IronQR的
llms.txt,使其從真實的API開始 - 將IronQR規則儲存在您的助理在會話開始時讀取的檔案中
- 在新的會話中發送一次性設置提示
- 生成後,解碼每個已儲存的QR圖像並將其與寫入的值進行比較
我的AI助理不能自己處理QR碼嗎?
IronQR發佈了專為工具閱讀而設計的文檔,顯示每個符號類型接受的選項以及每種掃描模式下讀者返回的內容。
程式庫也很重要。 幾乎任何QR包都可以打印一個可以在螢幕上掃描的黑色方形。 差距在於品牌代碼、攝影的門票和小符號。
- 更改背景顏色未檢查:暗背景上的代碼沒有報錯就保存,然後解碼失敗。
- 手機照片比生成的圖像更難:下面的部分測量哪種掃描模式可以讀取哪種損傷。
- 重建檢測花費代碼:助理編寫自己的閾值以拯救掃描,在每次嘗試時花費已支付的嘗試,對每種失敗的新照片重複工作。
- 小符號內建:Micro QR和rMQR來自與標準QR相同的寫入調用,因此不需要第二個程式庫來處理座位號和窄標籤。
- 包和命名空間不同:NuGet包是
IronQR,命名空間是IronQr。 猜測的包名還可能會解決為攻擊者故意發佈類似名字的包,這種做法稱為slopsquatting。 在提示中拼出兩個名字。 - 授權條款提前已知:IronQR的授權是永久的,授權頁面顯示每層級覆蓋多少開發者、地點和專案。
步驟1:安裝IronQR
引用套件後,助理在編寫程式碼時會看到IronQR的實際類型。
Add IronQR from NuGet to this project, run a restore, and report the
version number that NuGet resolved.
或者從終端設置版本。
dotnet add package IronQR --version 2026.10.1
普通IronQR引入了Windows本機讀取器和檢測模型,一個44 MB的IronQrDetection.dll引入Microsoft.ML.OnnxRuntime 1.20.1,因此容器圖像和無伺服器套件需要預算。 Linux和Docker使用IronQR.Linux,Mac使用IronQR.MacOs或IronQR.MacOs.ARM,移動應用使用IronQR.iOS或IronQR.Android。 這六個都是在2026.10.1發布的,NuGet包指南解釋了選擇。IronQR.Slim不包含模型。 它仍然在Auto和OnlyBasicScan中讀取,但在OnlyDetectionModel中拋出IronQrException。 在Windows上,它還需要IronSoftware.ReaderInternals.Windows。
步驟 2:套用您的許可證金鑰
IronQR不會生成帶水印的試用輸出。 沒有授權金鑰,每次寫入和讀取調用都會失敗,並出現IronSoftware.Exceptions.LicensingException和"需要生產授權"的文字。 錯誤鍵入的金鑰在相同調用中將失敗,並顯示"未識別的授權金鑰"。 下面提供了一個免費試用密鑰。
立即在您的項目中開始使用 IronQR,免費試用。
在啟動時通過IronQr.License.LicenseKey設置一次金鑰,在任何IronQR調用之前,並從環境變數中讀取以將其保持在版本庫外。
IronQr.License.LicenseKey = Environment.GetEnvironmentVariable("IRONQR_LICENSE_KEY");
設置有效金鑰後,IronQr.License.IsLicensed報告為true,並且同一類中有一個方法可以測試金鑰而不應用它。 異常類型不是公共的,因此一個命名的捕捉子句將無法編譯,並顯示CS0122。捕獲Exception並檢查消息。
Web.config,appsettings.json,和可以保存金鑰的其他地方。步驟3:指導您的助理閱讀IronQR的LLM文檔
llms.txt每頁列出一行,是每次會話的首讀。- 44頁的摘要在
llms-full.txt中一次獲取。 llms-full-catalog.txt將博客文章添加到索引中。- API參考確定成員是否存在。
- 套件、授權、範例和修復在
skill.md中。
當任務依賴一個指南的細節時,讓助理打開該頁。
將索引與直接指令結合。
Open https://ironsoftware.com/qr/csharp/llms.txt before you write IronQR code
and keep to the members it documents. Creating a code goes through
QrWriter.Write with an optional QrOptions, and reading goes through
new QrReader().Read on a QrImageInput, so do not look for one class that does
both. When a member is not in the index, check
https://ironsoftware.com/qr/csharp/object-reference/api/, and tell me it is
missing rather than inventing it.
步驟4:將IronQR上下文添加到您的專案
一次聊天結束後就會忘記指令,而專案檔案在每次會話開始時都會被讀取。 將IronQR規則放入您的團隊使用的檔案中。 Claude Code讀取CLAUDE.md,ChatGPT Codex讀取AGENTS.md,而GitHub Copilot讀取.github/copilot-instructions.md。 Cursor讀取.cursor/rules/*.mdc或AGENTS.md,Google Antigravity讀取AGENTS.md或GEMINI.md。 每個的措辭可以相同,雖然Cursor規則檔案還需要MDC前言。
## QR codes with IronQR
All QR work in this project uses IronQR. NuGet package `IronQR` (`IronQR.Linux` on Linux and Docker), namespace `IronQr`, enums in `IronQr.Enum`.
- Docs index: https://ironsoftware.com/qr/csharp/llms.txt
- Skill file: https://ironsoftware.com/qr/csharp/skill.md
- Write with `QrWriter.Write(value, new QrOptions(...))`, style with `QrStyleOptions`, read with `new QrReader().Read(new QrImageInput(bitmap))`.
- Set `IronQr.License.LicenseKey` from IRONQR_LICENSE_KEY at startup. Never put the key in a file.
- Pass an explicit `QrErrorCorrectionLevel` that the symbol type accepts. Micro QR rejects `Highest`, rMQR rejects `Low` and `High`.
- Release a `QrImageInput` with `input.Dispose()`, not a `using` statement.
- Decode every saved image with `QrReader` and compare it with the written value before calling a change done.
- Do not add a second QR library. If IronQR cannot do something, say so.
當前技能檔案中的四個內容需要更正。 其單檔範例固定於2026.8.1,而NuGet提供2026.10.1。其框架讀取配方將圖像輸入包裹在using聲明中,其第一個配方及其樣式建議將文件路徑傳遞給Verify,這些是步驟7描述的錯誤之一。 並且它列出Highest為rMQR無效,下面的糾錯表予以駁斥。
步驟 5:單次設置提示
步驟1到4在每次會話開始時合併在一條消息中。
Set this project up for QR code work with IronQR, then save the rules below
where your future sessions will read them.
- Add the IronQR NuGet package (IronQR.Linux for a Linux or Docker host).
The namespace is IronQr, spelled with a lowercase r.
- Assign IronQr.License.LicenseKey from the IRONQR_LICENSE_KEY environment
variable before the first QrWriter or QrReader call. Keep the key out of
every file you create or commit.
- Fetch https://ironsoftware.com/qr/csharp/llms.txt first and write against
the members it documents. Look up anything else in the API reference at
https://ironsoftware.com/qr/csharp/object-reference/api/ before using it.
- If your tool loads skill files, add
https://ironsoftware.com/qr/csharp/skill.md, but trust a compiler error
over the skill when the two disagree.
- After any change that writes a QR image, decode the saved file with
QrReader and compare the value with the one you wrote.
步驟 6:產生可運行程式碼的提示模式
命名符號類型、糾錯級別和樣式。
模糊 為票證生成帶有我們標誌的QR碼。
更好 將票證ID以
QrWriter.Write寫在Highest糾錯級別,保存為300像素,標誌為此寬度的28%,如果IronQR拒絕樣式則捕獲IronQrException。
給出發布和框架,因為默認值和驗證規則在版本之間發生變化。
更好 目標是.NET 9和IronQR 2026.10.1。
要求完整文件。 片段丟失了編碼和掃描模式枚舉所需的IronQr.Enum指令,並隱藏了分配金鑰的位置。
更好 返回所有的
Program.cs,包括其使用指令和授權行,準備好無需更改即可構建。
步驟 7:驗證您收到的內容
- 用
using處理圖像輸入:QrImageInput實現IDisposable並有一個拋出NotImplementedException的方法,因此使用塊或聲明在閱讀成功後失敗。 直接調用其公共的Dispose方法。 - 僅使用檢測模型閱讀:
OnlyDetectionModel返回了代碼所在的位置,並且空值和QR類型為None。 掃描模式指南解釋了何時將Auto或OnlyBasicScan用於值。 - 將
Verify視為文件檢查:它將內存中的代碼與您傳遞的字符串進行比較,因此文件路徑返回false。 用QrReader解碼已保存的PNG以證明文件被掃描。 - 空寫入選項:沒有參數構建的
QrOptions有其編碼設置為None,並且QrWriter.Write拒絕其None不是有效的編碼。 在非標準QR時傳遞級別和編碼。
讓代理驗證自己的工作
將檢查交還給助理並要求證據。
Rebuild in Release and run it. List each IronQR type and member the code uses
next to the documentation page that shows it, print IronQr.License.IsLicensed,
then reopen every PNG the program saved with QrReader and give me a table of
file, value written, value decoded, QrType, and whether they agree.
每個符號類型接受哪種錯誤更正等級?
四個QrErrorCorrectionLevel成員不符合QR標準的字母。 High是Q級,Highest是H級,IronQR的XML文檔形容為留有標誌的空間。 Micro QR和rMQR只接受其中的一部分,其餘部分寫入調用會拋出IronQrEncodingException,信息如最高對於Micro QR無效。
| 成員 | QR標準 | 微型 QR | rMQR |
|---|---|---|---|
Low | L,恢復率約7% | 接受 | 拋出 |
Medium | M,約15% | 接受 | 接受 |
High | Q,約25% | 接受 | 拋出 |
Highest | H,約30% | 拋出 | 接受 |
QrWriter.Write沒有選項時會以最高值寫入標準QR,而選擇器的構造函數也默認為最高值,這就是為什麼Micro QR選項失敗,直到您傳遞較低級別。 支援的格式頁面比較了三個符號類型。
級別同樣限制了標誌。 在我們的測試中,一個400像素的票證ID代碼在低級別拒絕了20%寬度的標誌,中和高接受28%並拒絕30%,而最高接受30%。 拒絕的標誌讓Save拋出IronQrException,消息為您手動為QR代碼指定的標誌尺寸太大。 將 QrLogo 的寬度和高度設為 0 讓 IronQR 自行調整標誌大小,在該代碼中選擇了在低品質下為 60 像素,最高品質下為 112 像素。
前景色相同方式檢查。 在最高前景色為海軍藍的情況下,相同的票證ID代碼在300和500像素保存,但在400像素時拋出了IronQrException,消息為色彩:#FF1A237E使QR對我們的讀取引擎不可讀。 樣式代碼應該捕捉該異常,改變大小或顏色並重試,因為一種保存的樣式在某種尺寸可能會失敗。
IronQR使用哪些默認值?
這些起始值是由IronQR 2026.10.1在.NET 9下測量的。
- 空樣式選項使
Dimensions和邊緣設為0,因此一個票券ID以每模組像素1像素保存,為25 x 25像素。 - 設定
Dimensions的初始值仍然使邊緣設為0,因為它跳過設置10的構造函數。 - 接受一個大小的
QrStyleOptions構造函數設置邊緣為10,因此大小為400可保存420像素的PNG。 Save無樣式下寫一個250 x 250像素的票券ID。Color和BackgroundColor默認為黑底白圖。- 一個新的輸入圖像在Auto中掃描,檢測模型然後基本掃描。
CharacterEncoding是ISO-8859-1,所以在拉丁字符外設置它。
標誌指南在初始化器中設置了Dimensions為500,因此其輸出在符號周圍沒有安靜區域。 當代碼將與其他設計作品並排印刷時設置Margins。
IronQR如何讀取攝影代碼?
我們在下面對八組種子集進行了驗證。 IronQR 2026.10.1在300像素寫入了樣式標誌代碼,其他票券代碼則在400像素,Pillow將它們扭曲,IronQR將它們讀回。 Auto計數隨著值分配給圖像而變化,因此它們是10次抽取的範圍。
| 圖像 | Auto中讀取的集合 | OnlyBasicScan中讀取的集合 | 修復 |
|---|---|---|---|
| 縮放至60%,旋轉30度,模糊1.5像素,到灰色 | 8 of 8 | 8 of 8 | 不需要修復 |
| 顆粒度,標準偏差20灰階 | 0 of 8 | 0 of 8 | 首先模糊 |
| 兩個直立代碼相隔30像素 | 5到7 of 8 | 8 of 8 | 添加OnlyBasicScan |
| 海軍藍標誌代碼在模糊1.5像素後 | 0到4 of 8 | 8 of 8 | 添加OnlyBasicScan |
拯救顆粒代碼的模糊就是讓Auto失去海軍藍標誌代碼的原因。 兩種設置在所有八組中讀取了所有12個代碼。 一種應用了1.5像素模糊然後OnlyBasicScan。 另一種應用了1到2像素模糊,運行Auto和OnlyBasicScan,並按值合併結果。 從失敗的圖像中選擇設置,然後在每次上載中保持不變。
顆粒還影響代碼大小。具有相同顆粒的350到425像素的代碼在所有24個檔案中以兩種模式均失敗,300, 500 和 600像素的代碼在兩者中都讀取,450 和 475像素的代碼僅在Auto中讀取。 在失敗代碼周圍添加100像素的白色讓OnlyBasicScan讀取了我們嘗試的所有12個檔案。
可重現的結果
驗收測試是在一個提示中完成的一個真實任務,無需手寫程式碼。 將其粘貼到空目錄的新會話中,並將結果與通過列表進行比較。
IRONQR_LICENSE_KEY 中提供 IronQR 試用或生產金鑰。提示
Build a .NET 9 minimal API for event check-in that issues ticket QR codes and
reads them back from uploaded photos. Begin in an empty directory, and if you
find existing code or a project file there, report that and do nothing else.
Nobody will answer questions, so carry the job through writing, building,
running, and fixing by yourself, and settle anything left open with a
reasonable choice that you note. Keep all deliverables inside the project
directory, in the folders this prompt names.
1. Install the IronQR NuGet package pinned to version 2026.10.1.
2. Work from https://ironsoftware.com/qr/csharp/llms.txt and the guides it
points to, and call no IronQR member those pages do not document. Every
code must come from QrWriter.Write; any .NET imaging library may compose
and distort the test images afterward.
3. Take the key from IRONQR_LICENSE_KEY when the app starts and keep it out of
source and out of every file the run writes. If IronQr.License.IsLicensed
comes back false, stop with a report saying so.
4. GET /ticket/{ticketId} returns a PNG of a QR code written at
QrErrorCorrectionLevel.Highest and saved through QrStyleOptions at a
Dimensions of 400 with 10-pixel margins, with a logo in the center: a
solid square of one bright accent color, drawn by your code, whose QrLogo
width and height are each 28 to 30 percent of Dimensions. POST /checkin
accepts one uploaded image and returns JSON listing every QR code found in
it, each with its value and QR type.
5. Seed the random generator with 2026 and write 10 PNG files to testset/,
no two holding the same value: standard-01 to standard-03, each carrying a
ticket ID made of TKT- and eight random digits; pair-01, one image holding
two more ticket codes side by side and upright, with 30 pixels of
background between their dark modules; styled-01 to styled-03, ticket
codes at Highest with the step 4 logo and three different dark, saturated
foreground colors on white; micro-01 and micro-02, Micro QR codes carrying
seat numbers such as C07; and rmqr-01, an rMQR code carrying an event URL.
Save every testset code the same way at a Dimensions of 400, except 300
for the styled and Micro QR codes and 600 for rmqr-01, and resize no code
afterward unless standard-02 calls for it.
Keep standard-01 clean. Make standard-02 look photographed: scale it to 60
percent, rotate it 30 degrees, blur it with a Gaussian radius of 1.5
pixels, and center it on a 600 x 600 light gray canvas. Give standard-03
sensor grain: Gaussian noise with a standard deviation of 20 gray levels,
one value per pixel added to all three channels, over the whole image.
Record in manifest.csv each file, every value it holds, its QR type, the
error correction level used, and its distortion (none, photographed,
grain, pair, or styled).
6. Measure each saved image before /checkin is ever called, and repair the
generator whenever a measurement falls outside its range: the pixel size
step 5 implies;
on the styled codes and the /ticket output, the logo's share of the symbol
area, 7 to 10 percent; on the styled codes, the foreground's WCAG contrast
ratio against the background, 7 to 15; on the Micro QR codes, a square
symbol 11 to 17 modules wide; on the rMQR code, a symbol at least twice as
wide as it is tall; on standard-03, the mean absolute difference from the
clean code, 7 to 9 gray levels; on pair-01, the gap between the two codes'
dark modules, 28 to 32 pixels. Once /checkin has been called the first
time, the testset files are frozen: do not rewrite or edit them.
7. /checkin runs one fixed configuration for every upload: the same scan mode
or modes and the same image preparation, in the same order. It must never
open the manifest, hold a ticket ID, seat number, or URL as a literal, or
pick between results by comparing them with expected values. You choose
and change the configuration between runs; the program never does.
8. Build in Release and start the API. Request /ticket for a ticket ID drawn
from the seed that is not in the testset and save the PNG it returns as
ticket.png. POST ticket.png and every testset image to /checkin over HTTP
and save each raw response as checkin/<file name without .png>.json.
9. Write roundtrip.md with every step 6 measurement as a number for each
image (a bare pass or fail is not enough), the /checkin configuration,
and a results table with the columns file, distortion, expected value,
value read (the decoded string as the saved response holds it, even when
it is wrong), expected QR type, QR type read, and match, holding one row
per expected code, 12 rows in all. A row counts as a match only if the
decoded value equals the expected value exactly, the QR type agrees, and
the value appears in that file's saved response. An extra or repeated
code in a response fails every row of that file.
10. Until all 12 rows match, study the saved responses of the failing files,
adjust the /checkin configuration, rebuild, and repeat. Stop after the
eighth run that still has failures, and report the failing rows, each
configuration you tried, and your reading of the cause.
11. End with a brief summary covering the Release build outcome, how many
rows matched, the /checkin configuration, the measured step 6 values,
and every assumption you made.
輸出
這是standard-03.png,顆粒圖像,從乾淨代碼平均距離8.0灰度。 第一個簽入設置,普通Auto,讀取了其他11個代碼,僅漏掉了這一個。 具有sigma為1的高斯模糊讀取了它但丟失了styled-03.png和ticket.png,而中值濾波器,無論單獨還是與更寬的安靜區域一起使用,仍然錯過了它。 第五種設置通過施加3乘3中值濾波器並在半亮度處設置閾值然後在Auto中讀取來讀取了所有12個代碼。
未編輯的往返表列出了每個測量,每個嘗試過的設置和12行。
運送了一個橙色標誌,佔符號的7.84%。
- 獨立檢查重新測量了已保存文件的每個要求,Release構建的新啟動返回了相同的11個響應。
- 第五次運行之前,Claude Code在API之外嘗試了八種設置,其中三種讀取了每個代碼。
- Claude Code將提示的高斯係數1.5應用了為1.5的sigma。
- 步驟1, 3, 5和7的提示在同一會話中遵循,並且在步驟7中解碼了12個代碼中的每一個。
- NuGet現在標記
SixLabors.ImageSharp3.1.12表示Claude Code添加的釘選。 - 隨著代碼大小選擇開放,早期的提示草案讓普通Auto讀取了每個文件。
什麼過關
- 發行版本構建成功,未經您編輯。
- 打開圖像顯示了三種不同的深色前景,位於亮色方形標誌下,整個
standard-03.png的顆粒,以及在pair-01.png中並排放置的兩個直立代碼。
運行記錄
- 機器在Core i9-14900KF上運行Windows 11 x64,擁有64 GB記憶體。
- 每個專案都面向 .NET 9。
- 每個指南都運行了
IronQR2026.10.1。Copilot和Antigravity還引用了IronQR.Linux2026.10.1用於Linux構建,Copilot入門專案已包含PDFtoImage5.4.0,Cursor的最後提示將服務移動到IronQR.Slim2026.10.1以及IronSoftware.ReaderInternals.Windows2026.3.47413。 - 每個持續時間加起來就是該指南頁面上的提示日誌時間。 此指南的行數僅為驗收提示。
- 最後測試2026年10月7日,所有六次運行。
| 指南 | 助手和版本 | 模型 | 時長(分鐘) |
|---|---|---|---|
| 此指南 | Claude Code 2.1.277,一條信息,許可提示關閉 | Claude Opus 5 | 29.0 |
| Claude Code | Claude Code 2.1.277在opusplan | Claude Opus 5 用於計劃,Claude Sonnet 5 用於其餘部分 | 30.2 |
| ChatGPT Codex | Codex CLI 0.160.0 | GPT-6 Luna | 37.2 |
| GitHub Copilot | GitHub Copilot CLI 1.0.91 | GPT-6 Luna, routed by Auto | 26.9 |
| Cursor | Cursor 3.23.23 桌面應用 | Grok 4.7 | 50.8 |
| Google Antigravity | Antigravity CLI 1.3.1 | Gemini 3.8 Flash (High) | 53.6 |
代理特定指南
下面的每份指南將上述步驟應用於一個工具和一個QR工作。
- 在Claude Code中使用IronQR用於品牌營銷代碼,解碼標誌、顏色、邊緣、大小和糾錯的每個變體
- 在ChatGPT Codex中使用IronQR適用於平行解碼積壓的掃描和攝影圖像,附有
ReadAsync的失敗報告 - 在GitHub Copilot中使用IronQR適用於在現有PDF頁上戳上驗證代碼,包括受密碼保護的檔案,在一個文件管道中
- 在Cursor中使用IronQR用於從客戶照片中讀取代碼,使用正確的掃描模式、QR類型和角落點,遵循保持其他QR程式庫對外的規則
- 在Google Antigravity中使用IronQR適用於Blazor伺服器掃描器頁面,解碼伺服器上的上載並在真實瀏覽器中檢查
疑難排解
- 運行時複製異常如果機器學習DLL未從運行時文件夾中複製出來
- 在IronQR中應用授權金鑰
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。