Używanie IronBarcode z GitHub Copilot, w IDE i na GitHub

Curtis Chau
Curtis Chau
Zaktualizowano: 21 września 2026

Projekty IronBarcode zawodzą na runnerach GitHub z powodu brakujących natywnych zależności i brakujących kluczy licencji. Kompilacja na Linux potrzebuje pakietu platformy zawierającego te zależności, a każde wywołanie kodu kreskowego wymaga klucza. Copilot napotyka oba te wymagania przy kompilacji projektu na GitHub, a nieudane testy, których nie może rozwiązać, kierują go na poszukiwanie błędu, który nigdy nie istniał w kodzie.

Nic z tego nie wymaga opuszczania IDE. GitHub Copilot jest dostępny w Visual Studio, VS Code i JetBrains, więc istniejące rozwiązanie, odwołania do projektów, ustawienia NuGet i pipeline kompilacji pozostają na swoim miejscu.

Nie ma wtyczki Copilot dla IronBarcode i nie ma ustawienia do włączenia. Wszystko, co Copilot wie o kodach kreskowych, pochodzi z repozytorium, z konwencji zapisanych tam przez użytkownika i z udostępnionego mu środowiska. Asystent obsługuje obszar przycięcia lub zmianę marginesu wewnątrz jednego pliku. Dobrze poinformowany, może stemplować kody kreskowe na PDF lub naprawić nieudane skanowanie na GitHub bez nadzoru.

Wykrywanie oparte na uczeniu maszynowym w IronBarcode to osobna funkcja z własnym przykładem progu pewności; poniższy opis jej nie dotyczy.

Szybki start
NuGetInstalacja z NuGet

PM > Install-Package BarCode

Zainstaluj IronBarcode, wykonując powyższe polecenie w konsoli Menedżera Pakietów NuGet lub wyszukaj pakiet w Menedżerze Pakietów NuGet.

Otworzyć rozwiązanie w używanym IDE i przekazać poniższy prompt do Copilot Chat z kontekstem projektu. #solution to odniesienie Visual Studio, które obejmuje żądanie w całym rozwiązaniu. W VS Code użyć zamiast tego #codebase.

#solution Add the BarCode package to this project. In Program.cs, copy an
existing invoice PDF, then stamp a Code 128 barcode of the invoice number onto
the first page of the copy with StampToExistingPdfPage, which writes in place.
Take the license key from IRONBARCODE_LICENSE_KEY, never inline. Build, and fix
anything that breaks.
Text

Przykład potrzebuje dwóch wywołań: jednego do stworzenia symbolu, a drugiego do ostemplowania go na nazwanej stronie, a przewodnik po stemplowaniu kodów kreskowych na PDF obejmuje indeks strony i argumenty dotyczące umiejscowienia. Oba powinny znaleźć się w sugestii. Alternatywnie, można wysłać to samo żądanie do asystenta na GitHub, który będzie działał samodzielnie na gałęzi i dostarczy pull request. To zmienia, co należy przygotować.

Dwa punkty bezpieczeństwa przed rozpoczęciem. Po pierwsze, należy trzymać klucze licencyjne poza promptami i commitami, przechowując je w konfiguracji, zmiennych środowiskowych lub sekretach repozytorium, jak opisano w przewodniku po kluczach licencyjnych. Po drugie, należy pamiętać, że dostęp do zapisu pozwala Copilot otwierać rzeczywiste pull requesty, więc ochrona gałęzi i przegląd przez człowieka pozostają głównym zabezpieczeniem.



Gdzie Copilot pasuje do projektu już istniejącego w Visual Studio?

Copilot działa na trzech poziomach, a zakres poszerza się na każdym z nich.

Uzupełnienia w miejscu i czat znajdują się w edytorze. Są najlepsze do zmian, które można opisać w jednym stwierdzeniu w jednym pliku, takich jak zmiana symboliki, dodanie marginesu lub ograniczenie czytnika do jednego formatu. Należy opisać zmianę, przejrzeć wynikowe różnice i zdecydować o ich zaakceptowaniu lub odrzuceniu.

Tryb edytora dla wielu plików angażuje się w zmiany obejmujące kilka plików. Wybiera pliki, uruchamia polecenia terminala, przegląda wyniki i iteruje na błędach. Używać go do migracji i refaktoryzacji.

Asystent na GitHub zarządza zadaniami, które mają przebiegać bez bezpośredniego nadzoru. Instrukcje przekazuje się w zgłoszeniu, a wynikiem jest gałąź i pull request. Żadna funkcja związana z edytorem nie może tego zrobić, więc większość z tego, co następuje, dotyczy tego trybu.

