Jak używać IronPDF z Cursor

Curtis Chau
Curtis Chau
Zaktualizowano: 26 października 2026

Zaproponuj dowolnemu asystentowi AI napisanie kodu IronPDF, a wygeneruje on cos, co wyglada poprawnie. Czasami tak jest. Innym razem wywołuje metodę, która nigdy nie istniała, i dowiadujesz się o tym dopiero podczas budowania, a nie przeglądu. Model nie ulega awarii. Uzupelnia luke w swojej wiedzy czyms prawdopodobnym, co czyni go zarowno uzytecznym, jak i niebezpiecznym w rownym stopniu.

Cursor to edytor kodu zbudowany z podejsciem AI, oparty na VS Code, a jego najbardziej wartosciowa funkcja do pracy z bibliotekami nie jest okienko czatu. To umiejętność pobrania dokumentacji biblioteki z linku i zobowiązania zasad projektu do repozytorium, dzięki czemu edytor odpowiada prawdziwymi API IronPDF i przestrzega konwencji zespołu bez potrzeby ponownego informowania. IronPDF renderuje HTML, CSS i JavaScript do formatu PDF za pomocą wbudowanej maszyny Chromium. Żadne z narzędzi nie jest świadome istnienia drugiego i nie ma integracji do zainstalowania. Zamiast tego ustawiasz kontekst, a ta konfiguracja jest omawiana w pierwszej polowie tego przewodnika.

Jedna uwaga przed rozpoczęciem, ponieważ dwa podobne tematy są często mylone. Ten przewodnik dotyczy używania edytora AI do budowania oprogramowania z IronPDF. Nie dotyczy on używania modeli AI do odczytu lub analizy zawartości plików PDF, co omawia osobno samouczek przetwarzania PDF zasilany 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ć projekt C# w Cursor i zadawać pytania do dokumentacji IronPDF zamiast do pamięci modelu:

Read https://ironpdf.com/llms.txt and the pages it links to.

In this C# project, create Program.cs that renders "<h1>Hello from IronPDF</h1>"
to hello.pdf. Read the license key from the IRONPDF_LICENSE_KEY environment
variable. Use only methods that appear in the linked documentation.
Text

Cursor pisze kilka linijek, które mają znaczenie: skonstruować ChromePdfRenderer, wywołać RenderHtmlAsPdf na znacznikach i SaveAs rezultat na dysk. Link do dokumentacji w pierwszej linii to coś, co odróżnia to od tego samego żądania wpisanego w ogólnym oknie czatu, a skonfigurowanie tego jest pierwszym prawdziwym krokiem poniżej.

Krótka uwaga na temat bezpieczeństwa. Agent z dostępem do zapisu plików i terminala nigdy nie powinien otrzymać klucza licencyjnego w linii, więc należy go umieścić w zmiennej środowiskowej lub pliku konfiguracyjnym wykluczonym z kontroli wersji. Przewodnik po kluczach licencyjnych omawia wspierane opcje.



Co faktycznie działa za oknem czatu?

Cursor nie jest dostarczany z przypisanym jednym modelem. Ma wbudowany swoj wlasny, a także pozwala ustawić ten sam edytor na czyjsc inny.

Można przełączać się między nimi w jednej sesji.

Dla pracy z PDF ma to jeden praktyczny skutek, który warto zaplanować. Większość sesji dokumentu to tania, powtarzalna praca: dostosowanie marginesu, ponowna budowa, spojrzenie na wynik, ponowne dostosowanie. Sporadycznie tabelka przełamuje się na stronę z powodu, którego żaden kompilator nie wyjaśni, i to jest ten moment, by przejść do modelu, który myśli dłużej przed edycją. Spodziewaj się, że dokument również zmieni się wraz z wyborem. To samo zrealizowane z dwoma modelami prowadzi do dwóch układów różnicy w przestrzeniach i przełamaniach stron, zarazem kiedykolwiek wyraziłeś to wyraźnie, co jest argumentem za przypieczętowaniem ilości stron, tekstu nagłówka i formatu stopki, zamiast polegać na domysłach.

Uruchomić model Claude w Cursor, a obserwacje w przewodnik kodu Claude nadal obejmują jego wyjście, ponieważ model jest ten sam, choć co wizualne nie.

Jak przekazać dokumentację IronPDF Cursorowi, aby przestał zgadywać?

