Wie Sie IronPrint mit GitHub Copilot verwenden

Curtis Chau
Curtis Chau
Aktualisiert: 26. Oktober 2026

Ein Güterdepot druckt ein Übergabeformular für jeden Anhänger, der seine Laderampen verlässt. Das Webportal des Depots speichert jedes Formular als ausgefülltes PDF mit Feldern für den Fahrer, die Siegelnummer, die Palettenzahl und Gefahrgut, und ein .NET-Dienst in einer Visual Studio-Lösung druckt zwei Kopien von jedem. Ein Assistent, der den Dienst bearbeitet, muss innerhalb dieser Lösung arbeiten, im Editor, den das Team bereits verwendet.

GitHub Copilot bietet Chat- und Agent-Mode in Visual Studio und VS Code, Copilot CLI für das Terminal und einen GitHub-Cloud-Agent, der ein zugewiesenes Problem mit einem Pull-Request beantwortet. IronPrint sendet PDFs und Bilder von .NET an einen Drucker, wobei Papiergröße, Kopien, Auflösung und Formularverflachung auf einem einzigen PrintSettings Objekt gesetzt werden. Jede dieser Copilot-Oberflächen liest die IronPrint-Regeln aus Anleitungsdateien im Repository.

Die untenstehenden Eingabeaufforderungen bitten Copilot um Druckcode, der auf IronPrint aufgebaut ist. Die Auswahl von Druckerhardware oder das Konfigurieren eines Druckservers ist eine separate Aufgabe, die kein Assistent aus dem Repository übernehmen kann. Der Verflachungsleitfaden beschreibt die IronPrint-Einstellung, auf die sich diese Formulare stützen.

Schnellstart
NuGetMit NuGet installieren

PM > Install-Package IronPrint

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

Starten Sie copilot aus dem Lösungsordner und senden Sie die Eingabeaufforderung. In der CLI hängt @ vor einem Pfad diese Datei an. In Visual Studio verwendet Copilot Chat # für denselben Zweck.

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

Die Eingabeaufforderung benennt keine individuelle Einstellung. Das Druckprofil in docs/print-profile.md listet jede einzelne auf, und Flatten ist darunter.

Der Lizenzschlüssel geht in IRONPRINT_LICENSE_KEY, festgelegt in der Umgebung, in der Copilot läuft. IronPrint selbst liest diese Variable nicht. In unserem Test blieb License.IsLicensed mit eingestellter Variable auf false, bis das Programm seinen Wert License.LicenseKey zuwies. Andere unterstützte Stellen für den Schlüssel sind im Lizenzschlüssel-Leitfaden aufgeführt.



Wie setzen Sie IronPrint-Konventionen für Copilot?

Projektweite Regeln gehören in .github/copilot-instructions.md. GitHubs Support-Matrix zeigt Unterstützung für diese Datei in Copilot Chat auf Visual Studio, VS Code und JetBrains IDEs sowie für Copilot CLI, Copilot-Codeüberprüfung und den Cloud-Agent. Visual Studio fügt die Datei nur dann zu Copilot Chat-Anfragen hinzu, wenn das Kontrollkästchen für benutzerdefinierte Anweisungen aktiviert ist, unter GitHub, Copilot, Copilot Chat in den Optionen.

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

Die letzte Druckregel stammt von der Testmaschine. Dort fragt Microsoft Print to PDF nach einem Dateinamen und Adobe PDF öffnete ein Create Adobe PDF-Fenster, sodass ein an einen dieser Drucker gesendeter Auftrag auf eine Antwort einer Person wartet.

Wie geben Sie dem Druckcode eigene Regeln?

Die applyTo Muster von .github/instructions/printing.instructions.md beschränken seine Regeln auf einen Teil des Baums, in diesem Fall die Quell- und Testprojekte. GitHubs CLI-Dokumentation besagt, dass die CLI eine pfadspezifische Datei nur dann in ihren Kontext hinzufügt, wenn an einer Datei gearbeitet wird, die dem applyTo Wert entspricht. In unserem Durchlauf war printing.instructions.md die erste Datei, die Copilot in Eingabeaufforderung 1 öffnete.

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

