Cómo usar IronPDF con GitHub Copilot

Curtis Chau
Curtis Chau
Actualizado: 26 de octubre de 2026

La mayoría de las guías de codificación asistida por IA suponen que estás dispuesto a cambiar de editores. Para trabajos en .NET esa suposición suele estar equivocada. Los proyectos de IronPDF que se ejecutan en Visual Studio están dentro de soluciones con referencias de proyectos, configuración de NuGet y una canalización de construcción que nadie quiere reubicar solo por intentar un asistente.

GitHub Copilot se ejecuta donde ya están esos proyectos, en Visual Studio, VS Code y JetBrains IDEs, por lo que este flujo de trabajo no necesita migración. También hace algo que ningún asistente de solo editor puede hacer: se ejecuta dentro de GitHub. Puedes describir un problema de PDF en un asunto, asignarlo al agente en la nube de Copilot, y recibir una solicitud de extracción. IronPDF renderiza HTML, CSS y JavaScript a PDF a través de un motor Chromium integrado, y no existe integración entre los dos productos. Lo que los conecta es el repositorio, y las convenciones a las que te comprometes.

Primero una distinción, porque dos temas similares compiten. Esta guía trata sobre cómo usar un asistente de codificación IA para construir software con IronPDF. No se trata de usar modelos de IA para leer o analizar contenido de PDF, lo cual el tutorial de procesamiento de PDF con IA cubre por separado.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronPdf

Instale IronPDF ejecutando el comando arriba en la Consola del Administrador de Paquetes NuGet, o busque el paquete en el Administrador de Paquetes NuGet.

Abre la solución en el IDE donde ya reside y solicita el documento:

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 escribe las pocas líneas que importan, construyendo un ChromePdfRenderer, llamando RenderHtmlAsPdf, y guardando el resultado con SaveAs. Esa parte es poco destacada y no es la razón de ser de esta guía. Lo que sigue: el mismo asistente hará este trabajo sin que nadie lo supervise, en una rama, como una solicitud de extracción, y eso cambia lo que debes configurar.

Dos notas de seguridad, ambas breves. Una clave de licencia nunca debe estar en línea en un prompt o en un commit; vive en la configuración, como describe el guía de claves de licencia, o en una variable de entorno o un secreto del repositorio. Y un agente con acceso de escritura al repositorio abre solicitudes de extracción reales, por lo que la protección de rama y la revisión humana siguen siendo el control que importa.



¿Dónde encaja Copilot en un proyecto ya en Visual Studio?

Copilot trabaja en tres rangos, y elegir el correcto ahorra más tiempo que cualquier técnica de prompt.

Las completaciones en línea y el chat manejan cualquier cosa que podrías describir en una oración y que vive en un solo archivo: ajustar un margen, añadir un pie de página a una llamada de renderizador existente, renombrar un ayudante. Describes el cambio, obtienes un diff en su lugar, aceptas o no.

El modo agente maneja trabajos que abarcan varios archivos, donde Copilot decide qué archivos editar, ejecuta comandos de terminal, lee la salida, e itera en los errores. Este es el rango correcto para una migración o un refactor.

El agente en la nube en GitHub maneja trabajo que no necesita supervisión alguna. Asignas un issue, lo planifica, empuja una rama, y abre una solicitud de extracción. Esto es lo que hace a Copilot diferente de un asistente vinculado a un editor, y es donde el resto de esta guía centra su atención.

Copilot también es un lector razonable. Pedirle que explique el tipo de opciones de renderizado y listar cuáles están configuradas actualmente en el proyecto convierte la referencia de la API en algo que se puede consultar en lugar de desplazarse.

Por favor, tenga en cuenta: Los tres rangos tienen diferentes radios de explosión. Una edición en línea se revisa antes de aplicarse, el modo agente se revisa como un diff, y el trabajo del agente en la nube llega como una solicitud de extracción que puede esperar un día antes de que alguien la lea. Empareja el rango con cuánto deseas estar sosteniendo cuando termine.