Cursor używał do indeksowania zewnętrznej dokumentacji za pomocą wzmianki @Docs. Jego notatki o wydaniu wersji 3.21 zapisują, że opcja Doksy „już przestała dodawać dokumentację do kontekstu agenta” i usunięto ją z menu @. To, co działa obecnie, to link. Agent Cursor ma narzędzie web, które pobiera URL wymieniony we wskazówce, a IronPDF publikuje llms.txt, indeks swoich stron dokumentacyjnych. Podczas próby z CLI Cursor, agent pobrał ten indeks, a następnie strony nagłówków i stopek, które on linkuje, zanim odpowiedział. Przekazanie dokumentacji IronPDF Cursorowi jest najważniejszym krokiem konfiguracji w tym przewodniku, ponieważ zastępuje przypominanie odzyskiwaniem.

Powod warto wyrazic jasno dla kazdego nowego w tym temacie. Model zapytany o konkretną bibliotekę opiera się na tym, co przyswoił podczas szkolenia, co może być już nieaktualne i nigdy nie zostało zweryfikowane w obecnej wersji. Link do dokumentacji daje edytorowi coś do obejrzenia. Różnica pojawia się natychmiast w nazwach metod: nieosadzony model wymyśla renderer.ConvertHtmlToPdfDocument(), i brzmi to dobrze, dopóki kompilator się nie sprzeciwia.

Link jest wstawiany jako jedna linia tekstu:

Use the IronPDF docs at https://ironpdf.com/llms.txt.

What are the options for adding a footer with page numbers to a rendered PDF?
Show the exact class and property names from the documentation, and link the
page you took them from.
Text

Prośba o źródłową stronę to tani nawyk weryfikacji.

Porady: To ponownie przynosi korzysci pozniej, przy nieznanych klasach. Poproś edytora o podsumowanie opcji renderowania i listę, które z nich projekt już ustawia, a dokumentacja API staje się narzędziem do zapytań zamiast przewijania.

Jak napisać zasady projektowe kodujące konwencje IronPDF?

Zasady projektowe Cursor są umieszczone w katalogu .cursor/rules w głównym folderze repozytorium i są kontrolowane wersjami, dzięki czemu są one zapisywane razem z kodem i każdy programista otrzymuje to samo zachowanie bez potrzeby konfiguracji.

Zasady to pliki .mdc: markdown z frontmatter YAML noszącymi description, globs, i alwaysApply. Cursor czyta je rekurencyjnie, wiec dzialaja katalogi podrzedne. Prosty plik .md w tym folderze jest ignorowany, ponieważ nie ma frontmattera do aktywacji. Zasada dla konwencji IronPDF wyglada tak:

---
description: IronPDF conventions for PDF generation in this project
globs: **/Services/**/*.cs, **/Pdf/**/*.cs
alwaysApply: false
---

# IronPDF conventions

- Use ChromePdfRenderer for all HTML-to-PDF 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 instead of guessing.
Text

Ta ostatnia linia robi więcej, niż się wydaje. Powiedzenie modelowi, że przyznawanie się do niepewności jest dopuszczalne, zmniejsza liczbę wynalezionych API, a umieszczenie jej w zatwierdzonej zasadzie sprawia, że przestajesz się powtarzać w każdym zapytaniu.

Linia globs to część warta celowego skopiowania. Wszystko oznaczone jako alwaysApply: true ładuje się do każdego żądania i zużywa budżet kontekstu, więc zakreślenie zasady IronPDF do ścieżek, gdzie rzeczywiście żyje kod PDF, utrzymuje ją z dala od żądań, które nie mają nic wspólnego z renderowaniem.

Uwaga: Cursor również czyta prosty plik AGENTS.md w głównym katalogu projektu, ten sam plik, który ChatGPT Codex i Google Antigravity czytają. Nie zawiera frontmattera, więc nie ma globów i zawsze się stosuje. Sięgnij po .cursor/rules, kiedy chcesz zakresu, i po AGENTS.md, kiedy chcesz jeden plik instrukcji, który honoruje kilka narzędzi.

Jedno ograniczenie zaskakuje ludzi: zasady mają zastosowanie do interakcji agenta i czatu, nie do uzupełnienia Tab ani edycji w liniach. Zasada zakodowana we wzorze kształtuje to, co agent pisze i nie powstrzyma Tab od sugerowania czegokolwiek innego. Warto wiedzieć, zanim dojdziesz do wniosku, że zasada jest ignorowana.

