Używanie IronBarcode z asystentami kodowania opartymi na AI oraz agentami

Curtis Chau
Curtis Chau
Zaktualizowano: 21 września 2026

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.

Logo agenta kodowania AI Claude CodeLogo agenta kodowania AI ChatGPT CodexLogo asystenta kodowania AI GitHub CopilotLogo edytora kodu AI CursorLogo agenta kodowania AI Google Antigravity

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

Alternatywnie, zainstaluj pakiet z terminala, określając wersję bieżącego wydania.

dotnet add package BarCode --version 2026.9.2
SHELL

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

Pierwszy krok:
arrow pointer

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");

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.

Uwaga: Każdy inny sposób ustawienia klucza, od 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óbOpisKiedy używać
llms.txtIndeks wszystkich stron dokumentacji, po jednym wierszu na stronęNa początku każdej sesji
llms-full.txtKompletne przewodniki i przykłady w jednym plikuNarzędzie może pobierać adresy URL
llms-full-catalog.txtIndeks plus wszystkie artykuły na bloguOdpowiedź może znajdować się w artykule na blogu
Dokumentacja APIWszystkie klasy i metody w bieżącym wydaniuSprawdzanie, czy metoda istnieje
skill.mdInstalacja, licencjonowanie, gotowe rozwiązania i poprawkiNarzędzie obsługuje pliki umiejętności
Karta informacyjna produktu dla AIZakres produktu, platformy i to, czego produkt nie robiPytania 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.
Text

Obecne modele dobrze reagują na bezpośrednie prośby o wyjaśnienia. Lepiej, aby model zadał pytanie, niż ryzykował błąd kompilacji.

Uwaga: IronBarcode publikuje również gotowy do użycia plik umiejętności dla narzędzi, które je obsługują. Następny krok wyjaśnia, gdzie się do niego odwołać.

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ędziePlik kontekstowy projektuLokalizacja pliku umiejętności
Claude CodeCLAUDE.md.claude/skills/
ChatGPT CodexAGENTS.md.agents/skills/
GitHub Copilot.github/copilot-instructions.mdn/d
Cursor.cursor/rules/*.mdcn/d, użyj @Docs
Google AntigravityAGENTS.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.
Markdown

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.
Text
Porady: Ostatnia linia zwykle powoduje, że narzędzie zapisuje te zasady do swojego pliku kontekstowego z Kroku 4, takiego jak CLAUDE.md lub AGENTS.md. Monit wkleja się tylko raz.
Porady: Brak obrazów testowych? Poproś agenta, aby najpierw wygenerował je za pomocą IronBarcode, a potem ponownie je odczytał. Biblioteka kodów kreskowych to jedna z niewielu rzeczy, które agent może przetestować kompleksowo, operując wyłącznie na tekście. Zapisuje wartość, dekoduje obraz i porównuje ciągi.

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.Read z BarcodeReaderOptions, 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:

  1. Kompiluje się: wymyślona metoda od razu powoduje błąd.
  2. Klucz licencyjny jest zastosowany: musi być ustawiony przed pierwszym wywołaniem IronBarcode, w przeciwnym razie to wywołanie wyrzuca LicensingException.
  3. Każda metoda API istnieje: sprawdź każdą nieznaną metodę w dokumentacji API, zanim zaczniesz szukać alternatyw.
  4. Każdy kod kreskowy można odczytać: dekoduj każdy wygenerowany obraz za pomocą BarcodeReader lub GeneratedBarcode.Verify i 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.Databar i BarcodeWriterEncoding.DataBar należą 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.
Text

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.

Uwaga: Przed rozpoczęciem potrzebujesz SDK .NET 9, agenta kodowania AI, który może wykonywać polecenia, połączenie internetowe oraz klucz próbny lub produkcyjny IronBarcode w zmiennej środowiskowej IRONBARCODE_LICENSE_KEY. IronBarcode wyrzuca błąd zamiast umieszczania znaku wodnego, gdy nie ma klucza, więc ten test nie może przejść bez niego.

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

Wynik

Etykieta wysyłkowa Code 128 dla numeru przesyłki 1Z999AA10123456784, zwrócona przez GET /label w przebiegu testu akceptacyjnego

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.md pokazuje 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.
Uwaga: Przypnij wersję, aby dopasować własny projekt, zamieniając wydanie w kroku 1 na to, którego używasz. Historia zmian IronBarcode wymienia, co zmieniło się w każdym wydaniu.

Rekord uruchomienia

PozycjaWartość
PakietBarCode 2026.9.2
Docelowy framework.NET 9
Agent i modelClaude Code, Opus 5
MaszynaWindows 11 x64, Intel Core i9-14900KF, 64 GB RAM
WynikKompilacja Release zakończona powodzeniem, 13 z 13 cykli zapisu i odczytu zgodnych
Wyjście referencyjnelabel.png, roundtrip.md
Ostatni test16 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:


Rozwiązywanie problemów


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.

Czytaj więcej

Gotowy, aby rozpocząć?

Pobrania z NuGet 2,564,559Wersja:2026.11właśnie wydane