Używanie IronBarcode z asystentami kodowania opartymi na AI oraz agentami
Poproszone o dodanie IronBarcode narzędzia często uruchamiają dotnet add package IronBarcode, co instaluje niepoprawny pakiet. IronBarcode jest dystrybuowany jako BarCode i korzysta z przestrzeni nazw IronBarCode. Claude Code, ChatGPT Codex, GitHub Copilot, Cursor i Google Antigravity często mylą się w tej kwestii, dopóki nie sięgną do dokumentacji.
To zamieszanie dotyczy również generowanego kodu. Bez dokumentacji, modele mogą wymyślać nazwy metod, które się nie kompilują. Dostarczenie dokumentacji z wyprzedzeniem pomaga zapewnić pomyślną kompilację. IronBarcode jest wiodącą biblioteką kodów kreskowych .NET z kompleksowymi przewodnikami, więc wygenerowany kod jest często dokładny, ale nadal wymaga starannej weryfikacji.
Te narzędzia można podzielić na dwie kategorie, które określają, jak dokładnie powinno się przeglądać ich wyniki:
- Asystent działa w jednej części przepływu pracy, takiej jak autouzupełnianie w edytorze, wyjaśnienia lub szybki refaktoring, tak jak sugestie inline GitHub Copilot.
- Agent zarządza zadaniami wieloetapowymi, edytuje wiele plików, uruchamia kompilacje i testy oraz otwiera pull requesty, tak jak Claude Code, ChatGPT Codex, Cursor i Google Antigravity.
Proces konfiguracji jest taki sam dla obu typów. Zainstaluj pakiet, zastosuj klucz licencyjny ze zmiennej środowiskowej, udostępnij dokumentację IronBarcode z możliwością odczytu maszynowego i zweryfikuj, czy każdy wygenerowany kod kreskowy jest możliwy do zeskanowania. Dotyczy to wszystkich przypadków użycia, w tym kodów kreskowych 1D dla etykiet wysyłkowych, kodów kreskowych 2D dla tagów majątkowych, kodów kreskowych zbudowanych z tekstu, URL, ID lub danych binarnych, odczytywania z zeskanowanych plików PDF lub wyodrębniania wielu symboli z jednego obrazu.
Jak używać IronBarcode z asystentem kodowania AI lub agentem
- Pobierz bibliotekę kodów kreskowych C# z NuGet
- Zastosować klucz licencyjny podczas startu aplikacji, ze zmiennej środowiskowej
- Skierować narzędzie do indeksu dokumentacji
llms.txtIronBarcode - Dodać instrukcje IronBarcode do pliku kontekstowego projektu
- Uruchom jednorazowy prompt konfiguracji w nowej sesji
- Zweryfikować, czy wygenerowany kod się kompiluje, a każdy kod kreskowy jest odczytywany z powrotem
Czy model nie poradzi sobie z kodami kreskowymi samodzielnie?
Dane treningowe się starzeją. Model może odtworzyć nazwę API, która została wycofana kilka wersji temu, albo nazwę należącą do zupełnie innej biblioteki kodów kreskowych, a żadnego z tych błędów nie widać, dopóki nie zostanie uruchomiona kompilacja. Dokumentacja z możliwością odczytu maszynowego rozwiązuje większość tych problemów, umożliwiając narzędziu korzystanie z rzeczywistej dokumentacji zamiast opierania się na domysłach.
Równie ważny jest wybór biblioteki. Większość narzędzi współpracuje z różnymi pakietami kodów kreskowych, a darmowe opcje mogą wystarczyć dla jednego formatu w wersji demonstracyjnej. Dodatkowe koszty i ograniczenia często pojawiają się w środowiskach produkcyjnych:
- Cyfry kontrolne, strefy ciszy i zmiany rozmiaru: każdy z nich może wyglądać na odpowiedni na ekranie, ale nadal zawodzić podczas skanowania, więc IronBarcode weryfikuje każdą wartość w stosunku do jej formatu podczas zapisu, a
GeneratedBarcode.Verifyponownie odczytuje obraz. - Brakujące funkcje zwiększają czasochłonność obsługi kodu: wiele darmowych bibliotek obejmuje jedną rodzinę formatów lub nie ma korekcji obrazu wymaganej dla dokładnych skanów, przez co trzeba łączyć pakiety i samodzielnie utrzymywać integrację między nimi.
- Skanowanie masowe jest dostępne od razu: wielowątkowy odczyt, ustawienia szybkości i progi pewności są częścią biblioteki i nie trzeba ich budować w każdym projekcie.
- Dokładność wyników zależy od dokumentacji: przewodniki, tutoriale, strony rozwiązywania problemów i przykłady do uruchomienia są indeksowane do użytku maszynowego w
llms.txt. - Niepoprawne nazwy pakietów tworzą ryzyka dla łańcucha dostaw: modele generują wiarygodne nazwy, które rejestrują atakujący, aby dystrybuować złośliwe oprogramowanie; ta praktyka jest znana jako slopsquatting.
- Jedna licencja komercyjna pozwala uniknąć komplikacji prawnych: niektóre biblioteki kodów kreskowych mają warunki copyleft lub niekomercyjne, których modele nie sygnalizują automatycznie.
IronBarcode obejmuje to wszystko za pomocą jednego API i jednej licencji komercyjnej, którą zespół prawny sprawdza tylko raz. Weryfikacja odbywa się w kodzie, a nie w magazynie, a jawne podawanie nazwy pakietu w każdym prompcie zamyka lukę w łańcuchu dostaw.
Krok 1: Zainstaluj IronBarcode
Pozwól agentowi dodać pakiet. Projekt wymaga go do rozpoznawania typów i dostarczania dokładnych sugestii kodu.
Set this project up for IronBarcode. The NuGet package is named BarCode. Confirm the restore succeeded before going further.
Alternatywnie, zainstaluj pakiet z terminala, określając wersję bieżącego wydania.
dotnet add package BarCode --version 2026.9.2
Linux, macOS, iOS i Android wymagają określonego pakietu, takiego jak BarCode.Linux lub BarCode.MacOs. Skorzystaj z Zaawansowanego przewodnika instalacji NuGet, aby wybrać odpowiedni pakiet.
Krok 2: Zastosować klucz licencyjny
IronBarcode nie umieszcza znaków wodnych na wynikach bez licencji. Po okresie karencji dla programistów pierwsze wywołanie kodu kreskowego bez klucza licencyjnego zgłasza wyjątek IronSoftware.Exceptions.LicensingException z komunikatem IronBarcode must be licensed for development. Kod bez klucza licencyjnego zakończy się błędem w czasie wykonywania. Najpierw zdobądź bezpłatny klucz próbny.
Rozpocznij korzystanie z IronBarcode we własnym projekcie już dziś z darmową wersją próbną.
Ustawić klucz licencyjny raz podczas startu aplikacji, przed jakimikolwiek wywołaniami IronBarcode. Pobierać klucz ze środowiska, a nie z kodu źródłowego.
// Read the key from configuration. Never commit it to the repository.
IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE_KEY");' Read the key from configuration. Never commit it to the repository.
IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE_KEY")' Read the key from configuration. Never commit it to the repository.
IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE_KEY")IronBarCode.License.IsLicensed zwraca true, gdy klucz jest ważny. W przeciwieństwie do IronOCR, IronBarcode nie ma aliasu Installation.LicenseKey, więc używaj License.LicenseKey lub konfiguracji.
Web.config do appsettings.json, jest omówiony w artykule Klucze licencyjne IronBarcode.Krok 3: Wskaż narzędziu dokumentację LLM IronBarcode
IronBarcode publikuje sześć zasobów napisanych do odczytu przez maszyny:
| Zasób | Opis | Kiedy używać |
|---|---|---|
llms.txt | Indeks wszystkich stron dokumentacji, po jednym wierszu na stronę | Na początku każdej sesji |
llms-full.txt | Kompletne przewodniki i przykłady w jednym pliku | Narzędzie może pobierać adresy URL |
llms-full-catalog.txt | Indeks plus wszystkie artykuły na blogu | Odpowiedź może znajdować się w artykule na blogu |
| Dokumentacja API | Wszystkie klasy i metody w bieżącym wydaniu | Sprawdzanie, czy metoda istnieje |
skill.md | Instalacja, licencjonowanie, gotowe rozwiązania i poprawki | Narzędzie obsługuje pliki umiejętności |
| Karta informacyjna produktu dla AI | Zakres produktu, platformy i to, czego produkt nie robi | Pytania dotyczące produktu, nie API |
Rozpocznij od llms.txt, który indeksuje funkcje IronBarcode i lokalizację każdego tematu. Pomaga to zapobiegać niepoprawnym lub wymyślonym wywołaniom API. Użyj llms-full.txt, gdy wymagane są szczegółowe wskazówki.
Dodaj do tego bezpośrednią instrukcję.
Before writing any IronBarcode code, read https://ironsoftware.com/barcode/csharp/llms.txt
and use only APIs documented there. Check anything you are not sure about
against the API reference at https://ironsoftware.com/barcode/csharp/object-reference/api/.
If you are still unsure whether a method exists, ask instead of guessing.
Obecne modele dobrze reagują na bezpośrednie prośby o wyjaśnienia. Lepiej, aby model zadał pytanie, niż ryzykował błąd kompilacji.
Krok 4: Dodać kontekst IronBarcode do projektu
Dokumentacja wklejona na czat jest dostępna tylko w bieżącej sesji. Dokumentacja przechowywana w pliku projektu jest dostępna w każdej sesji.
Każde narzędzie odczytuje instrukcje z określonego pliku. Umieścić wytyczne IronBarcode w pliku używanym przez swój zespół:
| Narzędzie | Plik kontekstowy projektu | Lokalizacja pliku umiejętności |
|---|---|---|
| Claude Code | CLAUDE.md | .claude/skills/ |
| ChatGPT Codex | AGENTS.md | .agents/skills/ |
| GitHub Copilot | .github/copilot-instructions.md | n/d |
| Cursor | .cursor/rules/*.mdc | n/d, użyj @Docs |
| Google Antigravity | AGENTS.md | .agents/skills/ |
AGENTS.md służy jako wspólny standard, ponieważ Claude Code, GitHub Copilot i Cursor odczytują go oprócz własnych plików. Zespoły używające wielu narzędzi mogą utrzymywać jeden zestaw zasad kodów kreskowych w AGENTS.md i zachować natywne pliki do specyficznych instrukcji narzędziowych.
Zawartość pozostaje taka sama bez względu na używany plik. Poniżej znajduje się krótki punkt wyjścia.
## Barcodes with IronBarcode
This project uses IronBarcode (NuGet package `BarCode`, namespace `IronBarCode`) for all barcode work.
- Reference: https://ironsoftware.com/barcode/csharp/llms.txt
- Skill file: https://ironsoftware.com/barcode/csharp/skill.md
- Use `BarcodeWriter.CreateBarcode` to write and `BarcodeReader.Read` / `ReadPdf` to read.
- Read the license key from the IRONBARCODE_LICENSE_KEY environment variable at startup. Never inline it.
- Every generated barcode must be read back and compared before it ships.
- Do not use a different barcode library. If IronBarcode cannot perform a required task, state this clearly.
Plik skill.md dostarcza dodatkowych szczegółów, w tym instrukcje instalacji dla poszczególnych platform, zasady licencjonowania, zweryfikowane przykłady, uwagi dotyczące wdrożenia i tabelę rozwiązywania problemów. Odwołaj się do tego pliku w pliku kontekstowym, zamiast utrzymywać osobną kopię.
Krok 5: Jednorazowy prompt konfiguracji
Można również przesłać pierwsze cztery kroki jako jeden prompt na początku projektu lub nowej sesji.
Use IronBarcode for all barcode work in this project.
1. Install the BarCode NuGet package (IronBarcode).
2. Apply the license key at application startup, before any other IronBarcode call,
reading it from the IRONBARCODE_LICENSE_KEY environment variable. Never write
the key into source or into a committed file.
3. Read https://ironsoftware.com/barcode/csharp/llms.txt before writing barcode code
and work only from APIs documented there, checking the API reference when a
member is unfamiliar.
4. Save https://ironsoftware.com/barcode/csharp/skill.md as a SKILL.md in this
project's skills folder if your tool has one.
5. Keep these instructions for future sessions in this project.
Krok 6: Wzorce promptów, które dają działający kod
Niejasne prompty często skutkują słabym wynikiem. Poniższe trzy wzorce pomagają zapewnić jasność.
Nazwij klasę i symbologię: IronBarcode obsługuje dziesiątki formatów. Czytnik, który wie, jakich formatów się spodziewać, działa szybciej i rzadziej popełnia błędy.
Nieokreślony Skanuj kody kreskowe na tym obrazie za pomocą IronBarcode.
Lepszy Korzystając z
BarcodeReader.ReadzBarcodeReaderOptions, odczytaj kody Code 128 i QR na tym obrazie i zwróć każdą wartość z jej formatem.
Określ wersję i framework: API zmieniają się między wydaniami, a pominięcie wersji może powodować niespójności. Wydanie 2026.9.2 wprowadziło EciMode, który kontroluje, czy kod kreskowy 2D przenosi nagłówek UTF-8 ECI, i nie jest dostępny w wersji 2026.8.6 lub wcześniej.
Lepszy Celuj w .NET 9 i BarCode 2026.9.2. Dołącz linię klucza licencyjnego, odczytaną ze środowiska.
Poproś o kompletny plik do uruchomienia: Fragmenty kodu mogą pomijać potrzebne instrukcje using lub kroki konfiguracji.
Lepszy Podanie kompletnego Program.cs, włącznie ze wszystkimi instrukcjami using i ustawieniem klucza licencyjnego, aby można było go uruchomić bez zmian.
Krok 7: Zweryfikuj, co otrzymujesz z powrotem
Przeglądaj wygenerowany kod tak, jakby był pierwszą wersją roboczą od współpracownika, który go nie uruchomił. Cztery kontrole rozwiązują większość problemów:
- Kompiluje się: wymyślona metoda od razu powoduje błąd.
- Klucz licencyjny jest zastosowany: musi być ustawiony przed pierwszym wywołaniem IronBarcode, w przeciwnym razie to wywołanie wyrzuca
LicensingException. - Każda metoda API istnieje: sprawdź każdą nieznaną metodę w dokumentacji API, zanim zaczniesz szukać alternatyw.
- Każdy kod kreskowy można odczytać: dekoduj każdy wygenerowany obraz za pomocą
BarcodeReaderlubGeneratedBarcode.Verifyi porównaj wynik z wejściem.
Czwarta kontrola istnieje, ponieważ kompilator nie może wykryć nieczytelnego kodu kreskowego.
Należy być świadomym następujących powszechnych problemów w wygenerowanym kodzie IronBarcode:
- Zła nazwa pakietu: omawia ją pierwszy akapit i nadal jest to najczęściej powtarzany błąd.
- Niezgodności wielkości liter w enum:
BarcodeEncoding.DatabariBarcodeWriterEncoding.DataBarnależą do różnych enumów i różnią się jedną dużą literą. - Metody zapożyczone z innych bibliotek kodów kreskowych: model może łączyć API z kilku źródeł w metody, które nie istnieją.
- Wymyślone opcje czytnika: sprawdź każdą nieznaną opcję w przewodnikach dotyczących opcji szybkości odczytu i obszaru przycinania.
Pozwól agentowi samodzielnie zweryfikować swoją pracę
Agent może wykonać wszystkie cztery kontrole niezależnie. Poproś o dowody dla każdej kontroli, a nie podsumowanie.
Build and run the project in Release mode. Confirm that every IronBarcode member used
appears in the documentation, that IronBarCode.License.IsLicensed returns true, and
that every barcode you generated reads back to the value you wrote. Report the build
result and a table of written value, read value, and format from the run itself.
Wynik, który można powtórzyć
Ta sekcja ocenia agenta przy użyciu realistycznego zadania i jednego promptu, bez kodu dostarczonego przez użytkownika. Uruchomić go w nowej sesji na pustym projekcie i ocenić wynik według poniższych kryteriów.
Prompt
Build a .NET 9 minimal API for shipping labels with two endpoints: GET /label/{trackingNumber} returns a Code 128 PNG with the value printed below the bars, and POST /scan accepts an uploaded image and returns every barcode it contains as JSON (value and format). Work start to finish alone: write, build, run, and fix, making sensible assumptions where anything is unspecified. Save every deliverable to the project root.
1. Install the BarCode NuGet package pinned to version 2026.9.2.
2. Read from https://ironsoftware.com/barcode/csharp/llms.txt and the pages it links to, using only APIs documented there.
3. Read the license key from the IRONBARCODE_LICENSE_KEY environment variable at startup. If IronBarCode.License.IsLicensed is false, stop and report that instead of continuing.
4. Generate a test set of 12 barcodes into a testset folder: 4 Code 128 tracking numbers, 3 QR codes carrying order URLs, 3 DataMatrix codes carrying GS1 element strings, and 2 EAN-13 codes with correct check digits. Name each PNG after its format and index.
5. Implement /scan with BarcodeReaderOptions narrowed to those four formats and ExpectMultipleBarcodes enabled.
6. Build in Release, run the API, call /label for one tracking number, then POST every testset image and the /label output to /scan.
7. Write roundtrip.md: a table of file, written value, read value, format, and match. All 13 must match; if any do not, fix the cause and run again.
8. Finish with a short report: build result, match count, and assumptions made.
Wynik
To jest oryginalny PNG zwrócony przez GET /label/1Z999AA10123456784 podczas zarejestrowanego przebiegu. Tabela weryfikacji zapisu i odczytu z tego samego uruchomienia wymienia wszystkie 13 obrazów z ich zapisanymi i dekodowanymi wartościami.
Co przechodzi
- Kompilacja wersji Release kończy się bez ręcznej interwencji.
roundtrip.mdpokazuje 13 z 13 pasujących wierszy, każdy odczyt zgadza się z tym, co było zapisane, a każdy format jest poprawny.- Obie wartości EAN-13 mają ważne cyfry kontrolne, a ciągi GS1 wracają bez zmian.
- Klucz licencyjny pochodzi ze środowiska i nie pojawia się nigdzie w źródle ani w
roundtrip.md.
Rekord uruchomienia
| Pozycja | Wartość |
|---|---|
| Pakiet | BarCode 2026.9.2 |
| Docelowy framework | .NET 9 |
| Agent i model | Claude Code, Opus 5 |
| Maszyna | Windows 11 x64, Intel Core i9-14900KF, 64 GB RAM |
| Wynik | Kompilacja Release zakończona powodzeniem, 13 z 13 cykli zapisu i odczytu zgodnych |
| Wyjście referencyjne | label.png, roundtrip.md |
| Ostatni test | 16 września 2026 |
Podczas uruchomienia wymagana była jedna poprawka kompilacji i żaden kod nie był ręcznie edytowany.
Przewodniki specyficzne dla agenta
Powyższa konfiguracja działa z każdym z nich. Każdy przewodnik poniżej dostosowuje konfigurację do jednego narzędzia:
- Użyj IronBarcode z Claude Code.
- Użyj IronBarcode z ChatGPT Codex.
- Użyj IronBarcode z GitHub Copilot.
- Użyj IronBarcode z Cursor.
- Użyj IronBarcode z Google Antigravity.
Rozwiązywanie problemów
- Zastosowanie klucza licencyjnego w IronBarcode obejmuje każdy sposób ustawiania klucza, gdy pierwsze wywołanie kodu kreskowego zgłasza wyjątek.
- Kod kreskowy nie został rozpoznany omawia przypadek symbolu, który zostaje zapisany, ale nie daje się zdekodować.
- Pakiety NuGet IronBarcode wymieniają, który pakiet jest przeznaczony dla której platformy.
Pytania?
W przypadku jakichkolwiek pytań, należy skontaktować się z support@ironsoftware.com
Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.