¿Cómo comprometes convenciones que sigue cada superficie?

Las instrucciones personalizadas del repositorio se confirman en el repositorio, lo cual significa que rigen tanto el chat del IDE como al agente autónomo, incluido cuando el agente trabaja sin ser observado. Escríbelas una vez, luego deja de repetirte en prompts.

El archivo es .github/copilot-instructions.md. Para un equipo .NET, este es el formato que vale la pena estandarizar, porque es el que Visual Studio documenta la carga, junto con VS Code, JetBrains, el agente en la nube y la revisión de código de Copilot. Copilot también lee otros archivos de instrucciones, AGENTS.md entre ellos, pero el soporte varía por superficie de una versión a otra, por lo que el archivo más seguro por defecto para una tienda de Visual Studio es aquel nombrado por el producto.

# 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

La línea sobre admitir incertidumbre gana su lugar. El defecto de un modelo es producir algo plausible en lugar de admitir un vacío, e inventar renderer.ConvertHtmlToPdfDocument() se lee perfectamente hasta que el compilador no está de acuerdo. Dar permiso para detenerse es barato, y funciona.

Instrucciones específicas de ruta en .github/instructions/**/*.instructions.md guían la orientación a archivos coincidentes, lo que mantiene las convenciones de PDF fuera de solicitudes que no tienen nada que ver con PDFs.

¿Qué hace que un problema sea sobre el que el agente realmente pueda actuar?

Aquí la habilidad que importa no es escribir prompts. Es escritura de asuntos, porque, según GitHub, el agente trabaja desde el título del asunto, descripción y comentarios existentes, y no ve comentarios añadidos después de la asignación. Nadie está presente para aclararlo.

Un issue débil luce así:

Title: PDF looks wrong

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

El agente no tiene archivo para abrir, no sabe cuál de varios PDFs se refiere, no hay descripción de la salida correcta y no hay error del que trabajar. Explorará, adivinará y producirá una solicitud de extracción que puede abordar lo incorrecto por completo.

Un issue fuerte lleva todo lo que un colega necesitaría:

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

Seis cosas separan el segundo del primero: archivos nombrados, la versión del marco y biblioteca, la salida esperada establecida concretamente, el comportamiento actual incluyendo lo que no sucede, restricciones duras, y una definición de término.

Ese detalle sobre que no se lanza ninguna excepción está haciendo un trabajo real. Le dice al agente que esto es un problema de renderización en lugar de un bloqueo, lo que descarta toda una categoría de investigación antes de comenzar. La observación de que el logo se renderiza en Chrome pero no en el PDF lo precisa aún más: una cadena HTML sin procesar no lleva ubicación de documento, por lo que las rutas de imagen relativas se resuelven contra el directorio de trabajo del proceso en lugar de la carpeta de la plantilla, mientras que un navegador sabe de dónde proviene la página.

Una vez asignado, el agente planifica, empuja una rama, abre una solicitud de extracción y solicita revisión. Revisas el diff en lugar de ver el trabajo.

¿Por qué fallan las pruebas del agente en un proyecto de IronPDF?

Esta es la sección que ninguna guía general de Copilot escribirá, y es la que más probablemente te ahorre una tarde.

El agente en la nube construye y prueba en su propio entorno efímero. Para la mayoría de los proyectos, la fuente más una restauración de paquete es suficiente. Un proyecto de IronPDF necesita más, porque el renderizado depende de un motor Chromium con dependencias de plataforma nativas. Si esas están ausentes del corredor del agente en Linux, cada prueba que renderiza un PDF falla, por razones que nada tienen que ver con el código que el agente acaba de escribir.

La consecuencia es peor que una construcción fallida. Al encargarse de encontrar e instalar dependencias faltantes por sí mismo, el agente trabaja por ensayo y error, lo cual la documentación de GitHub llama lento y poco fiable.

