Utiliser IronBarcode avec GitHub Copilot, dans l'IDE et sur GitHub
Les projets IronBarcode échouent sur les runners GitHub en raison de dépendances natives manquantes et de clés de licence manquantes. La compilation sous Linux nécessite un package de plateforme contenant ces dépendances, et chaque appel de code-barres nécessite une clé. Copilot rencontre ces deux problèmes lorsqu'il compile votre projet sur GitHub, et les échecs de tests qu'il ne peut expliquer l'amènent à rechercher un bug qui n'était jamais dans le code.
Rien de cela ne nécessite de quitter votre IDE. GitHub Copilot est disponible dans Visual Studio, VS Code, et JetBrains, donc votre solution existante, les références de projets, les paramètres NuGet, et le pipeline de compilation restent où ils sont.
Aucun plugin Copilot n'est disponible pour IronBarcode, et il n'y a pas de réglage à activer. Tout ce que Copilot sait des codes-barres provient du dépôt, des conventions que vous y enregistrez et de l'environnement que vous lui fournissez. L'assistant gère une région de recadrage ou un changement de marge dans un seul fichier. Avec suffisamment d'informations, il peut tamponner des codes-barres sur un PDF ou corriger un scan échoué sur GitHub sans que vous le surveilliez.
La détection par apprentissage machine propre à IronBarcode est une fonctionnalité distincte avec son propre exemple de seuil de confiance, et rien ci-dessous ne la touche.
Démarrage rapideOuvrez votre solution dans l'IDE que vous utilisez déjà, et mettez-la en contexte dans un chat Copilot avec le projet. #solution est la référence Visual Studio qui encadre une requête pour l'ensemble de la solution. Dans VS Code, utilisez #codebase à la place.
#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.
L'exemple nécessite deux appels, un pour créer le symbole et un pour le tamponner sur la page que vous nommez, et le guide sur l'application de codes-barres sur des PDFs couvre l'index de la page et les arguments de placement. Vous devriez voir les deux dans la suggestion. Alternativement, vous pouvez envoyer la même demande à l'assistant sur GitHub, qui fonctionnera sans surveillance sur une branche et livrera une pull request. Cela change ce que vous devez préparer.
Deux points de sécurité avant de commencer. Premièrement, gardez les clés de licence en dehors des invites et des commits en les stockant dans la configuration, les variables d'environnement, ou les secrets du dépôt comme décrit dans le guide des clés de licence. Deuxièmement, rappelez-vous que l'accès en écriture permet à Copilot d'ouvrir de vraies pull requests, donc la protection des branches et la revue humaine restent votre principale protection.
Flux de travail minimal en 5 étapes
- Télécharger la bibliothèque de codes-barres C# depuis NuGet
- Commitez
.github/copilot-instructions.mdavec les conventions IronBarcode du projet - Utilisez le chat en ligne pour de petites modifications et le mode multi-fichier de l'éditeur pour des plus grandes
- Pour le travail non supervisé, créez un ticket détaillé et assignez-le à l'assistant sur GitHub
- Examinez la pull request, en vérifiant chaque nom d'API contre la référence API
Où Copilot s'intègre-t-il dans un projet déjà présent dans Visual Studio ?
Copilot fonctionne à trois niveaux, et la portée s'élargit à chaque étape.
Les complétions en ligne et le chat sont intégrés à l'éditeur. Ils conviennent mieux aux changements qui peuvent être décrits en une seule phrase dans un fichier, comme changer la symbologie, ajouter une marge, ou limiter un lecteur à un format. Vous décrivez le changement, examinez le diff résultant, et choisissez de l'accepter ou de le rejeter.
Le mode multi-fichier de l'éditeur s'occupe des changements qui couvrent plusieurs fichiers. Il sélectionne les fichiers, exécute des commandes terminales, examine les résultats, et itère sur les erreurs. Utilisez-le pour les migrations et refactorisations.
L'assistant sur GitHub gère les tâches que vous ne souhaitez pas superviser directement. Vous fournissez des instructions via un problème, et recevez ensuite une branche et une pull request. Rien lié à l'éditeur ne peut faire cela, donc la plupart de ce qui suit concerne ce mode.
Tous les trois lisent la documentation correctement. Dirigez-en un vers la référence API, demandez quels BarcodeReaderOptions votre projet laisse à leurs valeurs par défaut, et la réponse revient sans assemblage manuel.
Comment enregistrer des conventions que chaque interface respecte ?
Des instructions personnalisées sont conservées dans le dépôt, donc elles façonnent les suggestions IDE et les exécutions sans surveillance de manière identique. Écrivez-les une fois et arrêtez de les répéter dans les invites.
Utilisez .github/copilot-instructions.md. C'est le fichier applicable au dépôt entier, et il s'applique dans les IDE, sur GitHub, et dans la revue de code de Copilot. Si IronBarcode est la norme sur plus d'un dépôt, définissez les règles une fois en tant qu'instructions personnalisées d'organisation à la place. Un propriétaire de l'organisation avec un abonnement Copilot Business ou Enterprise peut faire cela, et ces instructions atteignent le chat Copilot sur github.com, la revue de code de Copilot, et le travail sans surveillance là-bas. Copilot lit aussi AGENTS.md n'importe où dans l'arborescence, avec le fichier le plus proche qui l'emporte, plus un seul CLAUDE.md ou GEMINI.md à la racine. Si votre dépôt garde déjà des règles de code-barres dans AGENTS.md pour un autre outil, Copilot les respecte et vous n'avez pas besoin d'une seconde copie.
# 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.
Les modèles ont tendance à fournir des réponses confiantes plutôt qu'à reconnaître l'incertitude, donc un appel comme BarcodeScanner.DecodeImageFile() peut sembler valide jusqu'à ce que la compilation échoue. Permettre au modèle de s'arrêter en cas de doute ne coûte rien et empêche les APIs inventées d'apparaître dans le diff.
Pour des règles plus spécifiques, placez un fichier dans .github/instructions/ nommé something.instructions.md. Utilisez un glob applyTo: dans son frontmatter pour cibler uniquement des fichiers correspondants. Par exemple, limiter les règles de codes-barres à **/Services/** les empêche d'affecter des demandes non liées.
Qu'est-ce qui fait d'un problème un cas sur lequel l'assistant peut agir ?
Vous rédigez le problème, puis l'assignez. Le corps du ticket constitue toutes les instructions de l'assistant, et personne n'est là pour répondre aux questions de suivi une fois qu'il commence.
Voici un problème déposé en trente secondes.
Title: Barcodes not scanning
Some labels don't scan. Can we fix it?
Ce problème ne fournit rien de concret : aucune référence de fichier, aucune indication des étiquettes concernées, aucune définition du comportement correct, et aucun exemple d'échec. L'assistant devinera, et il se peut qu'il corrige la mauvaise chose.
Voici le même défaut rédigé comme un collègue le voudrait.
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.
Un problème bien défini comprend six éléments : fichiers pertinents, versions de framework et bibliothèque, résultat attendu spécifique, comportement réel (y compris ce qui ne se produit pas), contraintes claires et critères d'acceptation définis.
La phrase sur le décodage correct des étiquettes avec IronBarcode indique à l'assistant que les codes-barres sont valides et que le défaut se situe entre l'image imprimée et les scanners du dépôt, ce qui élimine une grande zone de recherche. Un dossier d'échantillons transforme une plainte vague en données que l'assistant peut tester.
Après affectation, l'assistant s'en va et revient pour révision. Vous vérifiez le diff plutôt que de le regarder travailler.
Pourquoi les tests de l'assistant échouent-ils sur un projet IronBarcode ?
L'assistant compile et teste sur GitHub dans un environnement éphémère alimenté par GitHub Actions, sur un runner Ubuntu sauf si vous l'avez dirigé vers un runner Windows ou auto-hébergé. De nombreux projets n'ont besoin que de la source et d'une restauration de package là-bas. Un projet IronBarcode a besoin de deux éléments supplémentaires. Il a besoin du package de plateforme dont les dépendances natives correspondent à ce runner, et il a besoin d'une clé de licence. Sans l'un ou l'autre, chaque test qui écrit ou lit un code-barres échoue, indépendamment de ce que l'assistant a changé. Parce qu'IronBarcode lance LicensingException au lieu de mettre un filigrane, une clé manquante ressemble à un test cassé, pas à un secret manquant.
L'assistant blâme son propre changement et commence à éditer un code qui était déjà correct, et il peut continuer à le faire pendant longtemps.
Prévenez cela en préparant l'environnement dans .github/workflows/copilot-setup-steps.yml. Plutôt que d'adapter un flux de travail d'ailleurs, décrivez ce dont le runner a besoin et laissez Copilot écrire le fichier. Deux exigences sont faciles à manquer, donc mettez les deux dans la requête. Le job doit être nommé copilot-setup-steps. Et le flux de travail ne s'exécute qu'une fois que le fichier existe sur votre branche par défaut.
#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.
Relisez le fichier avant de le valider dans le dépôt. Le nom du job doit correspondre exactement, la version du SDK doit correspondre à votre projet, et l'étape de dépendance doit pointer vers le guide Linux plutôt que de deviner. Fusionnez-le à votre branche par défaut, car le flux de travail ne s'exécute pas depuis une branche de fonctionnalité.
Deux points déterminent si cela fonctionne.
Premièrement, l'assistant ne reçoit pas automatiquement votre clé de licence. Il ne peut pas accéder aux secrets d'Actions, Codespaces, ou Dependabot. Stockez la clé séparément : dans les paramètres du dépôt ou de l'organisation, ouvrez Secrets et variables, sélectionnez l'onglet Agents, et ajoutez IRONBARCODE_LICENSE_KEY. Les secrets des agents atteignent l'assistant en tant que variables d'environnement, y compris dans copilot-setup-steps.yml.
Deuxièmement, Copilot continue lorsque l'étape de configuration échoue. Il saute les étapes restantes et commence le travail dans l'état actuel du runner. Une installation de dépendance qui a échoué sans bruit ressemble alors exactement à un bug de code. Déclenchez le flux de travail manuellement depuis l'onglet Actions une fois avant d'en dépendre.
Que faut-il vérifier avant de fusionner ?
Examinez la pull request de l'assistant comme vous le feriez pour une branche d'un collègue. La revue de code Copilot peut effectuer un premier passage sur le résultat et détecter les problèmes mécaniques avant qu'une personne ne le lise.
Pour les changements IronBarcode, confirmez trois choses avant d'approuver :
- Chaque nom d'API utilisé apparaît dans la documentation : portez une attention particulière aux énumérations d'encodage, où un faux plausible peut différer d'une seule lettre majuscule.
- Chaque code-barres que le changement produit est encore lisible : ni une compilation réussie ni une revue de code ne prouvent qu'une étiquette se scanne.
- Le changement est resté dans les contraintes définies par le problème : si on lui laisse de la latitude, l'assistant traite souvent une correction de bug comme une autorisation de changer la symbologie ou de retravailler le modèle d'appel.
Demandez systématiquement des tests aller-retour dans la même 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.
Éviter les comparaisons par octet empêche les tests instables, car les encodeurs d'image peuvent produire des octets différents selon les versions et les plateformes même lorsque le code-barres décodé reste identique.
Le problème est-il dans le code ou dans le scan ?
Les échecs de lecture sont le problème le plus souvent signalé par les utilisateurs d'IronBarcode, et trois causes expliquent presque tous ces échecs. Les formats n'ont jamais été déclarés, donc le lecteur a recherché chaque symbologie qu'il connaît. Le symbole occupe une fraction d'une grande photo. Ou la capture elle-même est médiocre, qu'elle soit floue, inclinée, ou délavée. Tous trois sont côté lecteur, donc dites-le dans la demande.
#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.
Un diagnostic vous donne un raisonnement à vérifier plutôt qu'une modification inexpliquée à démêler. Limitez la modification au lecteur aussi, ou l'assistant résoudra un problème de scan en réimprimant chaque étiquette. Trois pages de documentation couvrent les réglages qu'il devrait utiliser, sur la vitesse, la région de recadrage, et la correction d'image.
La section précédente couvre l'autre cas. Quand le code lit correctement sur votre machine mais échoue dans un conteneur ou sur un runner, le code est rarement en faute. Collez l'exception complète, pas une synthèse, et dirigez l'assistant vers le package de plateforme et le Dockerfile au lieu de l'application. Une bibliothèque native manquante appartient à l'image, pas à la source. Sans contrainte, il peut ajouter un try/catch qui cache l'échec sans le corriger.
Qu'est-ce qui continue de fonctionner quand personne ne regarde ?
Configurez deux choses en premier. Les instructions dans .github/copilot-instructions.md guident l'assistant sur une branche nocturne comme elles guident votre IDE pendant la journée. Un copilot-setup-steps.yml qui installe les dépendances natives d'IronBarcode, avec la clé dans les secrets Agents, l'empêche de déboguer un code qui n'a jamais été défaillant. Tout le reste est un usage ordinaire de l'assistant, et cela se passe mieux avec ces deux éléments en place.
La révision est la même qu'elle ait lieu dix secondes après une complétion ou le matin après une pull request, et elle est évaluée selon les critères fixes du guide des assistants et agents de codage AI. Claude Code, ChatGPT Codex, Cursor, et Google Antigravity ont chacun des instructions dédiées.
Dépannage
- Appliquer une clé de licence dans IronBarcode quand une pull request revient avec tous les tests de codes-barres en rouge.
- Code-barres non reconnu quand une étiquette se scanne sur votre bureau mais pas au dépôt.
- Packages NuGet d'IronBarcode pour épingler le package que votre fichier d'instructions devrait nommer.
- Utiliser IronBarcode sur Linux pour les dépendances natives que le runner doit installer.
Des questions ?
Si vous avez des questions, contactez support@ironsoftware.com
Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes et créer des manuels bien structurés et visuellement attrayants.