Verwendung von IronBarcode mit GitHub Copilot, in der IDE und auf GitHub

Curtis Chau
Curtis Chau
Aktualisiert: 21. September 2026

IronBarcode-Projekte scheitern auf GitHub-Runnern an fehlenden nativen Abhängigkeiten und fehlenden Lizenzschlüsseln. Der Linux-Build benötigt ein Plattformpaket, das diese Abhängigkeiten mitbringt, und jeder Barcode-Aufruf benötigt einen Schlüssel. Copilot stößt auf beides, wenn es Ihr Projekt auf GitHub baut, und fehlgeschlagene Tests, die es sich nicht erklären kann, schicken es auf die Suche nach einem Fehler, der nie im Code lag.

Nichts davon erfordert das Verlassen Ihrer IDE. GitHub Copilot ist in Visual Studio, VS Code und JetBrains verfügbar, sodass Ihre bestehende Lösung, Projektverweise, NuGet-Einstellungen und Build-Pipeline dort bleiben, wo sie sind.

Es gibt kein Copilot-Plugin für IronBarcode und keine Einstellung, die aktiviert werden muss. Alles, was Copilot über Barcodes weiß, stammt aus dem Repository, von den Konventionen, die Sie dort festlegen, und der Umgebung, die Sie ihm bereitstellen. Der Assistent bearbeitet einen Zuschneidebereich oder eine Randänderung innerhalb einer Datei. Mit einer ausreichend genauen Aufgabenbeschreibung kann er Barcodes auf ein PDF stempeln oder einen fehlgeschlagenen Scan auf GitHub ohne Ihre Aufsicht korrigieren.

Die ML-basierte Erkennung von IronBarcode selbst ist eine separate Funktion mit einem eigenen Beispiel für den Konfidenzschwellenwert, und nichts im Folgenden betrifft sie.

Schnellstart
NuGetMit NuGet installieren

PM > Install-Package BarCode

Installieren Sie IronBarcode, indem Sie den obigen Befehl in der NuGet Packet Manager-Konsole ausführen, oder suchen Sie das Paket im NuGet Paket Manager.

Öffnen Sie Ihre Lösung in der IDE, die Sie bereits verwenden, und geben Sie folgenden Prompt in Copilot Chat ein, mit dem Projekt im Kontext. #solution ist der Visual Studio-Verweis, der eine Anfrage auf die gesamte Lösung bezieht. In VS Code verwenden Sie stattdessen #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

Das Beispiel benötigt zwei Aufrufe, einen, um das Symbol zu erstellen, und einen, um es auf die von Ihnen benannte Seite zu stempeln, und der Leitfaden zum Stempeln von Barcodes auf PDFs behandelt die Argumente für Seitenindex und Platzierung. Sie sollten beide in dem Vorschlag sehen. Alternativ können Sie dieselbe Anfrage an den Assistenten auf GitHub senden, der unbeaufsichtigt auf einem Branch ausgeführt wird und einen Pull-Request liefert. Das ändert, was Sie vorbereiten müssen.

Zwei Sicherheitshinweise, bevor Sie beginnen. Erstens: Halten Sie Lizenzschlüssel aus Prompts und Commits heraus, indem Sie sie in der Konfiguration, Umgebungsvariablen oder Repository-Geheimnissen speichern, wie im Leitfaden für Lizenzschlüssel beschrieben. Zweitens: Denken Sie daran, dass Copilot mit Schreibzugriff echte Pull-Requests öffnen kann, daher bleiben Branch-Schutzregeln und menschliche Überprüfung Ihre wichtigste Absicherung.



Wo passt Copilot in ein bereits in Visual Studio bestehendes Projekt?

Copilot operiert auf drei Ebenen, und der Umfang erweitert sich auf jeder.

Inline-Vervollständigungen und Chat leben im Editor. Sie eignen sich am besten für Änderungen, die in einer einzigen Aussage innerhalb einer Datei beschrieben werden können, wie zum Beispiel das Umschalten der Symbologie, das Hinzufügen eines Randes oder das Beschränken eines Lesers auf ein Format. Sie beschreiben die Änderung, überprüfen den resultierenden Diff und entscheiden, ob Sie sie annehmen oder verwerfen.

Der Mehrdateimodus des Editors übernimmt Änderungen, die sich über mehrere Dateien erstrecken. Er wählt die Dateien aus, führt Terminalbefehle aus, überprüft Ergebnisse und iteriert über Fehler. Verwenden Sie ihn für Migrationen und Refaktorierungen.

