使用IronQR與AI程式碼助理

Curtis Chau
Curtis Chau
已更新: 2026年10月9日

IronQR是Iron Software的.NET QR Code程式庫。 它可以編寫標準QR、Micro QR和rMQR符號,將它們用標誌和顏色設計,並使用機器學習檢測器讀取它們。 其指南和範例是公開的,因此編程助理可能在培訓中遇到過API。

培訓不會將發佈版本固定在您的專案中。 引用當前文檔的助理生成的程式碼將遵循其運行時規則,而依賴記憶的助理可能會生成能編譯但運行時失敗的程式碼。

本指南涵蓋了兩種類型的工具。

  • 助理在編輯器中工作,完成行或重寫方法,例如GitHub Copilot的行內建議。
  • 代理完成整個任務,編輯檔案、運行構建和程式,並返回結果以供檢視,如Claude Code、Cursor、ChatGPT Codex和Google Antigravity所做的那樣。

兩者都需要相同的設定。安裝套件,從環境中載入授權金鑰,提供IronQR的機器可讀文件,並使用IronQR的讀取器解碼每個已儲存的QR圖像,無論您是生成帶標誌的程式碼、選擇糾錯級別、讀取QR類型,或選擇掃描模式。

Claude Code標誌ChatGPT Codex標誌GitHub Copilot標誌Cursor編輯器標誌Google Antigravity標誌

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

或者從終端設置版本。

dotnet add package IronQR --version 2026.10.1
SHELL

普通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,免費試用。

第一步:
arrow pointer

在啟動時通過IronQr.License.LicenseKey設置一次金鑰,在任何IronQR調用之前,並從環境變數中讀取以將其保持在版本庫外。

IronQr.License.LicenseKey = Environment.GetEnvironmentVariable("IRONQR_LICENSE_KEY");
C#

設置有效金鑰後,IronQr.License.IsLicensed報告為true,並且同一類中有一個方法可以測試金鑰而不應用它。 異常類型不是公共的,因此一個命名的捕捉子句將無法編譯,並顯示CS0122。捕獲Exception並檢查消息。

請注意: IronQR授權金鑰涵蓋了Web.config,appsettings.json,和可以保存金鑰的其他地方。

步驟3:指導您的助理閱讀IronQR的LLM文檔

當任務依賴一個指南的細節時,讓助理打開該頁。

將索引與直接指令結合。

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

步驟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.
Markdown

當前技能檔案中的四個內容需要更正。 其單檔範例固定於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.
Text
提示: 隨後打開步驟4的專案檔案以確認規則是否生效。

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

每個符號類型接受哪種錯誤更正等級?

四個QrErrorCorrectionLevel成員不符合QR標準的字母。 High是Q級,Highest是H級,IronQR的XML文檔形容為留有標誌的空間。 Micro QR和rMQR只接受其中的一部分,其餘部分寫入調用會拋出IronQrEncodingException,信息如最高對於Micro QR無效。

成員QR標準微型 QRrMQR
LowL,恢復率約7%接受拋出
MediumM,約15%接受接受
HighQ,約25%接受拋出
HighestH,約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 88 of 8不需要修復
顆粒度,標準偏差20灰階0 of 80 of 8首先模糊
兩個直立代碼相隔30像素5到7 of 88 of 8添加OnlyBasicScan
海軍藍標誌代碼在模糊1.5像素後0到4 of 88 of 8添加OnlyBasicScan

拯救顆粒代碼的模糊就是讓Auto失去海軍藍標誌代碼的原因。 兩種設置在所有八組中讀取了所有12個代碼。 一種應用了1.5像素模糊然後OnlyBasicScan。 另一種應用了1到2像素模糊,運行Auto和OnlyBasicScan,並按值合併結果。 從失敗的圖像中選擇設置,然後在每次上載中保持不變。

