如何使用IronPDF和GitHub Copilot

Curtis Chau
Curtis Chau
更新: 2026年10月26日

大多数关于AI辅助编码的指南假设您愿意更换编辑器。 .NET工作中这种假设往往是错误的。 在Visual Studio中运行的IronPDF项目位于包含项目引用、NuGet配置和构建管线的解决方案中,没有人愿意为了尝试一个助手而重新定位。

GitHub Copilot可以运行在这些项目所在的位置,即Visual Studio、VS Code和JetBrains IDEs,因此这种工作流程不需要迁移。 它还做了一些编辑器独立助手无法做到的事情:它在GitHub自身内部运行。 您可以在问题中描述 PDF 问题,将其分配给 Copilot 的云代理,并获得一个拉取请求。IronPDF 通过一个嵌入式 Chromium 引擎将 HTML、CSS 和 JavaScript 渲染为 PDF,并且这两个产品之间没有集成。 链接它们的是仓库,以及您在其中提交的约定。

首先区分一下,因为有两个相似的主题在竞争。 本指南是关于使用AI编码助手构建软件与IronPDF。 它不是关于使用AI模型读取或分析PDF内容,AI驱动的PDF处理教程对此有单独介绍。

快速入门
NuGet使用NuGet安装

PM > Install-Package IronPdf

通过在 NuGet 包管理器控制台中运行上述命令安装 IronPDF,或在 NuGet 包管理器中搜索该包。

在它已经存在的任何IDE中打开解决方案,并请求文档:

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 编写了几行重要的代码,构建一个 ChromePdfRenderer,调用 RenderHtmlAsPdf,并使用 SaveAs 保存结果。 那部分没什么特别,这不是指南存在的原因。 接下来是:同一个助手将在没人观看的情况下,在一个分支上作为一个拉取请求执行这些工作,这改变了您需要设置的内容。

两个安全提示,都很简短。 许可证密钥永远不应在提示或提交中内联出现; 它存在于配置中,如许可证密钥指南,或在环境变量或存储库的秘密中。 具有仓库写权限的代理会打开真实的拉取请求,因此分支保护和人工审核仍然是重要的控制措施。



GitHub Copilot如何适应已在Visual Studio中的项目?

Copilot有三个工作范围,选对一个比任何提示技巧都能节省时间。

内联完成和聊天处理您可以在一句话中描述的单文件内容:调整边距、向现有渲染器调用中添加页脚、重命名助手。 您描述更改,您得到一个差异,您接受或不接受。

代理模式处理跨多个文件的工作,Copilot会决定编辑哪些文件、运行终端命令、读取输出并迭代错误。 这是迁移或重构的合适范围。

GitHub 上的云代理 处理完全不需要监管的工作。 您分配问题,它规划、推送一个分支并打开一个拉取请求。这使得Copilot与绑定编辑器的助手不同,这也是本指南其余部分关注的重点。

Copilot也是一个合格的读者。 让它解释渲染选项类型并列出项目当前设置的选项将API参考变成可以查询而非滚动的对象。

请注意: 这三个范围的爆炸半径不同。 内联编辑在应用之前会被审核,代理模式以差异形式被审核,而云代理的工作以拉取请求的形式到达,可以在出现后等上一天直到有人阅读。 选择一个范围以决定在结束时您希望持有的数量。

如何提交每个表面遵循的约定?

存储库自定义说明提交到存储库中,意味着它们支配 IDE 聊天和自主代理,包括代理在无人监管时的操作。 编写一次,然后在提示中停止重复。

文件是 .github/copilot-instructions.md。 对于 .NET 团队来说,这种格式值得标准化,因为 Visual Studio 与 VS Code、JetBrains、云代理以及 Copilot 代码评审一起记录了它的加载方式。 Copilot 还读取其他指令文件,其中包括 AGENTS.md,但不同界面的支持程度因发行版而异,因此对于 Visual Studio 公司的最安全默认是以产品命名的文件。

# 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

关于承认不确定性的那一行是有理由的。 模型的默认是生成形状像样的内容,而不是承认差距,发明 renderer.ConvertHtmlToPdfDocument() 一直到编译器不同意之前都能很好地运行。 允许停止是成本低廉而有效的。

