Jak używać IronPDF z GitHub Copilot

Curtis Chau
Curtis Chau
Zaktualizowano: 26 października 2026

Większość poradników dotyczących kodowania wspomaganego sztuczną inteligencją zakłada, że jesteś gotów zmienić edytory. Dla pracy z .NET często jest to błędne założenie. Projekty IronPDF w Visual Studio znajdują się w rozwiązaniach z referencjami projektów, konfiguracją NuGet i potokiem build, którego nikt nie chce przenosić, aby wypróbować asystenta.

GitHub Copilot działa tam, gdzie te projekty już są, w Visual Studio, VS Code i JetBrains IDE, więc ten przepływ pracy nie wymaga migracji. Robi też coś, czego żaden asystent jedynie dla edytora nie potrafi: działa wewnątrz samego GitHub. Można opisać problem z PDF w zgłoszeniu, przypisać go do agenta chmurowego Copilot i otrzymać żądanie ściągnięcia. IronPDF renderuje HTML, CSS i JavaScript do PDF przez osadzony silnik Chromium, i nie ma integracji między tymi dwoma produktami. Łączą je repozytorium i konwencje, które do niego wprowadzić.

Na początek jedno rozróżnienie, ponieważ konkurują dwa podobne tematy. Ten przewodnik dotyczy używania asystenta kodowania AI do tworzenia oprogramowania z IronPDF. Nie dotyczy używania modeli AI do odczytu lub analizy treści PDF, co oddzielnie omawia poradnik przetwarzania PDF z wykorzystaniem AI.

Szybki start
NuGetInstalacja z NuGet

PM > Install-Package IronPdf

Zainstaluj IronPDF, 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 IDE, w którym już istnieje, i poprosić o dokument:

In this C# console project, create Program.cs that uses IronPDF to render
"<h1>Hello from IronPDF</h1>" to hello.pdf. Read the license key from the
IRONPDF_LICENSE_KEY environment variable, never inline. Then build and fix
any errors.
Text

Copilot pisze garść linii, które mają znaczenie, konstruuje ChromePdfRenderer, wywołuje RenderHtmlAsPdf i zapisuje wynik przy użyciu SaveAs. Ta część jest nieistotna, i nie dlatego ten przewodnik istnieje. Co następuje, jest istotne: ten sam asystent wykona tę pracę bez obserwacji, na gałęzi, jako pull request, co zmienia to, co musisz skonfigurować.

Dwa krótkie uwagi bezpieczeństwa. Klucz licencyjny nigdy nie należy do wstawki czy commitu; znajduje się w konfiguracji, jak opisano w przewodniku dotyczącym klucza licencyjnego, lub w zmiennej środowiskowej bądź w tajemnicy repozytorium. A agent z możliwością zapisu do repozytorium otwiera prawdziwe pull requesty, więc ochrona gałęzi i ludzka weryfikacja pozostają kluczową kontrolą.



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

Copilot działa na trzech zakresach, a wybór właściwego oszczędza więcej czasu niż jakakolwiek technika wstawiania.

Wstawienia i czat obsługują wszystko, co można opisać jednym zdaniem i znajduje się w pojedynczym pliku: dostosowanie marginesu, dodanie stopki do istniejącego wywołania renderer'a, zmiana nazwy pomocnika. Opisujesz zmianę, dostajesz różnicę na miejscu, akceptujesz lub nie.

Tryb agenta obsługuje pracę rozciągającą się na kilka plików, gdzie Copilot decyduje, które pliki edytować, uruchamia polecenia terminala, odczytuje wyjście i iteruje na błędach. To właściwy zakres dla migracji lub refaktoryzacji.

Agent chmurowy na GitHubie obsługuje pracę, która nie wymaga nadzoru. Przypisać zadanie, planuje, przesyła gałąź i otwiera pull request. To odróżnia Copilot od asystenta ograniczonego do edytora i na tym skupia się reszta tego przewodnika.