Który tryb najlepiej pasuje do zmiany?

Cursor udostępnia kilka różnych sposobów dokonywania edycji, a wybranie złego z nich marnuje czas. Użyteczną intuicją jest skala.

TrybSiegnij po to, gdyTypowe zadanie PDF
TabJuż piszesz, a kolejna edycja jest przewidywalnaKończenie wcześniej ustawionej właściwości opcji renderowania
Edycja w miejscuZmiana mieści się w jednym zdaniu i znajduje się w jednym plikuDodanie marginesu, stopki lub ustawienia formatu strony
AgentPraca przebiega przez pliki lub wymaga petli budowy i naprawyPodlaczenie rendereru do usługi i kompilowanie
Zaplanuj najpierwPrzepisanie jest na tyle duże, że przeglądanie tego po fakcie byłoby gorsze niż zgodzenie się na początkuMigracja generatora raportów z innej biblioteki PDF
Agent chmurowyZadanie nie wymaga nadzoru i blokuje nicPisanie zestawu testów wokół wyjścia PDF

Edycja linii dla rendereru to najjasniejszy przyklad, poniewaz opisywana jest zmiana i przeglądane są różne miejsca, zamiast czytania nowego pliku:

Add a 25mm top margin and an HTML footer showing "{page} of {total-pages}",
centered, max height 15mm.
Text

To, co ląduje w pliku, jest na tyle krótkie, aby sprawdzić na razie:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.MarginTop = 25;
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    MaxHeight = 15,
    HtmlFragment = "<div style='text-align:center'>{page} of {total-pages}</div>",
};
C#

MarginTop = 25 przywraca domyślny margines górny IronPDF wynoszący 25 milimetrów, więc ta linia zostawia stronę bez zmian. Żaden z marginesów nie przesuwa stopki. Dolny margines ustawia miejsce, gdzie ciało zatrzymuje się nad nim, tak jak pokazuje naprawa stopki później na tej stronie.

{page} i {total-pages} są własnymi polami scalania IronPDF, a nie miejscami zastępczymi ciągów, które zastępujesz sam, co jest rodzajem szczegółu, który dokumentacja rozumie poprawnie, a nieosadzone zgadywanie zazwyczaj nie.

Co naprawdę zmienia wzmianka @?

Wzmianki o kontekście precyzują edytorowi, na co patrzeć. Nazwanie pliku, który tworzy PDF, daje o wiele lepszy rezultat niż jego opisanie, ponieważ opis jest stratny, a odniesienie do pliku nie jest.

@Services/InvoiceRenderer.cs @Templates/invoice.html Use the IronPDF docs at https://ironpdf.com/llms.txt.

The footer overlaps the last line of the invoice table. Fix it in the renderer
configuration, not the template. Explain which setting causes the overlap.
Text

Oprócz plików, menu @ Cursor przyjmuje foldery do pracy obejmującej moduł, wyjścia terminalowe, wcześniejsze czaty, różnice Git i wbudowaną przeglądarkę. Kiedy nie jest wiadomo, który plik się liczy, można pominąć wzmiankę i agent sam przeszuka bazę kodu. Połączenie pliku z dokumentacją, tak jak powyżej, jest wzorcem, który utrzymuje dokładność pracy z IronPDF: plik dostarcza tego, co aktualnie robi kod, a dokumenty dostarczają tego, co oferuje biblioteka.

To konkretne podpowiedzenie także ilustruje, dlaczego fundamenty mają znaczenie. Stopka skonfigurowana bez odpowiadającego marginesu nakłada się na ciało, ponieważ stopka zajmuje miejsce, którego treść nie oddaje we własnym zakresie. To ustawienie rendereru, a nie problem z CSS, a przewodnik po nagłówkach i stopkach dokumentuje tę zależność.

To jest faktura, którą testowy bieg renderował po naprawie:

Jak planować i przeprowadzać migrację do IronPDF?

Migracje to miejsce, gdzie nieoceniony wielopliki przepisania staje się kosztowne, ponieważ odkręcenie jednego jest trudniejsze niż jego napisanie. Planowanie przed wdrożeniem istnieje właśnie w tym celu: przyjmuje cel, zadaje wyjaśniające pytania i tworzy edytowalny plan, zanim zostanie napisany jakikolwiek kod.