Wszystkie trzy dobrze czytają dokumentację. Skierować jeden do dokumentacji API, spytać, które BarcodeReaderOptions projekt pozostawia w domyślnych ustawieniach, a odpowiedź wróci bez ręcznego składania.

Jak zapisać w repozytorium konwencje obowiązujące we wszystkich interfejsach?

Niestandardowe instrukcje znajdują się w repozytorium, więc kształtują sugestie IDE i samodzielne uruchomienia. Zapisać je raz, aby nie powtarzać ich w promptach.

Użyć .github/copilot-instructions.md. Jest to plik obejmujący całe repozytorium, i jest stosowany w IDE, na GitHub, i w Copilot code review. Jeśli IronBarcode jest standardem w więcej niż jednym repozytorium, ustalić zasady raz jako własne instrukcje organizacyjne zamiast tego. Właściciel organizacji na planie Copilot Business lub Enterprise może to zrobić, a te instrukcje docierają do Copilot Chat na github.com, przeglądu kodu Copilot i prac bez nadzoru tam. Copilot także czyta AGENTS.md gdziekolwiek w drzewie, przy czym pierwszeństwo ma najbliższy plik, plus jeden pojedynczy CLAUDE.md lub GEMINI.md w katalogu głównym. Jeśli repozytorium już przechowuje zasady kodu kreskowego w AGENTS.md dla innego narzędzia, Copilot je honoruje i druga kopia nie jest potrzebna.

# Copilot instructions

## Barcodes

- IronBarcode is this repository's barcode library. The package is BarCode, the
  namespace is IronBarCode, and no competing package may be introduced.
- Reference: https://ironsoftware.com/barcode/csharp/llms.txt
  Skill file: https://ironsoftware.com/barcode/csharp/skill.md
- The BarCode version is pinned in Directory.Packages.props. Changing it is its
  own pull request, never a side effect of another change.
- License keys come from configuration or IRONBARCODE_LICENSE_KEY, and never
  appear in source, in a commit, or in a pull request description.
- Cite a documentation page for any IronBarcode member you are not certain of.
  Saying you are unsure is an acceptable answer.

## Testing

- A barcode change is not complete until the generated barcode has been decoded
  and compared with the value that was written.
- Assert on decoded values and formats. Never compare image bytes.

## Pull requests

- Say which IronBarcode APIs the change introduces, and link the page for each.
- If the barcode tests fail, check the runner environment before changing code
  that the issue did not ask you to touch.
Markdown

Modele mają tendencję do dostarczania pewnych odpowiedzi zamiast uznania niepewności, więc wywołanie takie jak BarcodeScanner.DecodeImageFile() może wydawać się prawidłowe, dopóki kompilacja nie zawiedzie. Zezwolenie modelowi na zatrzymanie się w razie niepewności nic nie kosztuje i zapobiega wprowadzaniu do zmian nieistniejących API.