La solución es preconfigurar el entorno con .github/workflows/copilot-setup-steps.yml. Parece un flujo de trabajo ordinario de GitHub Actions con dos reglas fáciles de pasar por alto: el trabajo debe llamarse copilot-setup-steps, y el archivo no se activará en absoluto a menos que exista en la rama por defecto de tu repositorio.

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

Dos detalles deciden si esto funciona.

Primero, una clave de licencia no está automáticamente disponible para el agente. GitHub Actions, Codespaces y los secretos de Dependabot no están disponibles para una sesión de agente, por lo que la clave debe agregarse por separado como un secreto de agentes en la configuración del repositorio u organización.

Segundo, y este es el que produce el síntoma confuso: si un paso de configuración falla, Copilot no se detiene. Omite los pasos restantes y comienza a trabajar con el estado en que se encuentra el entorno. Por lo tanto, una instalación de dependencia fallida silenciosamente se ve exactamente como un problema de código. Ejecuta el flujo de trabajo manualmente desde la pestaña de Acciones una vez antes de confiar en él.

Consejos: La regla práctica: cuando una solicitud de extracción de un agente de nube tiene pruebas de render fallidas en un proyecto de IronPDF, verifique el entorno antes de asumir que el cambio es incorrecto. La guía de despliegue de Docker documenta las dependencias, que cambian entre versiones y deben leerse en lugar de recordarse.

¿Qué debes verificar antes de fusionar?

La solicitud de extracción es la superficie de revisión, y se aplican los mismos estándares que a la rama de cualquier colega. La propia revisión de código de Copilot puede ejecutarse como un segundo paso sobre la salida del agente, lo que atrapa problemas mecánicos antes de que un humano lea el diff.

Tres verificaciones importan específicamente para cambios de IronPDF:

  1. ¿Aparece cada nombre de API en la documentación, o algo plausible se deslizó?
  2. ¿El PDF generado realmente se ve bien? Una construcción limpia no dice nada sobre el diseño.
  3. ¿El cambio permaneció dentro de las limitaciones que estableció el asunto?

Solicitar pruebas en la misma solicitud de extracción vale la pena establecerlo como estándar:

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

Descartar la comparación de bytes previene una clase de prueba inestable que de otro modo costaría una tarde, ya que dos renderizaciones del mismo HTML en procesos separados difieren en sus marcas de tiempo y el ID del documento.

¿Cuándo es el código y cuándo es el contenedor?

Tres causas documentadas de diferencias de renderizado entre el navegador y el PDF son una hoja de estilos escrita para medios de pantalla en lugar de impresión, una fuente web que no se cargó cuando se calculó el diseño y contenido producido por JavaScript que se capturó demasiado pronto. Los tres son del lado del código, y los tres merecen ser nombrados en la solicitud:

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

Pedir un diagnóstico antes de un cambio te da algo que evaluar en lugar de una solución para invertir ingeniería. El comportamiento de los saltos de página pertenece a la hoja de estilos, y la guía de saltos de página cubre las propiedades relevantes. Restringir el cambio a CSS impide que un agente resuelva un problema de diseño reestructurando el C#.

La otra mitad de la pregunta es la que respondió la sección anterior: cuando el mismo código se renderiza localmente y falla en un contenedor o en un corredor, generalmente no es el código en absoluto. Pega la excepción completa en lugar de parafrasearla, y apunta la solicitud al Dockerfile en lugar de a la aplicación. Una biblioteca compartida faltante no es un problema de C#.

¿Qué produjeron los prompts en una ejecución real?