Der Assistent auf GitHub verwaltet Aufgaben, die Sie nicht direkt beaufsichtigen möchten. Sie geben Anweisungen über ein Issue, und später erhalten Sie einen Branch und einen Pull-Request. Nichts, was an den Editor gebunden ist, kann das tun, daher bezieht sich das Meiste, was folgt, auf diesen Modus.

Alle drei lesen Dokumentationen gut. Richten Sie eine auf die API-Referenz, fragen Sie, welche BarcodeReaderOptions Ihr Projekt auf ihren Standardwerten belässt, und die Antwort kommt zurück, ohne dass Sie sie manuell zusammensuchen müssen.

Wie committen Sie Konventionen, an die sich jede Oberfläche hält?

Benutzerdefinierte Anweisungen leben im Repository, sodass sie sowohl IDE-Vorschläge als auch unbeaufsichtigte Läufe formen. Schreiben Sie sie einmal und hören Sie auf, sie in Prompts zu wiederholen.

Verwenden Sie .github/copilot-instructions.md. Es ist die repositoryweite Datei, die in den IDEs, auf GitHub und in der Copilot-Codeüberprüfung gilt. Wenn IronBarcode in mehr als einem Repository der Standard ist, legen Sie die Regeln stattdessen einmal als benutzerdefinierte Anweisungen für die Organisation fest. Ein Organisationsinhaber auf einem Copilot Business- oder Enterprise-Plan kann dies tun, und diese Anweisungen erreichen Copilot Chat auf github.com, Copilot-Codeüberprüfung und unbeaufsichtigte Arbeiten dort. Copilot liest auch AGENTS.md überall im Baum, wobei die nächstgelegene Datei gewinnt, plus ein einzelnes CLAUDE.md oder GEMINI.md im Stammverzeichnis. Wenn Ihr Repository bereits Barcode-Regeln in AGENTS.md für ein anderes Tool aufbewahrt, respektiert Copilot sie, und Sie benötigen keine zweite Kopie.

# 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

Modelle neigen dazu, selbstsicher Antworten zu geben, anstatt Unsicherheit einzugestehen, sodass ein Aufruf wie BarcodeScanner.DecodeImageFile() gültig erscheinen kann, bis der Build fehlschlägt. Dem Modell zu erlauben, bei Unsicherheit aufzuhören, kostet nichts und hält erfundene APIs aus dem Diff heraus.