@Reports/ Use the IronPDF docs at https://ironpdf.com/llms.txt.

This folder builds PDFs by positioning text at coordinates with another library.
Plan a migration to IronPDF using HTML templates.

Summarize what the current output looks like, covering page size, sections, and
fonts, then propose the template structure and the files that change. Keep
existing public method signatures so callers don't change. Don't write code yet.
Text

Przeglądaj plan, popraw go w dwóch zdaniach i oddaj do wdrożenia. Tryb agenta czyta bazę kodu, edytuje w różnych plikach, uruchamia polecenia terminalowe, czyta wyniki i iteruje, więc kontynuacja jest krótka:

Implement the approved plan. Then run dotnet build, fix what breaks, and
show me the diff. Don't add new packages.
Text

Ograniczanie agenta do zatwierdzonego planu i zabranianie nowych pakietów ma większe znaczenie, niż się wydaje. Agenci pozostawieni bez ograniczeń mają tendencję do traktowania migracji jako zaproszenie do przeprojektowania konwencji wywoływania jako bonusu.

Praca, która nie potrzebuje nadzoru, może działać w agencie w chmurze, podczas gdy kontynuowanie gdzie indziej jest możliwe. Zestaw testów wokół wyjścia PDF jest dobrym kandydatem, ponieważ testy asercji dotyczą dokumentu, a nie implementacji, i nie potrzebują najpierw zakończonej migracji:

Write xUnit tests for the migrated report output: result is non-empty, begins
with the %PDF- signature, extracted text contains the bound company name, and
page count matches expectation. No golden-file byte comparisons, since
rendering output is not byte-stable across versions or platforms.
Text

Wykluczenie porównania bajtowego zapobiega całej klasie niezależnych testów, które w przeciwnym przypadku by kosztowały kogoś popołudnie.

Gdzie naprawdę żyją problemy z renderowaniem?

Trzy z powodów dokumentowanych przez IronPDF różnic między przeglądarką a PDF to arkusz stylów napisany dla mediów ekranowych zamiast drukowanych, czcionka sieciowa, która nie została załadowana, kiedy obliczano układ, i treści wygenerowane przez JavaScript, które zostały uchwycone zbyt wcześnie. Nazwanie objawu i pliku daje najwięcej przydatnych odpowiedzi niż wklejanie całego projektu.

@Templates/report.html @Services/ReportRenderer.cs Use the IronPDF docs at https://ironpdf.com/llms.txt.

The report renders correctly in Chrome but the PDF drops the logo and splits a
table row across pages. Explain the cause of each before changing anything,
then fix the table break in CSS and the logo in the renderer configuration.
Text

Oddzielanie diagnozy od naprawy daje coś do oceny, a nie zmianę do wstecznego inżynierowania. W tym miejscu, dwa problemy mają różne domy: zachowanie podziału stron należy do arkusza stylów, objętego przewodnikiem przewijania stron, podczas gdy logo, które rozwiązuje się w przeglądarce, a nie w renderze, zwykle jest pytaniem o ścieżkę bazową, ponieważ surowa string HTML nie niesie za sobą lokalizacji dokumentu, aby rozwiązać względne URL.

To jest raport strony, który testowy bieg renderował po obu naprawach:

Niepowodzenia wdrożenia to przypadki, gdzie dostęp do terminalu zasługuje na swoje miejsce, ponieważ odpowiedź zwykle żyje w kontenerze, a nie w kodzie.

@Dockerfile Use the IronPDF docs at https://ironpdf.com/llms.txt.

Rendering works on Windows but fails in our Linux container with:

[PASTE FULL EXCEPTION AND STACK TRACE HERE]

Check for missing native dependencies IronPDF's Chromium engine needs on
Debian-based images. Explain the cause, then propose the Dockerfile change.
Don't modify C# code unless the cause is there.
Text

Instrukcja, by nie dotykać kodu aplikacji, jest celowa. Brak wspólnej biblioteki w obrazie to nie problem C#, a agent z wolną ręką czasem opakuje wywołanie w try/catch, które ukrywa błąd, zamiast go naprawić. Przewodnik wdrożenia Docker dokumentuje bieżące wymagania, które zmieniają się wraz z wydaniami.

Co wyprodukowały zapytania w rzeczywistym uruchomieniu?