Copilot jest także rozsądnym czytelnikiem. Prośba o wyjaśnienie typu opcji renderowania i listę, które projekt obecnie ustawia, zamienia dokumentację API w coś, co można zapytać, a nie przewijać.

Uwaga: Trzy zakresy mają różne obszary oddziaływania. Edycja in-line jest przeglądana przed wprowadzeniem, tryb agenta jest przeglądany jako diff, a praca agenta chmurowego przychodzi jako żądanie ściągnięcia, które może czekać jeden dzień, zanim ktoś je przeczyta. Dopasuj zakres do tego, ile chcesz mieć w rękach, kiedy skończy.

Jak zatwierdzasz konwencje, które każde powierzchnia przestrzega?

Niestandardowe instrukcje repozytorium są zatwierdzane w repozytorium, co oznacza, że zarządzają czatem IDE i autonomicznym agentem, również wtedy, gdy agent pracuje bez nadzoru. Napisz je raz, potem przestań się powtarzać w podpowiedziach.

Plik to .github/copilot-instructions.md. Dla zespołu .NET to format, który wart jest standaryzacji, ponieważ jest to ten, który Visual Studio dokumentuje jako ładowanie, obok VS Code, JetBrains, agenta w chmurze i Copilot code review. Copilot czyta inne pliki instrukcji również, w tym AGENTS.md, ale wsparcie różni się w zależności od wersji, więc najbezpieczniejsze ustawienia domyślne dla Visual Studio to plik nazwany po produkcie.

# Copilot instructions

## PDF generation

- Use IronPDF for all PDF generation. Use ChromePdfRenderer for HTML conversion.
- Target the IronPDF version pinned in Directory.Packages.props. Do not upgrade
  it as part of an unrelated change.
- Never inline a license key. Read it from configuration or the
  IRONPDF_LICENSE_KEY environment variable.
- Prefer the shared PdfDocumentService helper over constructing a renderer per
  call. A ChromePdfRenderer instance is reusable.
- Use the async rendering methods in web request paths.
- Do not invent IronPDF API names. If a method is uncertain, say so and cite the
  documentation rather than guessing.

## Testing

- Assert on extracted text, page count and the %PDF- signature.
- Never use golden-file byte comparisons; rendering output is not byte-stable.
Text

Zasługuje na to zdanie o przyznaniu się do niepewności. Domyślem modelu jest produkcja czegoś o wiarygodnym kształcie, zamiast przyznania się do luki, a wymyślenie renderer.ConvertHtmlToPdfDocument() brzmi idealnie, dopóki kompilator się nie zgodzi. Zezwolenie na zatrzymanie się jest tanie i skuteczne.

Instrukcje specyficzne dla ścieżki w .github/instructions/**/*.instructions.md ukierunkowują wytyczne na pasujące pliki, co utrzymuje konwencje PDF poza zgłoszeniami niezwiązanymi z PDF-ami.

Co sprawia, że agent może faktycznie zadziałać na zgłoszenie?

Tutaj ważna umiejętność to nie pisanie podpowiedzi. To pisanie problemu, poniewaz wedlug GitHub, agent pracuje z tytulu problemu, opis, i istniejace komentarze, i nie widzi komentarzy dodanych po przypisaniu. Nikogo nie ma, aby to wyjaśnić.

Słabe zgłoszenie wygląda tak:

Title: PDF looks wrong

The invoice PDF doesn't look right. Can we fix the layout?
Text

Agent nie ma pliku do otwarcia, nie wie, który z kilku plików PDF jest zamierzony, brak opisu poprawnego wyniku i brak błędu do analizy. Będzie eksplorować, zgadywać i produkować prośbę o zmianę, która może całkowicie dotyczyć niewłaściwej rzeczy.

Silne zgłoszenie posiada wszystko, czego potrzebowałby kolega:

Title: Invoice PDF splits table rows across pages and drops the logo

**Files:** Services/InvoiceRenderer.cs, Templates/invoice.html
**IronPDF version:** as pinned in Directory.Packages.props
**Framework:** .NET 8