顆粒還影響代碼大小。具有相同顆粒的350到425像素的代碼在所有24個檔案中以兩種模式均失敗,300, 500 和 600像素的代碼在兩者中都讀取,450 和 475像素的代碼僅在Auto中讀取。 在失敗代碼周圍添加100像素的白色讓OnlyBasicScan讀取了我們嘗試的所有12個檔案。


可重現的結果

驗收測試是在一個提示中完成的一個真實任務,無需手寫程式碼。 將其粘貼到空目錄的新會話中,並將結果與通過列表進行比較。

請注意: 運行它需要在具有互聯網連線的 Windows 機器上安裝 .NET 9 SDK、允許使用終端的助理以及在 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.
Text

輸出

Grainy test QR code that IronQR read correctly through the check-in API in the acceptance run

這是standard-03.png,顆粒圖像,從乾淨代碼平均距離8.0灰度。 第一個簽入設置,普通Auto,讀取了其他11個代碼,僅漏掉了這一個。 具有sigma為1的高斯模糊讀取了它但丟失了styled-03.png和ticket.png,而中值濾波器,無論單獨還是與更寬的安靜區域一起使用,仍然錯過了它。 第五種設置通過施加3乘3中值濾波器並在半亮度處設置閾值然後在Auto中讀取來讀取了所有12個代碼。

未編輯的往返表列出了每個測量,每個嘗試過的設置和12行。 API的票券運送了一個橙色標誌,佔符號的7.84%。

  • 獨立檢查重新測量了已保存文件的每個要求,Release構建的新啟動返回了相同的11個響應。
  • 第五次運行之前,Claude Code在API之外嘗試了八種設置,其中三種讀取了每個代碼。
  • Claude Code將提示的高斯係數1.5應用了為1.5的sigma。
  • 步驟1, 3, 5和7的提示在同一會話中遵循,並且在步驟7中解碼了12個代碼中的每一個。
  • NuGet現在標記SixLabors.ImageSharp 3.1.12表示Claude Code添加的釘選。
  • 隨著代碼大小選擇開放,早期的提示草案讓普通Auto讀取了每個文件。

什麼過關

  • 發行版本構建成功,未經您編輯。
  • 打開圖像顯示了三種不同的深色前景,位於亮色方形標誌下,整個standard-03.png的顆粒,以及在pair-01.png中並排放置的兩個直立代碼。
請注意: 更改步驟1中的版本以測試其他版本。 對IronQR的變更日誌記錄了每個變更。

運行記錄

  • 機器在Core i9-14900KF上運行Windows 11 x64,擁有64 GB記憶體。
  • 每個專案都面向 .NET 9。
  • 每個指南都運行了IronQR 2026.10.1。Copilot和Antigravity還引用了IronQR.Linux 2026.10.1用於Linux構建,Copilot入門專案已包含PDFtoImage 5.4.0,Cursor的最後提示將服務移動到IronQR.Slim 2026.10.1以及IronSoftware.ReaderInternals.Windows 2026.3.47413。
  • 每個持續時間加起來就是該指南頁面上的提示日誌時間。 此指南的行數僅為驗收提示。
  • 最後測試2026年10月7日,所有六次運行。
指南助手和版本模型時長(分鐘)
此指南Claude Code 2.1.277,一條信息,許可提示關閉Claude Opus 529.0
Claude CodeClaude Code 2.1.277在opusplanClaude Opus 5 用於計劃,Claude Sonnet 5 用於其餘部分30.2
ChatGPT CodexCodex CLI 0.160.0GPT-6 Luna37.2
GitHub CopilotGitHub Copilot CLI 1.0.91GPT-6 Luna, routed by Auto26.9
CursorCursor 3.23.23 桌面應用Grok 4.750.8
Google AntigravityAntigravity CLI 1.3.1Gemini 3.8 Flash (High)53.6

代理特定指南

下面的每份指南將上述步驟應用於一個工具和一個QR工作。


疑難排解


問題?

如果您有任何疑問,請聯繫support@ironsoftware.com

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

閱讀更多

準備好開始了嗎?

NuGet 下載次數 82,442版本:2026.11剛剛發布