Jede dieser Regeln wurde mit IronPrint 2026.10.1 gemessen. Die Flatten- und Druckernamensabschnitte unten geben die Messungen hinter der ersten von ihnen an.

Warum drucken Formularfelder leer ohne Flatten?

Diese Messungen verwendeten einen simulierten Drucker. Unter Windows sendet IronPrint jeden Auftrag über den PrintDocument Aufruf des WPF-Druckdialogs. Ein Hook bei diesem Aufruf speicherte die Seiten und das Druckticket jedes Auftrags in einer XPS-Datei, und keine Druckwarteschlange erhielt einen Auftrag. Die vier Übergabeformulare durchliefen es mit den Einstellungen aus dem kombinierten Beispiel der Verflachungsanleitung. Die Ergebnisse beschreiben die Seite, die IronPrint dem Druckertreiber liefert, nicht Papier aus einem physischen Drucker.

Der untenstehende Vergleich verwendet das Übergabeformular HO-1001, gespeichert mit einem Wert in jedem Feld.

  • Mit Flatten auf seinem Standardwert von false blieben Fahrer, Siegelnummer, Palettenanzahl und Gefahrgutkästchen auf allen vier Formularen leer. Drei Formulare trugen Erscheinungsströme für ihre Felder, und die Kästchen waren auch auf diesen leer.
  • Mit Flatten = true wurde jeder Wert gedruckt. Das Formular, das ohne Erscheinungsströme gespeichert wurde, druckte seine Werte ebenfalls.
  • Jede PDF-Seite wurde zu einem Bild von 2479 x 3508 Pixeln auf einer ISO A4 Hochformatseite, das A4 bei 300 DPI entspricht. Das zweiseitige Formular ergab zwei Seiten.
  • Das Druckticket führte eine Kopienanzahl von 2 an, während das Dokument eine Seite pro PDF-Seite enthielt.
  • Die 10 mm Ränder aus dem Beispiel verschoben das Bild nicht, das die Seite von ihrer oberen linken Ecke aus füllte.

Ausgabe

HO-1001 durchlief den Hook zweimal, zuerst mit Flatten false und dann mit Flatten true. Jedes untenstehende PDF ist das Seitenbild eines erfassten Auftrags, unverändert und in seiner Originalgröße.

HO-1001 mit Flatten false, wie IronPrint den Auftrag erstellte, in eine Datei anstelle eines Druckers erfasst.

HO-1001 mit Flatten true, wie IronPrint den Auftrag erstellte, in eine Datei anstelle eines Druckers erfasst.

Der Verflachungsleitfaden schreibt leere Felder Druckertreibern zu, die Formulartaschen überspringen. In der Erfassung fehlten die Werte bereits auf der Seite, bevor ein Treiber sie erhielt.

Wie drucken Sie einen Ordner voller Formulare, ohne einen Auftrag zu senden?

Der Batchauftrag benötigt einen Probelauf, damit er ohne Drucker getestet werden kann. Der Probelauf zeichnet die Einstellungen auf, die jedes Formular erhalten würde, und ein Prüfer kann dieses Protokoll mit dem Druckprofil vergleichen.

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

Adobe PDF ist ein Drucker auf der Testmaschine. Verwenden Sie einen Namen aus Ihrer eigenen Druckerliste.

Was passiert, wenn ein Druckername nicht übereinstimmt?