Für spezifischere Regeln platzieren Sie eine Datei in .github/instructions/ mit dem Namen something.instructions.md. Verwenden Sie ein applyTo:-Glob-Muster im Frontmatter, um gezielt nur passende Dateien anzusprechen. Zum Beispiel verhindert das Eingrenzen von Barcode-Regeln auf **/Services/** deren Einfluss auf nicht zusammenhängende Anfragen.

Was macht ein Issue aus, mit dem der Assistent arbeiten kann?

Sie schreiben das Issue und weisen es dann zu. Der Text ist das gesamte Briefing des Assistenten, und niemand steht für Rückfragen bereit, sobald er beginnt.

Hier ist eines, das in dreißig Sekunden erstellt wurde.

Title: Barcodes not scanning

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

Dieses Issue bietet nichts Konkretes: keinen Dateiverweis, keinen Hinweis darauf, welche Etiketten betroffen sind, keine Definition des korrekten Verhaltens und kein fehlschlagendes Beispiel. Der Assistent wird raten, und er könnte das Falsche reparieren.

Hier ist derselbe Fehler, so ausformuliert, wie ein Teamkollege ihn sich wünschen würde.

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

Ein gut definiertes Issue umfasst sechs Elemente: relevante Dateien, Framework- und Bibliotheksversionen, spezifische erwartete Ausgabe, tatsächliches Verhalten (einschließlich dessen, was nicht auftritt), klare Einschränkungen und definierte Akzeptanzkriterien.

Die Zeile über das korrekte Decodieren der Etiketten mit IronBarcode sagt dem Assistenten, dass die Barcodes gültig sind und der Fehler zwischen dem gedruckten Bild und den Depot-Scannern liegt, was einen großen Bereich aus der Suche entfernt. Ein Beispielordner verwandelt eine vage Beschwerde in Daten, die der Assistent testen kann.

Nach der Zuweisung arbeitet der Assistent selbstständig und meldet sich zur Überprüfung zurück. Sie prüfen den Diff, anstatt ihm bei der Arbeit zuzusehen.

Warum schlagen die Tests des Assistenten bei einem IronBarcode-Projekt fehl?

Der Assistent erstellt und testet auf GitHub in einer temporären Umgebung, die von GitHub Actions angetrieben wird, auf einem Ubuntu-Runner, es sei denn, Sie haben ihn auf einen Windows- oder selbst gehosteten verwiesen. Viele Projekte benötigen dort nur den Quellcode und eine Paketwiederherstellung. Ein IronBarcode-Projekt benötigt zwei zusätzliche Dinge. Es benötigt das Plattformpaket, dessen native Abhängigkeiten zu diesem Runner passen, und es benötigt einen Lizenzschlüssel. Ohne eines davon schlägt jeder Test, der einen Barcode schreibt oder liest, fehl, unabhängig davon, was der Assistent geändert hat. Da IronBarcode eine LicensingException auslöst, statt ein Wasserzeichen zu setzen, sieht ein fehlender Schlüssel wie ein defekter Test aus, nicht wie ein fehlendes Geheimnis.

Der Assistent beschuldigt seine eigene Änderung und beginnt, Code zu ändern, der bereits korrekt war, und er kann das lange Zeit weiter tun.

Verhindern Sie das, indem Sie die Umgebung in .github/workflows/copilot-setup-steps.yml vorbereiten. Statt einen Workflow von anderswo anzupassen, beschreiben Sie, was der Runner benötigt, und lassen Sie Copilot die Datei schreiben. Zwei Anforderungen sind leicht zu übersehen, also nehmen Sie beide in die Anfrage auf. Der Job muss copilot-setup-steps heißen. Und der Workflow läuft erst, wenn die Datei auf Ihrem Standardbranch vorhanden ist.

#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

Lesen Sie die Datei noch einmal durch, bevor Sie sie committen. Der Job-Name muss exakt übereinstimmen, die SDK-Version muss Ihrem Projekt entsprechen, und der Abhängigkeitsschritt muss sich auf den Linux-Leitfaden zurückführen lassen statt auf eine Vermutung. Mergen Sie die Datei in Ihren Standardbranch, denn der Workflow läuft nicht von einem Feature-Branch aus.

Zwei Punkte bestimmen, ob dies funktioniert.

Erstens, der Assistent erhält Ihren Lizenzschlüssel nicht automatisch. Er hat keinen Zugriff auf Actions, Codespaces oder Dependabot-Geheimnisse. Speichern Sie den Schlüssel separat: in den Repository- oder Organisationseinstellungen, öffnen Sie Geheimnisse und Variablen, wählen Sie die Registerkarte Agents und fügen Sie IRONBARCODE_LICENSE_KEY hinzu. Agents-Geheimnisse erreichen den Assistenten als Umgebungsvariablen, einschließlich innerhalb copilot-setup-steps.yml.

Zweitens, Copilot macht weiter, wenn ein Einrichtungsschritt fehlschlägt. Es überspringt die verbleibenden Schritte und beginnt die Arbeit in dem Zustand, in dem sich der Runner befindet. Eine Abhängigkeitsinstallation, die unbemerkt fehlschlug, sieht dann genau wie ein Codefehler aus. Lösen Sie den Workflow von Hand über die Registerkarte Actions einmal aus, bevor Sie darauf angewiesen sind.

Tipps: Wenn Barcode-Tests bei einem Pull-Request fehlschlagen, überprüfen Sie die Runner-Umgebung und das Lizenzgeheimnis, bevor Sie das Problem auf Codeänderungen zurückführen. Ziehen Sie für die Plattformanforderungen die Leitfäden Linux-Setup und NuGet-Pakete heran, anstatt sich auf das Gedächtnis zu verlassen.

Was sollten Sie prüfen, bevor Sie zusammenführen?

Überprüfen Sie den Pull-Request des Assistenten, als ob es ein Branch eines Teamkollegen wäre. Die Copilot-Codeüberprüfung kann einen ersten Durchgang über die Ausgabe machen und mechanische Probleme erkennen, bevor eine Person sie liest.

Für IronBarcode-Änderungen bestätigen Sie drei Dinge, bevor Sie genehmigen:

  • Jeder verwendete API-Name erscheint in der Dokumentation: achten Sie besonders auf Kodierungs-Enums, bei denen ein plausibler Fake sich nur durch einen einzigen Großbuchstaben unterscheiden kann.
  • Jeder Barcode, den die Änderung erzeugt, wird noch immer eingelesen: weder ein erfolgreicher Build noch eine Code-Überprüfung beweisen, dass ein Etikett gescannt wird.
  • Die Änderung blieb innerhalb der vom Issue gesetzten Einschränkungen: lässt man ihm Spielraum, behandelt der Assistent einen Bugfix oft als Erlaubnis, die Symbologie zu ändern oder das Aufrufmuster umzugestalten.

Verlangen Sie Round-Trip-Tests als Standardanfrage im selben Pull-Request.

/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

Das Vermeiden von Byte-Vergleichen verhindert instabile (flaky) Tests, da Bild-Encoder möglicherweise unterschiedliche Bytes über Versionen und Plattformen hinweg erzeugen, selbst wenn der dekodierte Barcode identisch bleibt.

Liegt der Fehler im Code oder im Scan?

Fehlgeschlagene Lesevorgänge sind die häufigste Frage, die IronBarcode-Benutzer stellen, und drei Ursachen erklären fast alle. Die Formate wurden nie deklariert, sodass der Leser jede Symbologie durchsucht hat, die er kennt. Das Symbol nimmt nur einen Bruchteil eines großen Fotos ein. Oder die Erfassung selbst ist schlecht, sei es unscharf, schräg oder ausgebleicht. Alle drei sind leserseitig, also sagen Sie dies in der Anfrage.

#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

Eine Diagnose liefert Ihnen eine Begründung, die Sie prüfen können, statt einer unerklärten Änderung, die Sie entwirren müssen. Begrenzen Sie die Änderung außerdem auf den Leser, sonst löst der Assistent ein Scanproblem, indem er jedes Etikett neu druckt. Drei Dokumentationsseiten behandeln die Einstellungen, auf die er zurückgreifen sollte: Geschwindigkeit, Zuschneidebereich und Bildkorrektur.

Der frühere Abschnitt behandelt den anderen Fall. Wenn der Code auf Ihrem Rechner korrekt liest, aber in einem Container oder auf einem Runner fehlschlägt, ist der Code selten schuld. Fügen Sie die vollständige Ausnahme ein, nicht eine Zusammenfassung, und richten Sie den Assistenten auf das Plattformpaket und die Dockerfile anstelle der Anwendung. Eine fehlende native Bibliothek gehört zum Image, nicht zum Quelltext. Ohne Einschränkungen fügt der Assistent womöglich ein try/catch hinzu, das den Fehler verbirgt, ohne ihn zu beheben.

Was funktioniert weiter, wenn niemand zusieht?

Richten Sie zuerst zwei Dinge ein. Anweisungen in .github/copilot-instructions.md leiten den Assistenten auf einem Nacht-Branch, wie sie Ihre IDE tagsüber leiten. Ein copilot-setup-steps.yml, das die nativen Abhängigkeiten von IronBarcode installiert, zusammen mit dem Schlüssel in den Agents-Geheimnissen, verhindert, dass er Code debuggt, der nie fehlerhaft war. Alles andere ist übliche Assistentennutzung, und sie gelingt besser, wenn diese beiden Dinge eingerichtet sind.

Die Überprüfung ist die gleiche, ob sie zehn Sekunden nach einer Vervollständigung oder am Morgen nach einem Pull-Request stattfindet, und sie wird am festen Maßstab im Leitfaden für KI-Coding-Assistenten und -Agenten gemessen. Claude Code, ChatGPT Codex, Cursor und Google Antigravity haben jeweils spezielle Anleitungen.


Fehlerbehebung


Fragen?

Wenn Sie Fragen haben, wenden Sie sich an support@ironsoftware.com.

Curtis Chau hat einen Bachelor-Abschluss in Informatik von der Carleton University und ist spezialisiert auf Frontend-Entwicklung mit Expertise in Node.js, TypeScript, JavaScript und React. Leidenschaftlich widmet er sich der Erstellung intuitiver und ästhetisch ansprechender Benutzerschnittstellen und arbeitet gerne mit modernen Frameworks sowie der Erstellung gut strukturierter, optisch ansprechender Handbücher.

Mehr lesen

Bereit loszulegen?

NuGet-Downloads 2,564,559Version:2026.11gerade veröffentlicht