.github/instructions/**/*.instructions.md 中的路径特定指令将指导作用范围扩展至匹配文件,从而避免将 PDF 约定失败请求中与 PDF 无关的部分。

什么使得一个问题代理可以实际处理?

在这里,重要的技巧不是编写提示。 这是写问题,因为,根据 GitHub,代理从问题的标题、描述和已有的评论中工作,并且不会看到分配后添加的评论。 没有人在场解释它。

一个弱的问题看起来像这样:

Title: PDF looks wrong

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

代理没有要打开的文件,不知道是多个PDF中的哪一个,没有正确输出的描述,也没有可以处理的错误。 它将探索、猜测并生成一个可能完全针对错误问题的拉取请求。

一个强有力的问题包含同事所需的一切:

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

将第二个和第一个分开的六件事:命名文件、框架和库版本、具体的预期输出、包括什么并未发生的实际行为、严格的约束以及完成的定义。

关于未抛出异常的细节确实在工作。 它告诉代理这更像是一个渲染问题而不是崩溃,这排除了大类调查,还未开始就排除。 观察到标志在 Chrome 中渲染但在 PDF 中未渲染,这进一步缩小了范围:原始 HTML 字符串没有文档位置,因此相对图像路径根据工作路径解析,而不是模板文件夹,而浏览器知道页面的来源。

一旦被分配,代理会计划、推送一个分支、打开一个拉取请求并请求审核。 您查看差异而不是观看工作。

为什么代理的测试在IronPDF项目中失败?

这是一般的Copilot指南不会写的章节,也是最有可能节省你一个下午的章节。

云代理在其自身临时环境中构建并测试。 对大多数项目来说,源代码加上一个包恢复就足够。 IronPDF项目需要更多,因为渲染依赖于一个具有本机平台依赖关系的Chromium引擎。 如果这些依赖关系缺失于代理的Linux运行者上,所有渲染PDF的测试都会失败,这与代理刚刚编写的代码无关。

后果比构建失败更糟。 如果让其自行查找和安装缺失的依赖性,代理通过试错的方式工作,这种方式GitHub 的文档称之为缓慢且不可靠。

解决办法是通过 .github/workflows/copilot-setup-steps.yml 预配置环境。 看上去像是一个普通的 GitHub Actions 工作流,有两个容易被忽略的规则:任务必须命名为 copilot-setup-steps,而且文件必须存在于您的存储库默认分支上,否则根本不会触发。

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

两个细节决定这是否有效。

首先,代理并不能自动获得许可证密钥。 GitHub Actions、Codespaces 和 Dependabot 密钥在代理会话中不可用,因此密钥必须作为 代理秘密 单独添加到存储库或组织设置中。

第二个导致混乱症状的问题是:如果设置步骤失败,Copilot不会停止。 它会跳过其余步骤,并在环境当前状态下开始工作。 因此,一次静默失败的依赖安装看起来就像一个代码问题。 从操作标签中手动运行一次工作流程,在依赖之前依赖它。

提示: 实用规则:当云代理拉取请求在IronPDF项目上未通过渲染测试时,在您认为更改错误之前,请先检查环境。 Docker 部署指南记录着依赖项,这些依赖项会在版本之间变化,应该阅读而不是回忆。

合并前应检查什么?

拉取请求是审查表面,适用于任何同事分支的标准也同样适用。 Copilot自己可以作为代理输出的第二道审核程序,可以在人类阅读差异之前捕捉机械问题。

对IronPDF更改尤其重要的三项检查是:

  1. 每个API名称是否出现在文档中,或者某些合理的遗漏通过了?
  2. 生成的 PDF 实际上看起来对吗? 清理构建不说明布局。
  3. 更改是否保持在问题设置的限制内?

要求在同一个拉取请求中进行测试是值得标准化的:

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

排除字节比较可以避免一类会浪费整个下午的不稳定测试,因为两个不同进程中的相同 HTML 渲染在时间戳和文档 ID 上有所不同。

什么时候是代码的问题,什么时候是容器的问题?