Las tres instrucciones y los dos cuerpos del asunto en esta página se ejecutaron en orden, sin supervisión, con GitHub Copilot CLI 1.0.95, que dirigió cada vez a GPT-6 Luna. El archivo de instrucciones y el flujo de trabajo de los pasos de configuración se confirmaron tal como estaban escritos. Las cifras a continuación provienen de verificaciones independientes de los archivos que quedaron después de la ejecución.

  • La instrucción de inicio rápido produjo un Program.cs de 13 líneas que leyó la clave de IRONPDF_LICENSE_KEY y se construyó sin errores ni advertencias.
  • El agente no ejecutó el programa.
  • Ejecutado con la clave, el programa guardó un hello.pdf de una página con 17,385 bytes.
  • Antes de que se ejecutaran los asuntos, la factura dividía un elemento de línea entre las páginas 1 y 2 y no contenía ninguna imagen.
  • El asunto fuerte produjo una factura de dos páginas con cada elemento de línea completo y el logo en la página 1.
  • El agente incrustó el logo como un URI de datos en C# y corrigió los saltos de página en el CSS.
  • La firma pública de InvoiceRenderer.RenderAsync se mantuvo sin cambios, y no se añadió ningún paquete.
  • La nueva prueba afirmó dos páginas para el fixture de 12 elementos, y las 3 pruebas pasaron.
  • El agente agregó una regla para repetir el encabezado de la tabla y reportó que se repitió. La página 2 de la factura renderizada no llevaba fila de encabezado.
  • El asunto débil también corrigió ambos defectos, aunque no nombró ningún archivo ni síntoma específico.
  • El mismo cambio reescribió la hoja de estilos completa y redujo el texto del cuerpo de 13 a 11 píxeles.
  • La instrucción de pruebas añadió una verificación de no vacía y una verificación de nombre de empresa a las pruebas existentes, por lo que el conteo se mantuvo en 3, y ninguna comparó bytes.
  • La instrucción del informe nombró el salto de página forzado antes de los totales y la regla de la fila faltante como las causas antes de editar el CSS.
  • El informe corregido se ajustó en 2 páginas en lugar de 3, sin fila dividida y los totales debajo de los últimos cuatro sitios. ReportRenderer.cs no cambió.
  • El agente nunca enumeró variables de entorno, y la clave no apareció en ningún historial, confirmación o archivo de sesión de Copilot.
  • Algunos pasos se ejecutaron de manera diferente a lo esperado. El repositorio no tenía un remoto de GitHub, por lo que el CLI sustituyó al agente en la nube y cada asunto inició una nueva sesión. La solicitud de pruebas fue a la sesión del asunto fuerte en lugar de un comentario de solicitud de extracción. El flujo de trabajo de los pasos de configuración no se ejecutó, porque esta máquina no tiene un ejecutor de GitHub Actions ni un entorno Linux.

La factura después del asunto fuerte, renderizada por el InvoiceRenderer de la ejecución a partir del fixture de 12 elementos.

El informe después de la corrección de CSS de la instrucción del informe, renderizado por el ReportRenderer de la ejecución.

La versión del Copilot CLI, el modelo y la sincronización para esta ejecución están listados en el registro de ejecución.

¿Qué sigue funcionando cuando nadie está mirando?

Dos cosas, y son las dos que valen la pena configurar primero. Las instrucciones confirmadas en .github/copilot-instructions.md gobiernan al agente en una rama a medianoche exactamente como gobiernan tu IDE al mediodía. Un copilot-setup-steps.yml que instala las dependencias nativas de IronPDF es lo que evita que ese mismo agente las encuentre e instale por ensayo y error. Todo lo demás es un uso ordinario del asistente que simplemente funciona mejor una vez que esos dos existen.

El hábito de verificación no cambia con el rango: construye temprano, abre el PDF y verifica los nombres de API contra la documentación antes de que algo se envíe. La versión reproducible de esa verificación, ejecutada de principio a fin con un resultado publicado, se encuentra en la guía de asistentes de codificación con IA, junto a las guías de Claude Code, ChatGPT Codex y Cursor.


Solución de problemas


¿Preguntas?

Si tienes alguna pregunta, contacta a support@ironsoftware.com

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.

Leer más

¿Listo para empezar?

Descargas de NuGet 22,198,312Versión:2026.11recién lanzado