**Expected:** A4 portrait, 20mm margins. Line-item table rows stay intact
across page breaks. Company logo renders in the header.

**Actual:** A table row splits between pages 1 and 2. The logo area is blank
in the PDF but renders correctly when Templates/invoice.html is opened in
Chrome. No exception is thrown.

**Constraints:** Fix page-break behavior in CSS, not in C#. Keep the public
signature of InvoiceRenderer.RenderAsync unchanged. No new packages.

**Acceptance:** Existing tests pass, plus a new test asserting page count for
the fixture in TestData/invoice-12-items.json.
Text

Sześć rzeczy różnicuje drugie od pierwszego: nazwane pliki, wersja frameworku i biblioteki, oczekiwany wynik opisany konkretnie, rzeczywiste zachowanie w tym, co się nie dzieje, twarde ograniczenia i definicja ukończenia.

Szczegół o tym, że nie zostało wyrzucone żadne wyjątkiem, odgrywa tu realną rolę. Mówi agentowi, że to problem renderowania, a nie awarii, co wyklucza całą kategorię badań jeszcze przed rozpoczęciem. Obserwacja, że logo jest renderowane w Chrome, ale nie w PDF, dalej zawęża problem: surowy łańcuch HTML nie niesie lokacji dokumentu, więc względne ścieżki obrazu rozwiązują się względem katalogu roboczego procesu zamiast folderu szablonu, podczas gdy przeglądarka wie, skąd przyszła strona.

Po przypisaniu, agent planuje, przesyła gałąź, otwiera pull request i prosi o recenzję. Przeglądać różnicę, a nie oglądać pracy.

Dlaczego testy agenta nie działają na projekcie IronPDF?

To sekcja, której nie napisze żaden ogólny przewodnik Copilot i jedyna, która najprawdopodobniej zaoszczędzi Ci popołudnie.

Agent w chmurze buduje i testuje we wlasnym efemerycznym srodowisku. Dla większości projektów źródło plus przywracanie pakietu wystarczy. Projekt IronPDF potrzebuje więcej, ponieważ renderowanie zależy od silnika Chromium z zależnościami natywnymi dla platformy. Jeśli te są nieobecne w linuxowym runnerze agenta, każdy test, który renderuje PDF, nie powodzi się, z powodów niezwiązanych z kodem, który agent właśnie napisał.

Konsekwencja jest gorsza niż czerwony build. Pozostawione do samodzielnego znalezienia i zainstalowania brakujących zależności, agent działa metodą prób i błędów, co dokumentacja GitHub nazywa wolnym i zawodnym.

Rozwiazaniem jest wstepna konfiguracja srodowiska z .github/workflows/copilot-setup-steps.yml. Wygląda to jak zwykły przepływ pracy GitHub Actions z dwoma regułami, które łatwo przegapić: zadanie musi być nazwane copilot-setup-steps, a plik w ogóle się nie uruchomi, chyba że istnieje na domyślnej gałęzi repozytorium.

name: "Copilot Setup Steps"
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  # The job MUST be called `copilot-setup-steps` or Copilot will not pick it up.
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'
      # Install the native dependencies IronPDF's Chromium engine needs on
      # Debian-based images. Take the current package list from the Docker
      # and Linux deployment guide rather than copying one from anywhere else,
      # because it changes between releases.
      - name: Install IronPDF native dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y <packages from the IronPDF Linux guide>
      - run: dotnet restore
Text

Dwa szczegóły decydują, czy to działa.

Po pierwsze, klucz licencyjny nie jest automatycznie dostępny dla agenta. GitHub Actions, Codespaces i Dependabot secrets nie sa dostepne dla sesji agenta, wiec klucz musi zostac dodany osobno jako tajemnica agenta w ustawieniach repozytorium lub organizacji.