IronPrint vergleicht PrinterName mit den Namen, die Windows meldet, Zeichen für Zeichen, und löst keinen Fehler aus, wenn der Vergleich fehlschlägt. Erfasste Aufträge wurden an "NoSuchPrinter 7", an ein Kleinschreibungs-"adobe pdf" und an "Adobe PDF" gefolgt von einem Leerzeichen adressiert. Microsoft Print to PDF, der Standarddrucker von Windows, erhielt alle drei, und nur der genaue Name ging an Adobe PDF. Ein lizenzierter Auftrag an den unbekannten Namen führte zu keiner Ausnahme und kehrte erst zurück, nachdem der Speichern-unter-Dialog von Microsoft Print to PDF beantwortet wurde.

GetPrinterTrays kann die Namensprüfung nicht ersetzen, da es eine leere Liste für den unbekannten Namen und auch für Fax und Microsoft Print to PDF zurückgab. GetPrinterNames gab alle vier Drucker ohne Lizenzschlüssel zurück, daher funktioniert die Überprüfung auch in Tests, die ohne einen laufen.

Wie testen Sie die Druckereinstellungen?

Drücken Sie Shift+Tab in Copilot CLI, bis der Planmodus aktiv ist, und senden Sie dann die untenstehende Eingabeaufforderung.

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

Die Überprüfung des Plans zeigt zuerst, wie die Suite einen echten Druckernamen ermitteln wird, bevor ein Test von der Druckerliste der Maschine abhängt.

Wie beheben Sie einen Nachdruck, der die Formularfelder leer lässt?

Ein außerhalb des Hauptdienstes geschriebener Nachdruckpfad kann eine Einstellung weglassen, die der Hauptdienst anwendet. In diesem Szenario baut der ReprintService eines Teamkollegen sein eigenes PrintSettings ohne Flatten, und Treiber erhalten Nachdrucke mit leeren Kästchen.

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

Das gelieferte IronPrint.xml verbindet die Einstellung mit dem Symptom in einem Satz, derFlatten als nützlich zur Anzeige von Formularfeldwerten beschreibt. Es wird nicht angegeben, dass die Werte ohne es fehlen.

Was macht ein Problem aus, auf das der Cloud-Agent reagieren kann?

Copilot erhält den Titel des Problems, die Beschreibung und bestehende Kommentare, wenn das Problem zugewiesen wird, zusammen mit jedem Text im optionalen Eingabefeld. GitHubs Dokumentation besagt, dass der Agent sich der nach der Zuweisung geposteten Kommentare nicht bewusst ist, sodass der Issue-Text angeben muss, wann die Arbeit abgeschlossen ist.

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

Da der Test einen Namen verwendet, der sich nur durch Groß- und Kleinschreibung vom installierten Drucker unterscheidet, schlägt eine Prüfung, die Groß- und Kleinschreibung ignoriert, fehl.

Warum schlagen die Tests des Cloud-Agent auf einem IronPrint-Projekt fehl?

Es sei denn, das Repository konfiguriert einen anderen Runner, ist die Umgebung des Agents Ubuntu Linux. Die Produktseite von IronPrint nennt Windows, macOS, iOS und Android und nennt nicht Linux, und jedes Projekt in dieser Lösung zielt auf net9.0-windows. GitHub unterstützt Windows 64-Bit-Runner für den Cloud-Agent. Die integrierte Firewall ist nicht mit Windows kompatibel, daher empfiehlt GitHub selbstgehostete Runner oder größere von GitHub gehostete Runner mit privatem Netzwerk von Azure für diesen Fall.

Ohne ein Agents-Geheimnis enthält diese Umgebung auch keinen Lizenzschlüssel. In der Sonde warf jeder nicht lizenzierte Druckaufruf "Production License Required" innerhalb von 0,2 Sekunden, bevor irgendein Auftrag erstellt wurde.

Der copilot-setup-steps Auftrag in .github/workflows/copilot-setup-steps.yml läuft, bevor der Agent mit der Arbeit beginnt, und GitHub löst ihn erst aus, nachdem der Standard-Zweig die Datei enthält.

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