浏览器和 PDF 渲染差异的三种已记录原因是样式表为屏幕而非打印媒体编写、布局计算时未加载网络字体、和过早捕获的 JavaScript 生成内容。 这三者都是代码端的问题,并且值得在请求中指明。

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

在更改之前要求诊断会提供评估的依据,而不是进行逆向工程的修复。 页面断点行为属于样式表中,分页断点指南涵盖了相关属性。 将更改限制在CSS中可以避免代理通过重新结构化C#来解决布局问题。

问题的另一半由上一篇回答:当相同的代码在本地渲染但在容器或运行器中失败时,通常它完全不是代码的问题。 粘贴完整异常而不是改写它,并将请求指向Dockerfile而不是应用。 缺少共享库不是 C# 问题。

在实际运行中这些提示生成了什么?

本页上的三个提示和两个问题主体按顺序运行,无人值守,使用 GitHub Copilot CLI 1.0.95,该版本将每个回合路由到 GPT-6 Luna。 说明文件和设置步骤工作流程按原样提交。 下面的数字来自对运行后留下文件的独立检查。

  • 快速入门提示生成了一个 13 行的 Program.cs,从 IRONPDF_LICENSE_KEY 读取密钥,并无错误或警告地构建。
  • 代理没有运行程序。
  • 使用该密钥运行,程序保存了一个大小为 17,385 字节的 hello.pdf。
  • 在问题运行前,发票将一行物品拆分到第 1 和第 2 页,并且没有图像。
  • 强问题生成了一个每项物品都完整且在第一页有标志的双页发票。
  • 代理在 C# 中将标志嵌入为数据 URI 并修复了 CSS 中的分页。
  • InvoiceRenderer.RenderAsync 的公共签名保持不变,且未添加任何包。
  • 新的测试断言 12 项夹具的双页结果,并且所有 3 个测试都通过了。
  • 代理添加了一个重复表头的规则并报告了它的重复情况。 已渲染发票的第2页没有携带标题行。
  • 弱问题也修复了这两个缺陷,尽管它没有指定文件和具体症状。
  • 相同的更改重写了整个样式表并将正文文本大小从 13 像素减少到 11 像素。
  • 测试提示为现有测试中添加了一个非空检查和公司名称检查,因此数量保持在 3 个,且没有对字节进行比较。
  • 报告提示在编辑 CSS 之前将强制分页和缺失行规则命名为成因。
  • 修复的报告适合在 2 页内而不是 3 页,没有拆分行,且合计在最后四个站点之下。 ReportRenderer.cs 未更改。
  • 代理从未列出环境变量,且密钥未出现在任何记录、提交或 Copilot 会话文件中。
  • 有些步骤与页面中的运行不一样。 存储库没有 GitHub 远程,因此 CLI 代替云代理,每个问题都启动一个新会话。 测试请求前往强问题的会话而不是拉取请求评论。 设置步骤工作流未执行,因这台机器没有 GitHub Actions 运行器和 Linux 环境。

强问题后的发票,由运行的 InvoiceRenderer 渲染于 12 项夹具。

报告提示中的 CSS 修复后,报告由运行的 ReportRenderer 渲染。

此运行的 Copilot CLI 版本、模型和时间列在运行记录中。

无人看管时什么会继续工作?

两个值得首先设置。Commit 的说明在 .github/copilot-instructions.md 中管理分支上午夜代理,就像它们在正午管理您的 IDE 一样精确。 一个安装 IronPDF 原生依赖项的 copilot-setup-steps.yml 可以避免同一代理通过试错找到并安装它们。 其他一切都是普通助手使用,恰巧因为这些存在而表现更好。

验证习惯不会因为范围而改变:早期构建,打开PDF,在发货前根据文档检查API名称。 那项检查的可复现版本,从头到尾运行并发布结果,存在于AI编码助手指南中,伴随着Claude Code、ChatGPT Codex和Cursor的指南。


故障排除


有问题吗?

如果您有任何问题,请联系support@ironsoftware.com

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

阅读更多

准备开始了吗?

NuGet 下载量 22,198,312版本:2026.11刚刚发布