Po drugie, i to jest to, co wywołuje mylący objaw: jeśli krok konfiguracji się nie powiedzie, Copilot się nie zatrzymuje. Pomija pozostałe kroki i zaczyna pracować z tym, w jakim stanie jest środowisko. Cicha porażka instalacji zależności wygląda zatem dokładnie jak problem z kodem. Ręcznie uruchomić workflow z zakładki Akcje raz, zanim na nim polegnie.

Porady: Praktyczna reguła: gdy żądanie ściągnięcia agenta chmurowego zawiera nieudane testy renderowania w projekcie IronPDF, sprawdź Srodowisko zanim założysz, że zmiana jest błędna. Przewodnik wdrożenia Docker dokumentuje zależności, które zmieniają się między wydaniami i powinny być czytane zamiast zapamiętywane.

Co należy sprawdzić przed scaleniem?

Prośba o ściągnięcie to powierzchnia recenzji, i obowiązują te same standardy, co do jakiejkolwiek gałęzi kolegi. Przegląd kodu Copilot może być uruchomiony jako druga tura nad wynikiem agenta, co wychwytuje mechaniczne problemy, zanim człowiek zobaczy różnicę.

Trzy kontrole mają szczególne znaczenie dla zmian w IronPDF:

  1. Czy każda nazwa API pojawia się w dokumentacji, czy coś prawdopodobnego przeszło niezauważone?
  2. Czy wygenerowane PDF wygląda poprawnie? Czysta budowa nie mówi nic o układzie.
  3. Czy zmiana pozostała w granicach wyznaczonych przez problem?

Warto ustanowić standardowe żądanie testów w tej samej prośbie o ściągnięcie:

Add xUnit tests for this change: output is non-empty, begins with the %PDF-
signature, extracted text contains the bound company name, and page count
matches the fixture. No golden-file byte comparisons.
Text

Wykluczenie porównania bajtowego zapobiega klasie niestabilnych testów, które kosztowałyby popołudnie, ponieważ dwa rendery tego samego HTML w odrębnych procesach różnią się znacznikami czasów i ID dokumentów.

Kiedy to kod, a kiedy to kontener?

Trzy udokumentowane przyczyny różnic renderowania między przeglądarką a PDF to: arkusz stylów napisany dla mediów ekranowych zamiast drukowanych, font internetowy, który nie załadował się, gdy liczono układ, oraz treść wyprodukowana przez JavaScript, przechwycona zbyt wcześnie. Wszystkie trzy są po stronie kodu i wszystkie trzy warto wymienić w zgłoszeniu:

Templates/report.html renders correctly in Chrome but the PDF splits a table
row across pages and the totals block lands on the next page alone.

Explain the cause before changing anything, then fix it in the CSS using page
break properties. Do not modify ReportRenderer.cs.
Text

Poproszenie o diagnozę przed zmianą daje coś do oceny, a nie poprawkę do odwrotnego inżynieringu. Zachowanie łamania stron należy do arkusza stylów, a przewodnik po łamaniach stron obejmuje odpowiednie właściwości. Ograniczonej zmiany do CSS zapobiega agentowi rozwiązywania problemu z układem przez restrukturyzację C#.

Druga połowa pytania to ta, na którą odpowiedział poprzedni rozdział: kiedy ten sam kod renduje się lokalnie i nie powiedzie się w kontenerze lub na runnerze, zazwyczaj nie chodzi o kod. Wkleić pełen wyjątek zamiast go parafrazować i skierować żądanie na plik Dockerfile, a nie aplikację. Brakująca biblioteka współdzielona nie jest problemem C#.

Co wyprodukowały zapytania w rzeczywistym uruchomieniu?