Verwenden Sie ein Agents-Geheimnis für den Schlüssel: der Cloud-Agent kann keine Actions-, Codespaces- oder Dependabot-Geheimnisse lesen. Fügen Sie IRONPRINT_LICENSE_KEY auf der Agenten-Seite von Geheimnissen und Variablen hinzu, die sich in der Sicherheitsgruppe der Repository-Einstellungen befindet. Der Agent erhält dann den Schlüssel als Umgebungsvariable.

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

Senden Sie die Überprüfung als eigenen copilot -p Befehl. Ohne --continue oder --resume startet dieser Befehl eine neue Sitzung ohne Verlauf aus der Codierungssitzung.

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

Was haben die Aufforderungen in einem realen Lauf erzeugt?

Die sechs Eingabeaufforderungen waren so geplant, dass sie nacheinander im Copilot CLI laufen, ohne dass eine Person an der Tastatur ist, auf einer Depotlösung, die für diesen Leitfaden erstellt wurde. Nach jeder Eingabeaufforderung wurde der Commit neu aufgebaut und der Batchauftrag darauf ausgeführt. Die Einstellungen für jedes Formular wurden dann durch IronPrint geleitet, mit dem abgefangenen Druckaufruf, sodass kein Auftrag einen Drucker erreichte.

  • Vor dem Lauf war HandoverPrinter eine leere statische Klasse und der Batchauftrag ein Platzhalter, der mit Code 1 beendet wurde.
  • Die erste Eingabeaufforderung änderte nur HandoverPrinter.cs.
  • Nach der ersten Eingabeaufforderung gab BuildSettings Flatten an, 2 Kopien, A4, Hochformat, 300 DPI und Graustufen zurück.
  • Fach und Ränder blieben ungesetzt, sodass die Druckerstandards angewendet wurden.
  • PrintAsync überprüfte den Druckernamen mit einem ordinalen Vergleich, der Groß- und Kleinschreibung berücksichtigt.
  • Jeder Feldwert erschien auf den erfassten Seiten aller vier Formulare.
  • Das Druckticket für jedes Formular führte 2 Kopien, ISO A4 Hochformat, monochrome Ausgabe und 300 DPI an.
  • Der erfasste Auftrag für das zweiseitige Formular enthielt zwei Seiten, und jeder andere Auftrag hielt eine.
  • Die Lösung wurde nach jeder der beiden Eingabeaufforderungen mit 0 Fehlern aufgebaut.
  • Nach der zweiten Eingabeaufforderung endete der Probelauf für Adobe PDF mit Code 0 und protokollierte eine Zeile pro Formular.
  • Jede protokollierte Zeile entsprach dem Druckprofil, mit Flatten und Graustufen beide True.
  • Der Probelauf für Depot Laser 2 endete mit Code 2, und seine Konsolenausgabe nannte die vier installierten Drucker.
  • Kein Probelauf machte einen Druckaufruf.
  • Kein Druckauftrag erschien während des Laufs in einer Warteschlange.
  • Einige Schritte liefen anders als die Seite. Das monatliche Copilot-Kontingent war in der zweiten Eingabeaufforderung verbraucht, nachdem Copilot den Auftrag erstellt hatte und vor seinen Probeläufen. Beide Probeläufe wurden stattdessen außerhalb von Copilot ausgeführt. Die Eingabeaufforderungen 3 bis 6 liefen nicht, daher haben der Planmodus, der Nachdruckfix, der Einrichtungs-Workflow und die Überprüfung keine Ergebnisse auf dieser Seite. Das Issue, der Cloud-Agent und das Agents-Geheimnis erfordern ein gehostetes Repository, daher wurde keiner von ihnen getestet.

Cursor begrenzt seine Regeln ebenfalls auf Dateimuster, und Claude Code wartet gleichermaßen auf einen genehmigten Plan, bevor irgendwelche Codeänderungen vorgenommen werden. Der gemeinsame Laufdatensatz enthält die CLI-Version, das automatisch gewählte Modell, die Gesamtlaufzeit und die Hardware.


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 52,106Version:2026.11gerade veröffentlicht