Dla bardziej szczegółowych reguł, umieścić plik w .github/instructions/ nazwany something.instructions.md. Użyć globu applyTo: w jego nagłówku frontmatter, aby kierować się tylko do odpowiednich plików. Na przykład, ograniczenie reguł kodów kreskowych do **/Services/** zapobiega ich wpływowi na niepowiązane żądania.

Jak przygotować zgłoszenie, które asystent może zrealizować?

Napisać zgłoszenie, a następnie przypisać je asystentowi. Treść to cała instrukcja asystenta, a nikt nie jest dostępny, aby odpowiedzieć na pytania dodatkowe, gdy się zacznie.

Oto zgłoszenie utworzone w trzydzieści sekund.

Title: Barcodes not scanning

Some labels don't scan. Can we fix it?
Markdown

To zgłoszenie nie dostarcza nic konkretnego: brak odniesienia do pliku, brak wskazania, których etykiet dotyczy problem, brak definicji poprawnego zachowania i brak przykładu niepowodzenia. Asystent będzie zgadywał i może naprawić niewłaściwą rzecz.

Oto ten sam błąd napisany tak, jak chciałby go współpracownik.

Title: Returns labels fail to scan at the depot; tracking numbers with lowercase letters

**Files:** Services/LabelService.cs, Services/ScanService.cs
**BarCode version:** as pinned in Directory.Packages.props
**Framework:** .NET 8

**Expected:** Every returns label is a Code 128 barcode, 400 by 120 px with the
value printed below, and reads back to the exact tracking number.

**Actual:** Labels for tracking numbers containing lowercase letters do not read
at the depot. Samples are in TestData/returns-failing/. The same labels read
correctly with IronBarcode on a developer machine. No exception is thrown.

**Constraints:** Do not change the symbology or the public signature of
LabelService.RenderPng. No new packages.

**Acceptance:** Existing tests pass, plus a new round-trip test covering every
file in TestData/returns-failing/ and a lowercase tracking number.
Markdown

Dobrze zdefiniowane zgłoszenie zawiera sześć elementów: odpowiednie pliki, wersje frameworka i bibliotek, konkretne oczekiwane wyjście, rzeczywiste działanie (w tym, co się nie zdarza), jasne ograniczenia i zdefiniowane kryteria akceptacji.

Linia o poprawnym dekodowaniu etykiet z IronBarcode informuje asystenta, że kody kreskowe są prawidłowe, a błąd leży między wydrukowanym obrazem a skanerami w magazynie, co znacznie zawęża obszar poszukiwań. Folder z przykładami zmienia nieprecyzyjne zgłoszenie w dane, które asystent może przetestować.

Po przypisaniu asystent wykonuje zadanie i przekazuje wynik do przeglądu. Sprawdzić różnicę zamiast oglądać jego pracę.

Dlaczego testy asystenta zawodzą w projekcie IronBarcode?

Asystent buduje i testuje na GitHub w tymczasowym środowisku uruchamianym przez GitHub Actions, na runnerze Ubuntu, chyba że skonfigurowano runnera Windows lub utrzymywanego samodzielnie. Wiele projektów potrzebuje jedynie kodu źródłowego i przywrócenia pakietów. Projekt IronBarcode potrzebuje dwóch dodatków. Potrzebny jest pakiet platformy, którego natywne zależności pasują do tego runnera, i potrzebny jest klucz licencyjny. Przy braku któregokolwiek z nich każdy test, który zapisuje lub czyta kod kreskowy, zawodzi, bez względu na to, co zmienił asystent. Ponieważ IronBarcode zgłasza LicensingException zamiast nakładać znaki wodne, brakujący klucz wygląda jak uszkodzony test, a nie brakujący sekret.

Asystent obarcza winą własną zmianę i zaczyna edytować kod, który już był poprawny, i może to robić przez długi czas.

Zapobiec temu, przygotowując środowisko w .github/workflows/copilot-setup-steps.yml. Zamiast adaptować workflow z innego miejsca, opisać, czego potrzebuje runner, i pozwolić Copilotowi napisać plik. Dwa wymagania są łatwe do przeoczenia, więc umieścić oba w żądaniu. Zadanie musi być nazwane copilot-setup-steps. I workflow uruchomi się dopiero wtedy, gdy plik znajdzie się w domyślnej gałęzi.

#project Write .github/workflows/copilot-setup-steps.yml for this repository.

The job must be named copilot-setup-steps exactly, or it is ignored. Trigger it
manually, and on push and pull request limited to that one file path.

Run it on ubuntu-latest with read access to repository contents. Check out the
repository, set up the .NET SDK for the version this project targets, install
the native dependencies IronBarcode needs on Ubuntu, then restore packages.

For those native dependencies, read
https://ironsoftware.com/barcode/csharp/get-started/linux/ and use what it lists
for Ubuntu rather than a list from memory. Add a comment saying the list can
change between releases.

Give me the finished YAML and nothing else.
Text

Przeczytać plik ponownie przed jego zatwierdzeniem. Nazwa zadania musi dokładnie pasować, wersja SDK musi pasować do projektu, a krok zależności musi wynikać z przewodnika Linux, a nie z domysłów. Włączyć to do domyślnej gałęzi, ponieważ workflow nie uruchamia się z gałęzi funkcjonalnej.

Dwa punkty określają, czy to działa.

Po pierwsze, asystent nie odbiera automatycznie klucza licencyjnego. Nie ma dostępu do sekretów Actions, Codespaces ani Dependabot. Przechowywać klucz osobno: w ustawieniach repozytorium lub organizacji, otworzyć sekcję Secrets and variables, wybrać kartę Agents i dodać IRONBARCODE_LICENSE_KEY. Sekrety Agents docierają do asystenta jako zmienne środowiskowe, w tym wewnątrz copilot-setup-steps.yml.

Po drugie, Copilot kontynuuje, gdy krok konfiguracji zawiedzie. Pomija pozostałe kroki i zaczyna pracować w jakimkolwiek stanie, w jakim znajduje się runner. Instalacja zależności, która nie powiodła się cicho, następnie wygląda dokładnie jak błąd w kodzie. Wyzwolić workflow ręcznie z karty Akcje raz przed rozpoczęciem korzystania z niego.

Porady: Jeśli testy kodów kreskowych zawodzą w pull requeście, zweryfikować środowisko runnera i sekret licencji przed przypisaniem problemu do zmian w kodzie. Należy korzystać z przewodników instalacji na Linux i pakietów NuGet w celu sprawdzenia wymagań platformy, zamiast polegać na pamięci.

Co należy sprawdzić przed scaleniem?

Przejrzeć pull request asystenta, tak jakby to była gałąź współpracownika. Przegląd kodu Copilot może wstępnie sprawdzić wynik i wychwycić proste błędy, zanim ktoś go przeczyta.

W przypadku zmian dotyczących IronBarcode należy potwierdzić trzy rzeczy przed ich zatwierdzeniem:

  • Każda użyta nazwa API pojawia się w dokumentacji: zwrócić szczególną uwagę na typy wyliczeniowe kodowania, gdzie wiarygodna podróbka może się różnić jedną dużą literą.
  • Każdy kod kreskowy, wygenerowany po zmianie, nadal jest odczytywany: ani kompilacja, ani recenzja kodu nie dowodzą, że etykieta jest skanowana.
  • Zmiana pozostała w granicach, określonych w zgłoszeniu: przy braku ograniczeń asystent często traktuje naprawę błędu jako pozwolenie na zmianę symboliki lub przerobienie wzoru wywołania.

Standardowo wymagać testów zapisu i ponownego odczytu w tym samym pull requeście.

/tests Ensure tests are included in the same pull request, not in a subsequent one. A
barcode change without accompanying tests is not reviewable.

Every barcode generated by the service must read back to the value and format it
went in as. An image without a barcode should return no results rather than
throw an exception. All existing samples in TestData/ must read as expected.

Assert on decoded values, not image bytes, and say in the PR description which
of these cases were already covered prior to your change.
Text

Unikanie porównań bajtów zapobiega niestabilnym testom, ponieważ enkodery obrazu mogą produkować różne bajty w różnych wersjach i platformach, nawet gdy dekodowany kod kreskowy pozostaje identyczny.

Czy błąd jest w kodzie czy w skanowaniu?

Nieudane odczyty to najczęstsze pytanie zadawane przez użytkowników IronBarcode, a trzy przyczyny tłumaczą prawie wszystkie z nich. Formaty nigdy nie zostały zadeklarowane, więc czytnik przeszukał każdą znaną sobie symbolikę. Symbol zajmuje ułamek dużego zdjęcia. Lub samo zdjęcie jest niskiej jakości: rozmazane, wykonane pod kątem lub wyblakłe. Wszystkie trzy są po stronie czytnika, więc należy zaznaczyć to w żądaniu.

#project Use the editor's multi-file mode for this scenario, as it spans the reader and the test data.

Warehouse photos in TestData/depot/ come back empty from ScanService, while the
same physical labels read fine on a handheld scanner.

Explain the cause before making any changes. The fix should be applied
only in BarcodeReaderOptions, so expected formats, crop area, speed, and
image filters are in scope, while LabelService.cs is not.

Conclude by reporting how many of those photos were readable before your change
and how many are readable after.
Text

Diagnoza daje uzasadnienie do sprawdzenia, zamiast niewyjaśnionej edycji do rozwikłania. Ograniczyć zmianę również do czytnika, w przeciwnym razie asystent rozwiąże problem ze skanowaniem przez ponowne drukowanie każdej etykiety. Trzy strony dokumentacji obejmują ustawienia, z których asystent powinien skorzystać, dotyczące prędkości, obszaru przycięcia i korekcji obrazu.

Wcześniejsza sekcja obejmuje drugi przypadek. Gdy kod czyta poprawnie na maszynie, ale zawodzi w kontenerze lub na runnerze, kod rzadko jest źródłem błędu. Wkleić pełną treść wyjątku, nie streszczenie, i skierować asystenta na pakiet platformowy i Dockerfile zamiast aplikacji. Brakująca natywna biblioteka należy do obrazu, a nie do źródła. Bez ograniczeń asystent może dodać try/catch, które ukrywa awarię, nie naprawiając jej.

Co działa bez nadzoru?

Najpierw skonfigurować dwie rzeczy. Instrukcje w .github/copilot-instructions.md kierują pracą asystenta na gałęzi podczas nocnego zadania, tak jak prowadzą IDE w ciągu dnia. A copilot-setup-steps.yml, który instaluje natywne zależności IronBarcode, wraz z kluczem w sekretach Agents, zapobiega debugowaniu kodu, który od początku był poprawny. Pozostałe czynności to standardowa praca z asystentem, która przebiega sprawniej po przygotowaniu tych dwóch elementów.

Recenzja jest taka sama, czy dzieje się dziesięć sekund po zakończeniu, czy w poranek po pull requeście, i jest oceniana względem stałej poprzeczki w przewodniku po asystentach i agentach kodowania AI. Claude Code, ChatGPT Codex, Cursor i Google Antigravity mają osobne przewodniki.


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