Siedem z dziewięciu wskazówek na tej stronie działało w kolejności w jednej sesji CLI Cursor, wersja 2026.10.14-941492e. Edycja inline przebiegła w aplikacji desktopowej Cursor, wersja 3.23.23. Projekt był małą aplikacją .NET 8 na IronPDF 2026.10.3 z każdym plikiem nazwanym w wskazówkach i opisanymi przez nie defektami. Poniższe dane pochodzą z niezależnych renderów kodu, który agent napisał, a nie z jego odpowiedzi.

  • Agent pobrał 21 różnych stron dokumentacji IronPDF podczas sesji, poczynając od llms.txt.
  • Każda klasa i członek nazwany w odpowiedzi stopki istniała w IronPDF 2026.10.3, i wszystkie siedem cytowanych stron się załadowało.
  • Program Quickstart napisał jednolistny hello.pdf o wielkości 17 385 bajtów z ustawionym kluczem i rzucił LicensingException przy SaveAs bez klucza.
  • Edycja inline dodała 25 mm górny margines, który jest domyślnym dla IronPDF, i wyśrodkowaną stopkę drukującą „1 z 1”.
  • Przed naprawą stopki, wiersz Total due został wydrukowany nad pierwszą linią stopki jednolistej faktury.
  • Naprawa podniosła dolny margines w InvoiceRenderer.cs z 10 do 40 milimetrów i pozostawiła szablon bez zmian.
  • Po naprawie żaden wiersz faktury nie dotknął stopki, a sumy przeniesiono na drugą stronę.
  • Migracja zachowała wszystkie cztery publiczne sygnatury metod, usunęła PDFsharp i nie dodała żadnego pakietu.
  • Zmigrantowany raport zachował dwie strony A4, czcionki Arial, kolejność sekcji i całkowitą ilość regionalną.
  • Dwa rendery tego samego zmigrantowanego raportu miały ten sam rozmiar i różne bajty.
  • Testy xUnit przeszły 4 z 4 z kluczem i 0 z 4 bez niego.
  • Przed naprawą renderowania raport strony pokazywał tekst alternatywny logo i dzielił ostatni wiersz tabeli na strony 1 i 2.
  • Naprawa przekazała folder szablonów jako bazową ścieżkę, a zasada arkusza stylów utrzymywała każdy wiersz tabeli razem.
  • Po naprawie logo pojawiło się na stronie 1, a ostatni wiersz został w całości przeniesiony na stronę 2.
  • W próbach CLI, plik zasad był stosowany w 6 z 6 testów z globami oddzielonymi przecinkami i w 0 z 6 z listą YAML.
  • Niektóre kroki uruchomiono inaczej niż na stronie. CLI wysłał każdą wzmiankę @ jako zwykły tekst, a agent otworzył nazwane pliki własnymi narzędziami. Po planie migracji sesja pozostała w trybie planu, więc dwa kolejne polecenia zwróciły plany, które zbudowała kolejna wiadomość. Zestaw testowy działał jako lokalny agent, ponieważ agenci w chmurze potrzebują hostowanego repozytorium. Polecenie edycji inline przebiegło w aplikacji desktopowej Cursor, która zarejestrowała je jako czat Agenta z załączoną wybraną linią. Polecenie Docker nie zostało uruchomione, ponieważ maszyna testowa nie ma Docker ani środowiska Linux.

Zapis z biegu na przewodniku AI coding assistants wymienia narzędzie, model i czas trwania każdego przewodnika w tej serii.

Co należy skonfigurować najpierw?

Zakotwiczenie, przed czymkolwiek innym. Połączenie dokumentacji IronPDF i zapisanie jednej zakresowej zasady projektowania zajmuje około piętnastu minut, dotyczy każdego polecenia po tym i stanowi całą różnicę między tym trybem pracy a wklejaniem pytań do ogólnego asystenta czatu. Wszystko, co później, to edycje w linii, wzmianki, planowanie, agenci, to zwykłe użycie edytora, które dzieje się lepiej, gdy fundamenty są ustalone.

Nawyk weryfikacji pozostaje taki sam, niezależnie od tego, który model odpowiada: buduj wcześnie, otwórz PDF i sprawdź nazwy API z dokumentacją, zanim cokolwiek wyślesz. Powtarzalna wersja tego sprawdzenia, przeprowadzona od początku do końca z opublikowanym wynikiem, żyje w przewodniku AI coding assistants guide, wraz z przewodnikami ChatGPT Codex, GitHub Copilot i Google Antigravity.


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