如何在.NET QR Code專案中使用IronQR和Claude Code
行銷團隊要求每個行銷活動的QR Code使用品牌的海軍藍顏色、在中心展示logo,並以海報和貼紙兩種尺寸提供。 然而,每個額外的樣式選擇都可能降低掃描的可靠性。 例如,logo可能遮蓋模組,淺色的前景可能降低對比度,較小的印刷尺寸會降低像素密度。 QR Code在螢幕上看似正確,但在現實世界中仍可能失效。 Claude Code,Anthropic的程式碼代理,在終端、VS Code、JetBrains、桌面應用程式和網路上運行。 在任何環境中,它都能讀取專案、編輯文件並執行命令,因此可以呈現樣式化代碼、解碼已保存的文件,並調整樣式以保留有效負載。
IronQR在相同的.NET進程中生成和讀取QR Code,因此代理可以在每次變更後掃描。 程式庫會自動拒絕某些不可讀的設計。 手動調整logo大小過多或前景色接近白色背景時,保存時會引發IronQrException。 其他樣式選擇可能會成功保存,但稍後仍然無法解碼。 最可靠的方法是測試所有樣式變體矩陣並解碼每個保存的PNG。 此指南說明如何為此過程配置Claude Code,包括三個已測試的提示和每個提示所依賴的IronQR行為。
單個模型設置支持所有三個提示。opusplan別名在計劃模式下使用Opus,否則使用Sonnet,適合僅矩陣構建需要計劃的會話。
在終端中打開專案文件夾,啟動Claude Code,並運行/model opusplan。 在文件路徑前輸入@以交給Claude Code該文件,然後發送請求。
Install IronQR from NuGet here and make one branded QR code for the
spring-sale campaign in @Brand/campaigns.json. Use that entry's URL,
foreground color, and background color, put @Brand/logo.png in the center,
and save the result as out/spring-sale.png. Print the saved image's width
and height in pixels first, then open the file again with QrReader and print
the decoded text and whether it equals the campaign URL. The license key is
in the IRONQR_LICENSE_KEY environment variable.
這段代碼的最直接版本可能會失敗。 在我們的探測中,春季促銷代碼在默認錯誤更正級別與自動調整大小的logo下保存無誤,但讀取回空白或在讀取器的默認掃描模式下拋出ObjectDisposedException。 一個500像素代碼上的手動100像素logo讀回正確。
先檢查印刷寬度。在我們的探測中,未設定大小的樣式選項為此URL生成了49像素的圖像。
最小工作流程(5 個步驟)
- 從NuGet下載C# QR Code程式庫
- 在專案文件夾中啟動Claude Code,選擇帶有
/model的模型 - 在
CLAUDE.md記錄IronQR樣式規則,確保每個會話都從中開始 - 描述呈現的每個變體,從更正級別和logo大小到顏色和像素大小
- 以兩種掃描模式解碼每個保存的PNG
在.NET QR Code項目中Claude Code做什麼?
代理書寫渲染器,讀取品牌文件,為每個變體保存一個PNG,解碼每個文件,並報告哪些設計能夠保持。您指出活動需要哪些變體並查看返回的表格。
品牌化代碼使此檢查值得自動化,因為logo大小、更正級別和像素大小相互影響。 在測試運行中,IronQR將手動logo保存為600像素代碼寬度的30%,拒絕在某個活動中以120像素的相同比例保存,而另一個活動顯示相反情況。
在第一個提示中將IronQR命名為唯一的QR庫。 猜測包名稱的代理可以安裝一個看似相似,已發佈以捕捉該推測的對象,一種攻擊稱為slopsquatting。
您如何設置Claude Code?
用Anthropic的快速啟用指南安裝Claude Code並登入。 當它在終端中啟動並回復時,表示已準備就緒。
如何設立一個Claude Code可以工作的項目?
在第一個提示之前準備好儲存庫。 一個構建的.NET 9控制台專案,包含每個行銷活動的URL和顏色的Brand/campaigns.json文件以及logo文件,給代理提供真實的輸入來工作。 從該文件夾啟動Claude Code,以便會話局限於它。
Claude Code在每個會話開始時讀取CLAUDE.md,因此是放置超過一個提示的規則的地方。 快速入門添加包後,第二個提示寫入文件。
Write CLAUDE.md in the repository root with a section called QR codes. It
should tell every later session that IronQR (NuGet package IronQR, pinned to
the version now in BrandQr.csproj, namespaces IronQr and IronQr.Enum) is the
only QR library allowed here; that IronQR member names are checked against
IronQr.xml inside the ironqr.slim folder of the local NuGet cache before use;
that QrStyleOptions is always given an explicit Dimensions and Margins; that
the key comes only from IRONQR_LICENSE_KEY at startup and is never written to
a file or printed; and that a QR image counts as finished only after the saved
PNG has been decoded back to its exact payload.
XML路徑很重要,因為樣式和閱讀類型位於IronQR.Slim包中,而IronQR依賴於它,因此成員列表位於緩存的該文件夾內。 對於超過成員列表的指南,IronQR發布了一個代理索引在llms.txt。
在首次渲染之前處理授權。 沒有授權金鑰,QrWriter.Write和QrReader.Read都會拋出LicensingException,其消息為“需要生產授權”,且無水印的試用輸出可衰退到。 該異常類型不是公開的,所以程序應在從IRONQR_LICENSE_KEY設置密鑰後檢查License.IsLicensed,而不是通過名稱捕獲異常。 IronQR 授權金鑰 頁面涵蓋了如何獲取金鑰及IronQR從中讀取的位置。
哪些IronQR設定屬於CLAUDE.md?
每一行都通過構建探測或與授權金鑰運行的探測來檢查對IronQR 2026.10.1的符合性。 將區塊粘貼在QR Code部分下面。
## QR codes: IronQR 2026.10.1 behavior
- new QrStyleOptions { ... } starts at Dimensions 0 and margins 0, which
renders one pixel per module. The constructor with arguments defaults to
300 and 10. Always set both.
- Margins are added outside Dimensions. Dimensions 600 with Margins 24
saves a 648 x 648 PNG. Margins has no getter, so read MarginTop and the
other sides.
- QrErrorCorrectionLevel.High is level Q (about 25 percent) and Highest is
level H (about 30 percent). QrWriter.Write without options uses Highest.
- Build QrOptions with its constructor. An object initializer leaves
Encoding at None, and Write throws IronQrEncodingException.
- QrLogo width and height 0 let IronQR choose the logo size. A manual size
it cannot read back throws IronQrException from Save.
- Save checks a changed foreground color. It does not check a changed
background color.
- qr.Verify(expected) takes the expected text, not a file path.
- Save(style) keeps the style on the QrCode, so a later Save() repeats it.
- Do not put QrImageInput in a using block. Its explicit IDisposable.Dispose
throws NotImplementedException after a successful read. Its public
Dispose() works.
- Read every saved PNG with QrScanMode.Auto and QrScanMode.OnlyBasicScan.
黑色模組在黑色背景下保存時不出異常,且兩種掃描模式均無法解碼該文件。
如何控制QR Code的大小、邊距和顏色?
一個QrStyleOptions物件持有每個視覺選擇。Save應用它並返回一個您使用SaveAs寫入磁盤的位圖。 錯誤更正級別是另一個設置,位於QrOptions中,因為它改變了編碼的符號本身。
Dimensions以像素設置代碼大小,Margins則是四個邊的安靜區,而MarginTop和其他邊設置單邊。 Color畫深色模組,BackgroundColor畫淺色區域和邊距。 Logo採用QrLogo, 位圖、寬度、高度和角半徑。
在我們的探測中,400像素代碼具50像素的頂部和底部邊距及20像素的側邊邊距,保存於440 x 500。調整大小指南、邊距指南及顏色指南展示每個設置其本身。
Save不帶參數會返回一個250 x 250的圖像。 該尺寸是內部默認值。在每個錯誤更正級別中,logo最多有多大?
比更正百分比建議的更小。這些數字計算出Reed-Solomon解碼可以重建的代碼字,而中心的logo只是一個損壞來源。 我們將春季促銷URL以600像素渲染,使用純正方形logo,讓IronQR自動調整其大小,然後逐一手動增加其大小百分比,直到IronQR拒絕保存。
| 等級 | 已記錄的恢復 | 自動logo(寬度、面積) | 最大手動logo(寬度、面積) |
|---|---|---|---|
| 低 | 7% | 20%,4.0% | 23%,5.3% |
| 語言 | 15% | 30%,9.0% | 31%,9.6% |
| 高的 | 25% | 32.5%,10.6% | 39%,15.2% |
| 最高 | 30% | 32%,10.2% | 44%,19.4% |
在2026.10.1組件中,Auto調整大小嘗試的代碼寬度的分數短列表,從一半下降到二十分之一,並保持其讀取器最初解碼的第一個。 該列表解釋了為何High和Highest落在寬度的三分之一附近。 手動大小更高,到文檔恢復區域的60%到75%之間,但IronQR以其自身讀取器在全分辨率下檢查。 第二種掃描模式可能仍失敗於檢查通過的地方。
這些數字取決於有效載荷。 較長的URL產生更高密度的符號,擁有不同的限制,所以把該表當作權衡的形狀,讓矩陣測量您自己的活動。
如何在一個提示中測試每個樣式化IronQR變體?
在一個提示中要求整個網格,讓計劃模式先定下設計。按Shift+Tab直到狀態欄顯示計劃模式,然後發送提示。
Build Services/BrandedQrRenderer.cs, which renders one campaign from
@Brand/campaigns.json for a given QrErrorCorrectionLevel, logo mode, and
pixel size, and Services/ScanMatrix.cs, which renders every campaign at every
correction level (Low, Medium, High, Highest), with three logo modes (no
logo, a QrLogo of width and height 0 so IronQR sizes it, and a manual logo 30
percent of Dimensions wide that keeps the logo's aspect ratio), at the poster
and sticker sizes in the JSON. Call the matrix from Program.cs after the
spring-sale code. Save each PNG under out/matrix/. Decode every saved file
twice with a new QrReader each time, once with QrScanMode.Auto and once with
QrScanMode.OnlyBasicScan, and catch exceptions per file, including any that
Save throws. Write out/scan-matrix.csv with campaign, level, logo mode, size,
image width and height, the save result, and both read results, then print
how many variants decode to the exact URL in both modes. When the matrix has
run, have the general-purpose subagent check every IronQR member in the new
files against IronQr.xml and list any it cannot find.
每條條款關閉了一種使結果看起來比實際更好的途徑。
- 1.每種組合都有命名:三個活動、四個級別、三種logo模式和兩種尺寸共生成72個變體,因此
out/scan-matrix.csv中缺失的一行是可見的。 - 2.保存失敗是行:拒絕保存是一個結果,這些行顯示logo大小限制的位置。
- 3.每次讀取都有新的讀取器:一個失敗的讀取不會影響下一次。
- 4.一個第二代理檢查API:通用子代理加載
CLAUDE.md,而內建的Explore和Plan子代理跳過,所以檢查看到專案的規則。
在信任生成的IronQR代碼前您應該確認什麼?
QrScanMode.Auto只有在檢測模型找不到任何內容時才返回基礎掃描,而枚舉自身文件將其描述為檢測模型優先,然後“如果找不到則基本的暴力讀取”。 當模型找到代碼但無法解碼時,自動返回空結果,基本掃描從未運行。
基本掃描解碼了所有Quickstart失敗的變體,例外來自IronQR 2026.10.1內部。在我們的全矩陣校準程式中,每個文件Auto錯過都帶有一個logo,且八個中六個在High或Highest,這兩個級別擁有最多的冗餘用於logo。 在測試運行中,代理選擇的10像素平邊距,Auto錯過的八個中有兩個完全沒有logo。
將這些檢查加到相同的審查中。
- -構建:一個發明的成員失敗
dotnet build,並且以IronQR拼寫的using指令也如此,使用該包的拼寫,而命名空間為IronQr。 - -尺寸:比較每個保存寬度與請求大小加上兩側邊距。 不匹配顯示從未達到保存調用的樣式。
- -有效載荷:解碼磁盤上的文件。
Verify與IronQR自行記憶體渲染比較文本,因此文件路徑返回假,而以錯誤樣式寫入的文件未被察覺。
校驗和容錯指南涵蓋閱讀損壞的代碼並驗證返回的東西。 欲進行完整的IronQR任務從頭到尾以其自身的通行標準運行,請參見AI編碼助手指南。
在實際運行中,這些提示產生了什麼結果?
我們按順序將上述三個提示發送給Claude Code,在一個會話中。 品牌文件包含三個活動,600像素的海報尺寸和120像素的貼紙尺寸,旁邊是正方形logo和寬字標。 清理副本的獨立釋放構建然後重新運行矩陣並寫入相同的CSV,並且每個保存的PNG的獨立解碼都同意每行。
- -首次運行時,矩陣在兩種模式下匹配了72個變體中的0個。 在Claude Code刪除
QrImageInput上的using塊之後,72個中的55個匹配。 - -IronQR拒絕9個變體的保存,每一個都帶有手動的logo。 在其保存的63個文件中,基本掃描解碼了全部63個,自動解碼了55個。
- -對於Quickstart,Claude Code選擇了一個帶10像素邊距和50 x 50 logo的300像素代碼。 其320 x 320 PNG在第一次閱讀時匹配URL。
- -分支無發現任何IronQR成員缺失於
IronQr.xml。 - -每個提示留下了無手動編輯的整潔釋放構建,且矩陣總數等於校準運行。
- -一個打字回覆在非互動運行的會話中取代計劃對話框批准了第三提示的計劃。
此指南及其兄弟的版本、模型、時間和測試機器位於共享的運行紀錄中。
疑難排解
- -在IronQR中應用授權金鑰如果構建成功且第一次寫入拋出授權異常。
- -將Logo添加到QR Code如果保存手動大小的logo拋出IronQrException
- -設置QR Code錯誤更正級別如果變體需要更多冗餘來支持其logo
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。