Trzy wiersze i dwa ciała problemu na tej stronie działały zgodnie z kolejnością, bez nadzoru, z GitHub Copilot CLI 1.0.95, który przesłał każdy krok do GPT-6 Luna. Plik z instrukcjami i przepływ pracy kroków konfiguracji zostały zatwierdzone, jak napisano. Poniższe liczby pochodzą z niezależnych kontroli plików, które zostały po uruchomieniu.

  • Prompt startowy wyprodukował 13-linijek Program.cs, który czytał klucz z IRONPDF_LICENSE_KEY i kompilował bez błędów czy ostrzeżeń.
  • Agent nie uruchomił programu.
  • Uruchomiony z kluczem, program zapisał jednostronicowy hello.pdf o rozmiarze 17 385 bajtów.
  • Przed uruchomieniem problemów faktura podzieliła jeden element rachunku na strony 1 i 2 i nie zawierała obrazu.
  • Resny problem wyprodukował fakturę dwustronicową z każdym elementem rachunku w całości i logo na stronie 1.
  • Agent osadził logo jako URI danych w C# i poprawił przełamanie strony w CSS.
  • Publiczna sygnatura InvoiceRenderer.RenderAsync pozostała niezmieniona, nie dodano żadnego pakietu.
  • Nowy test potwierdzał dwie strony dla zestawu 12-elementów, i wszystkie 3 testy przeszły.
  • Agent dodał zasadę do powtórzenia nagłówka tabeli i zgłosił, że została powtórzona. Strona 2 renderowanej faktury nie miała wiersza nagłówka.
  • Slaby problem rowniez naprawil oba bledy, choc nie nazwal zadnego pliku ani konkretnego symtomu.
  • Ta sama zmiana przepisała cały arkusz stylów i zredukowała rozmiar tekstu głównego z 13 do 11 pikseli.
  • Prompt testów dodał niesEmpty check i check dla nazwy firmy do istniejących testów, więc liczba pozostała na 3, i żaden nie porównał bajtów.
  • Prompt raportu nazwał wymuszone przełamanie strony przed sumami i brakującą zasadę wiersza jako przyczyny przed edycją CSS.
  • Naprawiony raport zmiescil sie na 2 stronach zamiast 3, bez podzialonego wiersza i sumami ponizej ostatnich czterech pozycji. ReportRenderer.cs pozostalo niezmienione.
  • Agent nigdy nie wyświetlał zmiennych środowiskowych, a klucz nie pojawił się w żadnym transkrypcie, commitcie czy pliku sesji Copilot.
  • Niektóre kroki uruchomiono inaczej niż na stronie. Repozytorium nie miało zdalnego Gita na GitHub, więc CLI zastąpił agenta w chmurze, a każdy problem rozpoczynał nową sesję. Zadanie testów trafiło do sesji silnego problemu zamiast komentarza do pull request. Przepływ pracy kroków konfiguracji nie został wykonany, ponieważ ta maszyna nie ma runnera GitHub Actions ani środowiska Linux.

Faktura po silnym problemie, renderowana przez InvoiceRenderer uruchomienia z zestawu 12-elementów.

Raport po poprawie CSS z promptu raportu, renderowany przez ReportRenderer uruchomienia.

Wersja CLI Copilot, model i czas dla tego uruchomienia są wymienione w zapisie uruchomienia.

Co działa bez nadzoru?

Dwie rzeczy, i to te dwie warte skonfigurowania najpierw. Zatwierdzone instrukcje w .github/copilot-instructions.md zarządzają agentem na gałęzi dokładnie o północy tak, jak zarządzają swym IDE w południe. To copilot-setup-steps.yml, który instaluje natywne zależności IronPDF, chroni tego samego agenta przed znajdywaniem i instalowaniem ich metodą prób i błędów. Wszystko inne to zwykłe użycie asystenta, które działa lepiej, gdy te dwie rzeczy istnieją.

Nawyk weryfikacji nie zmienia się z zasięgiem: budować wcześnie, otworzyć PDF, i sprawdzić nazwy API w dokumentacji przed wysyłką czegokolwiek. Reprodukcyjna wersja tej kontroli, uruchomiona od początku do końca z opublikowanym wynikiem, znajduje się na przewodniku po asystentach kodujących AI, obok przewodników dla Claude Code, ChatGPT Codex i Cursor.


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 22,198,312Wersja:2026.11właśnie wydane