Comment utiliser IronPrint avec GitHub Copilot
Un dépôt de fret imprime un formulaire de transfert pour chaque remorque quittant ses quais. Le portail web du dépôt enregistre chaque formulaire sous forme de PDF rempli avec des champs pour le conducteur, le numéro de sceau, le nombre de palettes et les marchandises dangereuses, et un service .NET dans une solution Visual Studio imprime deux copies de chacun. Un assistant qui édite le service doit travailler dans cette solution, dans l'éditeur déjà utilisé par l'équipe.
GitHub Copilot offre le chat et le mode agent dans Visual Studio et VS Code, Copilot CLI pour le terminal, et un agent cloud GitHub qui répond à un problème assigné avec une demande de tirage. IronPrint envoie des PDF et des images à une imprimante depuis .NET, avec la taille de papier, le nombre de copies, la résolution et le nivellement des formulaires configurés sur un unique PrintSettings objet. Chacune des surfaces Copilot lit les règles IronPrint à partir de fichiers d'instructions dans le dépôt.
Les instructions ci-dessous demandent à Copilot un code d'impression construit sur IronPrint. Choisir le matériel de l'imprimante ou configurer un serveur d'impression est une tâche séparée qu'aucun assistant ne peut réaliser à partir du dépôt. Le guide de nivellement décrit le paramètre IronPrint dont dépendent ces formulaires.
Démarrage rapideLancez copilot depuis le dossier de la solution et envoyez l'instruction. Dans le CLI, @ devant un chemin attache ce fichier. Dans Visual Studio, Copilot Chat utilise # pour le même objectif.
Fill in @src/Depot.Printing/HandoverPrinter.cs so the depot can print its handover forms.
Use IronPrint 2026.10.1, the version Directory.Packages.props already pins.
Give the class three public static members:
- InstalledPrinters() returns the names from Printer.GetPrinterNames.
- BuildSettings(string printerName) returns the PrintSettings that @docs/print-profile.md describes.
- PrintAsync(string pdfPath, string printerName) checks the name first, then sends the job.
An unknown name throws an ArgumentException whose message lists the installed printers.
Build the solution and fix every error.
Then list the files you changed.
L'instruction ne nomme aucun paramètre individuel. Le profil d'impression dans docs/print-profile.md liste chacun, et Flatten est parmi eux.
La clé de licence va dans IRONPRINT_LICENSE_KEY, configurée dans l'environnement où Copilot fonctionne. IronPrint lui-même ne lit pas cette variable. Dans notre test, License.IsLicensed est resté faux avec la variable configurée jusqu'à ce que le programme affecte sa valeur à License.LicenseKey. D'autres emplacements pris en charge pour la clé sont listés dans le guide de la clé de licence.
Flux de travail minimal (5 étapes)
- Téléchargez la bibliothèque d'impression C# depuis NuGet
- Écrivez les règles IronPrint dans .github/copilot-instructions.md plus un fichier d'instructions spécifique au chemin
- Réglez Flatten sur chaque tâche de formulaire et vérifiez chaque nom d'imprimante par rapport à la liste installée
- Testez les PrintSettings que le code construit au lieu d'envoyer de vrais travaux
- Assignez le prochain changement à l'agent cloud comme un problème et vérifiez la demande de tirage par rapport à la référence de l'API IronPrint
Comment définir les conventions IronPrint pour Copilot ?
Les règles à l'échelle du projet appartiennent à .github/copilot-instructions.md. Le tableau de support de GitHub montre le support de ce fichier dans Copilot Chat sur Visual Studio, VS Code et les IDE JetBrains, et pour Copilot CLI, la révision de code Copilot et l'agent cloud. Visual Studio ajoute le fichier aux requêtes Copilot Chat uniquement lorsque la case des instructions personnalisées est cochée, sous GitHub, Copilot, Copilot Chat dans les paramètres des Options.
These rules apply to printing code in this repository:
- Handover forms print through IronPrint. The NuGet package and the namespace are both IronPrint.
- Add no other printing library and no System.Drawing.Printing code.
- Keep the IronPrint version that Directory.Packages.props sets. Only an upgrade task changes it.
- IRONPRINT_LICENSE_KEY holds the license key.
- IronPrint does not read that variable, so Program.cs copies its value into License.LicenseKey.
- Never print the value, and don't dump environment variables either.
- docs/print-profile.md is the print contract. Leave it as it is and suggest changes in your reply.
- https://ironsoftware.com/print/csharp/llms.txt indexes IronPrint's docs for agents.
- No printer on this machine finishes a job without someone answering a dialog.
- Don't send a print job from a session, a test or a dry run.
Printing tests follow these rules:
- Test the PrintSettings the code builds.
- A test never calls Printer.Print or Printer.PrintAsync with a printer name that exists.
La dernière règle d'impression provient de la machine de test. Là, Microsoft Print to PDF demande un nom de fichier et Adobe PDF a ouvert une fenêtre Créer un PDF Adobe, donc un travail envoyé à l'une ou l'autre imprimante attend qu'une personne réponde.
Comment donner ses propres règles au code d'impression ?
Les motifs applyTo de .github/instructions/printing.instructions.md limitent ses règles à une partie de l'arbre, dans ce cas les projets source et test. La documentation CLI de GitHub indique que le CLI ajoute un fichier spécifique au chemin à son contexte uniquement pour travailler sur un fichier dont la valeur applyTo correspond. Dans notre exécution, printing.instructions.md était le premier fichier ouvert par Copilot dans l'instruction 1.
---
applyTo: "src/**,tests/**"
---
Source and test code here follow these IronPrint rules:
- Set Flatten = true for every handover form.
- With Flatten false, IronPrint sends the page with four empty boxes.
- Those boxes are Driver, SealNumber, PalletCount and Hazmat.
- Check a printer name against Printer.GetPrinterNames before a job.
- IronPrint throws nothing for a name it cannot match, even by case or a trailing space.
- It prints on the Windows default printer instead.
- GetPrinterTrays returns an empty list for an unknown name, as it does for some real printers.
- So an empty tray list cannot prove that a printer exists.
- NumberOfCopies reaches the driver as a copy count.
- The job itself holds one page per PDF page.
- With no key, Printer.Print throws an AggregateException that wraps a LicensingException.
- PrintAsync throws the LicensingException itself.
- Margins takes millimeters, in the order left, top, right, bottom.
Chacune de ces règles a été mesurée avec IronPrint 2026.10.1. Les sections de Flatten et de nom d'imprimante ci-dessous donnent les mesures derrière la première d'entre elles.
Pourquoi les champs des formulaires s'impriment-ils vides sans Flatten ?
Ces mesures ont utilisé une imprimante simulée. Sur Windows, IronPrint envoie chaque travail à travers l'appel PrintDocument de la boîte de dialogue d'impression WPF. Un hook sur cet appel a enregistré les pages et le ticket d'impression de chaque travail dans un fichier XPS, et aucune file d'impression n'a reçu de travail. Les quatre formulaires de transfert l'ont traversé avec les paramètres de l'exemple combiné du guide de nivellement. Les résultats décrivent la page que IronPrint donne au pilote d'imprimante, pas du papier d'une imprimante physique.
La comparaison ci-dessous utilise le formulaire de transfert HO-1001, enregistré avec une valeur dans chaque champ.
- Avec
Flattenlaissé à sa valeur par défaut de faux, les cases Conducteur, Numéro de sceau, Nombre de palettes et Marchandises dangereuses étaient vides sur les quatre formulaires. Trois formulaires contenaient des flux d'apparence pour leurs champs, et les cases étaient vides sur ceux-là aussi. - Avec
Flatten = true, chaque valeur s'est imprimée. Le formulaire enregistré sans flux d'apparence a imprimé ses valeurs également. - Chaque page PDF est devenue une image de 2479 par 3508 pixels sur une page portrait ISO A4, qui est A4 à 300 DPI. Le formulaire à deux pages a produit deux pages.
- Le ticket d'impression a porté un nombre de copies de 2, tandis que le document contenait une page par page PDF.
- Les marges de 10 mm de l'exemple n'ont pas déplacé l'image, qui remplissait la page depuis son coin supérieur gauche.
Sortie
HO-1001 est passé par le hook deux fois, d'abord avec Flatten faux puis avec Flatten vrai. Chaque PDF ci-dessous est l'image de page d'un travail capturé, non modifié et à sa taille d'origine.
HO-1001 avec Flatten faux, comme IronPrint a construit le travail, capturé à un fichier à la place d'une imprimante.
HO-1001 avec Flatten vrai, comme IronPrint a construit le travail, capturé à un fichier à la place d'une imprimante.
Le guide de nivellement attribue les champs vides aux pilotes d'imprimante qui ignorent les calques de formulaire. Dans la capture, les valeurs étaient déjà absentes de la page avant que tout pilote ne la reçoive.
Comment imprimer un dossier de formulaires sans envoyer de travail ?
Le travail par lots a besoin d'un essai à blanc afin qu'il puisse être testé sans une imprimante. L'essai à blanc enregistre les paramètres que chaque formulaire recevrait, et un réviseur peut comparer ce journal avec le profil d'impression.
Turn @src/Depot.PrintJob/Program.cs into the batch job that prints forms/inbox.
It accepts two options:
- --printer <name> picks the printer for every form.
- --dry-run writes the log and sends nothing.
The job runs in this order:
1. Exit with code 2 when the printer isn't installed, and list the installed ones on the console.
2. Read every PDF in forms/inbox in file name order.
3. Get each form's settings from HandoverPrinter.BuildSettings.
4. Append a line per form to out/print-log.csv, then print the form unless it's a dry run.
Paths are relative to the solution root.
The log is semicolon-delimited, with this header line:
Form;Printer;Flatten;Copies;PaperSize;Orientation;Dpi;Grayscale
Run the job twice with --dry-run.
Use --printer "Adobe PDF" the first time and --printer "Depot Laser 2" the second.
Show me both exit codes and the log.
Adobe PDF est une imprimante sur la machine de test. Utilisez un nom de votre propre liste d'imprimantes.
Que se passe-t-il lorsqu'un nom d'imprimante ne correspond pas ?
IronPrint compare PrinterName avec les noms que Windows signale, caractère par caractère, et ne génère aucune erreur lorsque la comparaison échoue. Les travaux capturés ont été adressés à "NoSuchPrinter 7", à un "adobe pdf" en minuscules et à "Adobe PDF" suivi d'un espace. Microsoft Print to PDF, l'imprimante par défaut de Windows, a reçu les trois, et seul le nom exact est allé à Adobe PDF. Un travail sous licence au nom inconnu n'a soulevé aucune exception et n'est revenu qu'après que la boîte de dialogue Enregistrer sous de Microsoft Print to PDF ait été répondue.
GetPrinterTrays ne peut pas remplacer le contrôle du nom, car il a renvoyé une liste vide pour le nom inconnu et aussi pour Fax et Microsoft Print to PDF. GetPrinterNames a renvoyé les quatre imprimantes sans clé de licence, donc le contrôle fonctionne également dans les tests qui s'exécutent sans clé.
Comment tester les paramètres d'impression ?
Appuyez sur Shift+Tab dans Copilot CLI jusqu'à ce que le mode plan soit actif, puis envoyez l'instruction ci-dessous.
Plan an xUnit project in tests/Depot.Printing.Tests and add it to the solution.
Hold off on code until I approve the plan.
Its tests cover these cases:
- Every setting BuildSettings fills in matches @docs/print-profile.md.
- PaperMargins and Tray stay null, so the printer's own defaults apply.
- PrintAsync refuses a name with the wrong case or a trailing space.
- That refusal names every printer InstalledPrinters() returns.
Once the plan is approved, add the tests and run dotnet test.
Then give me the pass and fail counts.
Revoir le plan en premier montre comment la suite obtiendra un vrai nom d'imprimante avant que tout test ne dépende de la liste des imprimantes de la machine.
Comment réparer une réimpression qui laisse les champs des formulaires vides ?
Un chemin de réimpression écrit en dehors du service principal peut omettre un paramètre que le service principal applique. Dans ce scénario, le ReprintService d'un collègue construit son propre PrintSettings sans Flatten, et les pilotes reçoivent des réimpressions avec des cases vides.
Drivers say reprinted handover forms have empty Driver, Seal number and Pallet count boxes.
First prints look right. The reprint code is @src/Depot.Printing/ReprintService.cs.
Work out the cause before you edit anything:
1. Compare ReprintService.BuildSettings with HandoverPrinter.BuildSettings.
2. Open IronPrint.xml inside the IronPrint package in the NuGet cache.
3. Quote its summary for the setting that explains the empty boxes.
Then fix ReprintService.cs, and keep a reprint at one copy.
Leave the other source files alone.
Add a test for the reprint settings and run dotnet test.
Tell me the cause you found and the test result.
Le IronPrint.xml expédié connecte le paramètre au symptôme en une phrase, qui décrit Flatten comme utile pour afficher les valeurs des champs de formulaire. Il ne déclare pas que les valeurs sont absentes sans cela.
Qu'est-ce qui rend un problème sur lequel l'agent cloud peut agir ?
Copilot reçoit le titre du problème, la description et les commentaires existants lorsque le problème est assigné, ainsi que tout texte dans le champ d'instruction facultatif. La documentation de GitHub indique que l'agent n'est pas au courant des commentaires publiés après l'assignation, donc le corps du problème doit indiquer quand le travail est terminé.
Title: Log the printer each reprint was sent to
The work involves these files and settings:
- Files: src/Depot.Printing/ReprintService.cs, tests/Depot.Printing.Tests
- IronPrint version: unchanged from Directory.Packages.props
- Framework: net9.0-windows
After the change, reprints behave like this:
- Every reprint appends a line to out/reprint-log.csv.
- The line holds the form, the printer name, the time and the copy count.
- A printer name that Windows does not report stops the reprint before anything is sent.
Today, reprints leave no record, and ReprintAsync sends a job to any name it receives.
Keep to these limits:
- Keep the ReprintAsync signature.
- Follow .github/instructions/printing.instructions.md.
- Add no packages.
Acceptance means these checks pass:
- Every existing test passes.
- A new test passes "adobe pdf" in lower case and expects an ArgumentException before any job.
Parce que le test utilise un nom qui diffère de l'imprimante installée uniquement par la casse, un contrôle qui ignore la casse le rate.
Pourquoi les tests de l'agent cloud échouent-ils sur un projet IronPrint ?
À moins que le dépôt ne configure un autre exécuteur, l'environnement de l'agent est Ubuntu Linux. La page produit d'IronPrint nomme Windows, macOS, iOS et Android et ne nomme pas Linux, et chaque projet dans cette solution cible net9.0-windows. GitHub prend en charge les exécuteurs Windows 64 bits pour l'agent cloud. Son pare-feu intégré n'est pas compatible avec Windows, donc GitHub recommande des exécuteurs auto-hébergés ou des exécuteurs GitHub plus grands avec un réseau privé Azure pour ce cas.
Sans secret d'agents, cet environnement ne contient pas non plus de clé de licence. Dans la sonde, chaque appel d'impression sans licence a lancé "Licence de production requise" dans les 0,2 secondes, avant qu'aucun travail ne soit créé.
Le travail copilot-setup-steps dans .github/workflows/copilot-setup-steps.yml s'exécute avant que l'agent ne commence à travailler, et GitHub ne le déclenche qu'après que la branche par défaut contienne le fichier.
The cloud agent has to build this solution, so add a setup workflow for it.
Its path is .github/workflows/copilot-setup-steps.yml.
Copilot looks for one job, and it has to be named copilot-setup-steps.
The job works like this:
- Run it on windows-latest, because every project targets net9.0-windows.
- Its only permission is contents: read.
- Start it from workflow_dispatch and from pull requests that edit this workflow file.
- Its steps are a checkout, a .NET 9 SDK install, a restore and a Release build.
Printing calls need IRONPRINT_LICENSE_KEY, which is stored as an Agents secret.
The job sees that secret as an environment variable.
Add a step that tests whether the key is set:
- For pull_request and workflow_dispatch events, a missing key is a warning and the step passes.
- For every other event, a missing key fails the step with a message that names the secret.
That step goes last, since Copilot skips every setup step after one that fails.
Create the file and show me the YAML.
Utilisez un secret Agents pour la clé : l'agent cloud ne peut pas lire les secrets des Actions, des Codespaces ou de Dependabot. Ajoutez IRONPRINT_LICENSE_KEY sur la page Agents de Secrets et variables, disponible dans le groupe Sécurité des paramètres du dépôt. L'agent obtient alors la clé en tant que variable d'environnement.
Que faut-il vérifier avant de fusionner ?
Envoyez la révision comme sa propre commande copilot -p. Sans --continue ou --resume, cette commande commence une nouvelle session sans historique de la session de codage.
/review the changes made since this branch's first commit.
Compare each IronPrint call with .github/instructions/printing.instructions.md.
Then compare it with the IronPrint.xml that ships in the IronPrint NuGet package.
Name every place where the code and those two sources disagree.
Flag any of these as well:
- a PrintSettings for a handover form that leaves Flatten unset or false
- a print call whose printer name was never checked against Printer.GetPrinterNames
- a test that sends a real print job
- a catch block that would miss the LicensingException a print call throws
- any line that writes IRONPRINT_LICENSE_KEY to the console or a log
Report what you find and leave every file unchanged.
Qu'est-ce que les messages ont produit lors d'une réelle exécution ?
Les six instructions étaient programmées pour s'exécuter l'une après l'autre dans Copilot CLI, sans personne au clavier, sur une solution de dépôt construite pour ce guide. Après chaque instruction, le commit était reconstruit et le travail par lots exécuté dessus. Les paramètres pour chaque formulaire sont alors passés par IronPrint avec l'appel d'impression intercepté, donc aucun travail n'a atteint une imprimante.
- Avant l'exécution, HandoverPrinter était une classe statique vide et le travail par lots était une ébauche qui se terminait avec le code 1.
- La première instruction a changé seulement HandoverPrinter.cs.
- Après la première instruction, BuildSettings retournait Flatten activé, 2 copies, A4, portrait, 300 DPI et en niveaux de gris.
- Plateau et marges sont restés non définis, donc les paramètres par défaut de l'imprimante s'appliquaient.
- PrintAsync a vérifié le nom de l'imprimante avec une comparaison ordinale, qui est sensible à la casse.
- Chaque valeur de champ est apparue sur les pages capturées des quatre formulaires.
- Le ticket d'impression pour chaque formulaire comportait 2 copies, sortie en portrait ISO A4, monochrome et 300 DPI.
- Le travail capturé pour le formulaire à deux pages comportait deux pages, et chaque autre travail en comportait une.
- La solution a été construite avec 0 erreurs après chacune des deux instructions.
- Après la deuxième instruction, l'essai à blanc pour Adobe PDF s'est terminé avec le code 0 et a journalisé une ligne par formulaire.
- Chaque ligne journalisée correspondait au profil d'impression, avec Flatten et Niveaux de gris tous deux à Vrai.
- L'essai à blanc pour Depot Laser 2 s'est terminé avec le code 2, et sa sortie console a nommé les quatre imprimantes installées.
- Aucun essai à blanc n'a effectué d'appel d'impression.
- Aucun travail d'impression n'est apparu sur aucune file pendant l'exécution.
- Certaines étapes ont été exécutées différemment de la page. Le quota mensuel de Copilot s'est épuisé dans la deuxième instruction, après que Copilot ait construit le travail et avant ses essais à blanc. Les deux essais à blanc ont donc été exécutés en dehors de Copilot. Les instructions 3 à 6 n'ont pas été exécutées, donc le mode plan, la correction de la réimpression, le flux de configuration et la révision n'ont pas de résultats d'exécution sur cette page. Le problème, l'agent cloud et le secret des Agents nécessitent un dépôt hébergé, donc aucun d'eux n'a été testé.
Cursor encadre également ses règles par rapport aux motifs de fichiers, et Claude Code attend également un plan approuvé avant toute modification de code. Le journal d'exécution partagé contient la version du CLI, le modèle choisi par Auto, le temps total d'exécution et le matériel.
Dépannage
- Comment niveler les PDF avant l'impression pour les champs de formulaires qui s'impriment vides
- Comment obtenir les noms d'imprimantes pour les noms signalés par Windows
- Comment spécifier le nom de l'imprimante pour les travaux qui atteignent la mauvaise imprimante
- La méthode Print() se bloque dans WPF et WinForms pour un appel d'impression qui fige l'interface
- Application des clés de licence pour chaque endroit où la clé peut être définie
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.