Cómo usar IronXL con GitHub Copilot

Curtis Chau
Curtis Chau
Actualizado: 15 de octubre de 2026

Una solución de informes .NET ya puede escribir los números correctos en libros de trabajo simples y aún recibir una solicitud sobre la apariencia. Finanzas quiere sus colores de encabezado, separadores de miles, márgenes resaltados, una fila de encabezado que permanezca fija mientras se desplaza, y nombres que otras hojas puedan señalar.

IronXL proporciona las llamadas de estilo para fuentes, rellenos, formatos numéricos, reglas condicionales, congelación de paneles, anchura de columnas, tablas y rangos nombrados. Dos archivos de instrucciones comprometidos con el repositorio registran cómo se comportan esas llamadas.

Esta guía estiliza el informe de ventas mensual existente y comprueba cada estilo con pruebas que guardan el libro de trabajo, lo abren de nuevo y leen cada configuración. La guía de formato de celdas y la guía de formato condicional documentan las llamadas en sí.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronXL.Excel

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

Abre una terminal en el raíz de la solución, inicia copilot, y envía este prompt. El chat de Visual Studio toma los mismos dos archivos como #report-style.md y #ReportStyler.cs.

Read @docs/report-style.md, then fill in @src/FinanceReports/Styling/ReportStyler.cs.
Give it a public static ApplyHouseStyle(WorkBook workbook) method.
It styles the workbook that MonthlySalesReport.Build returns.
IronXL is the IronXL.Excel package.
Styling types are in IronXL.Styles and number formats in IronXL.Formatting.

Keep this first pass to the header row, the data rows and the Total row of the Sales sheet.
Set their fonts, fills, borders, alignment and number formats. The other sections come later.
Find the Total row by the word Total in column A. Don't count on a fixed row number.

1. Call ApplyHouseStyle from Program.cs just before SaveAs.
2. Run the job.
3. Load out/monthly-sales-2026-09.xlsx again.
4. Print the fill and font color of A1 and the FormatString of E2, exactly as IronXL gives them.
Text

El prompt no dice nada sobre cómo IronXL reporta colores y formatos después de una recarga, porque el archivo de instrucciones específico del camino lleva esas reglas.

Establece IRONXL_LICENSE_KEY en el entorno del que parte Copilot, y consulta la guía de claves de licencia para otros lugares donde mantener la clave. Mantenlo fuera de los prompts y commits. Cada prueba aquí carga un libro de trabajo, por lo que la clave tiene que estar presente donde sea que se ejecuten las pruebas.



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

Usa Copilot CLI desde una terminal, o modo agente en Visual Studio o VS Code, para un cambio de estilo que desees observar, ya que puede construir la solución y ejecutar el trabajo de reportes por sí mismo. El chat en línea es suficiente para un cambio de un solo archivo. El agente de la nube en GitHub toma un problema asignado y devuelve una solicitud de extracción.

¿Cómo estableces las convenciones de IronXL para Copilot?

Compromete las convenciones de IronXL como .github/copilot-instructions.md. Copilot CLI, el chat en Visual Studio y VS Code, el agente de la nube y la revisión de código de Copilot todos lo leen, así que coloca el paquete, la regla de licencia y las reglas de prueba allí.

# Copilot instructions

## Workbooks

- Excel work uses IronXL from the IronXL.Excel NuGet package. Styling types
  live in IronXL.Styles, number formats in IronXL.Formatting, and comparison
  operators in IronXL.Formatting.Enums. Add no other spreadsheet package and
  no Office Interop.
- The IronXL version is pinned in Directory.Packages.props. Leave it alone
  unless the task is an upgrade.
- The license key comes from the IRONXL_LICENSE_KEY environment variable,
  and the program reads it there. Never put a key in code, settings files,
  tests or console output, and don't list environment variables.
- docs/report-style.md is the source for every color, border, format and
  name in the monthly sales workbook.
- IronXL documentation is at https://ironsoftware.com/excel/csharp/llms.txt
  and https://ironsoftware.com/excel/csharp/skill.md
- Say so whenever you depart from docs/report-style.md, and before you use
  an IronXL member you cannot find in IronXL.xml in the NuGet cache.

## Tests

- Build the workbook into a temporary folder, save it, load it again with
  WorkBook.Load and assert on what the loaded file reports.
- Never compare workbook bytes and never edit files under TestData.
Markdown

¿Cómo le das al código de estilo sus propias reglas?

Las reglas que solo importan al código que establece o verifica estilos van en .github/instructions/workbook-styling.instructions.md. Su valor applyTo nombra dos carpetas, separadas por una coma, para que las reglas lleguen al estilizador y sus pruebas y se mantengan fuera de las solicitudes sobre la importación de CSV. La documentación de GitHub dice que el CLI incluye el archivo solo cuando Copilot trabaja en un archivo que el patrón coincide. En nuestra ejecución, Copilot CLI enumeró el patrón y la ruta del archivo en cada sesión y dijo al agente que lo leyera antes de cambiar el código. El agente lo abrió antes de su primer edición en cada prompt que cambió código excepto el segundo, que confiaba en la copia ya en la sesión.

---
applyTo: "src/FinanceReports/Styling/**,tests/FinanceReports.Tests/**"
---

- IronXL returns colors as lowercase hex. A fill set with "#1F4E78" reads
  back as "#1f4e78", so compare colors ignoring case.
- A cell with no fill still reports BackgroundColor "#ffffff". Use
  FillPattern (NoFill or SolidForeground) to tell the two apart.
- FormatString only changes how numbers and dates display. A number written
  as a string keeps its raw text, its DecimalValue is 0, and SUM skips it.
- Font.Height is the size in points, the number Excel shows.
- Call AutoSizeColumn last. It measures the formatted text in the cell's
  font, and on a machine without that font it measures in Arial.
- AddNamedTable and AddNamedRange throw ArgumentException when the name
  already exists, and AddConditionalFormatting adds another copy of a rule
  on every call. Guard each one so restyling a styled workbook changes nothing.
- IronXL has no getter for freeze panes. Check one by reading the pane
  element in the sheet XML.
Markdown

Ejecuta /instructions en una sesión CLI para confirmar cuál de los dos archivos está activo antes de un prompt largo.

¿Cómo IronXL lee estilos de celda después de una recarga?

Algunos valores que IronXL devuelve después de WorkBook.Load difieren de lo que el código pasó. Con IronXL 2026.10.1, una fuente establecida con "#FFFFFF" se lee como #ffffff, y un borde establecido con "#BFBFBF" como #bfbfbf. Assert.Equal("#1F4E78", cell.Style.BackgroundColor) falló contra nuestro libro de trabajo de referencia y una comparación que ignora mayúsculas y minúsculas pasó. El informe escribe valores de fecha, y IronXL dio a esas celdas el formato m/d/yy h:mm hasta que el estilizador estableció yyyy-mm-dd. Con #,##0.00, FormattedCellValue devolvió 176,366.84 mientras que Text aún devolvió 176366.84157142858, el número subyacente. Un margen escrito como la cadena "-0.075" mantuvo ese texto bajo 0.00%, y IsText era verdadero. Una cifra de ingresos escrita como texto mantuvo la cadena de formato #,##0.00, por lo que una prueba que solo verifica FormatString pasa en esa celda rota. La documentación XML enviada con el paquete describe Font.Height en píxeles, pero una altura de 12 fue guardada como tamaño 12.

¿Cómo agregas formato condicional, congelación de paneles y anchura de columnas?

Las reglas de margen provienen de CreateConditionalFormattingRule, que toma un ComparisonOperator y una fórmula, y AddConditionalFormatting, que adjunta la regla a un rango. El encabezado congelado es una llamada, CreateFreezePane(0, 1), donde el primer argumento cuenta columnas congeladas y el segundo cuenta filas congeladas, por lo que CreateFreezePane(1, 4) congeló la columna A y las filas 1 a 4. Las anchuras de columna provienen de AutoSizeColumn.

Add three more parts of @docs/report-style.md to ApplyHouseStyle.
It lives in @src/FinanceReports/Styling/ReportStyler.cs.

- The margin highlighting. Both rules go on the data rows of column F and stay off the Total row.
- The frozen header row.
- The column widths. Size them as the very last step, after every font, fill and number format.

Run the job and reload the output. Then print:

- the range, operator and formula of each rule, as IronXL reads them
- the pane element in the Sales sheet's XML
- the width of columns A to F
Text

Nuestro estilizador de referencia ajustó las columnas al final y obtuvo anchuras de 2,790, 6,988, 3,660, 1,740, 3,430 y 1,792 para las columnas A a F, en las unidades de 1/256 de carácter que GetColumn(i).Width devolvió en nuestra ejecución. Dimensionar primero, antes de los formatos, dio 1,587 para Unidades y 3,123 para Ingresos, demasiado angosto una vez que aparecieron los separadores de miles y 3,635 para la columna de fechas, que fue medida con el formato de fecha y hora por defecto más largo.

Las fuentes también cambian los números. En nuestra máquina Windows cuatro fuentes que no estaban instaladas produjeron exactamente las anchuras de Arial, que corrieron de 6 a 9 por ciento más ancho que Calibri. Por lo tanto, una prueba que fija anchuras exactas falla en cualquier corredor que carezca de la fuente del informe.

El panel congelado se escribe como <pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/> en el XML de la hoja y sobrevivió una carga y guardado a través de IronXL.

IronXL guarda cada relleno de regla como una entrada en una paleta indexada personalizada en xl/styles.xml, y nuestro archivo tenía los colores correctos, FFC7CE y C6EFCE. Leído de nuevo a través de PatternFormatting.BackgroundColor, ambas reglas reportaron #ffc7ce. El rango, el operador, la fórmula y el color de fuente de cada regla se leyeron correctamente. Solo el relleno necesita el archivo, aunque leer ambos colores de él permite que un asistente de prueba los cubra.

¿Cómo agregas tablas y rangos nombrados?

Los nombres en el documento de estilo provienen de dos llamadas. AddNamedTable("SalesData", range, true, TableStyle.TableStyleLight9, true) convierte las filas de encabezado y datos en una tabla con botones de filtro. AddNamedRange("TotalRevenue", range, true) da a la celda de Ingresos de la fila Total un nombre de libro de trabajo que una fórmula de Resumen puede usar como =TotalRevenue. Después de EvaluateAll, esa fórmula devolvió el mismo total que la celda que nombra. FindNamedRange("TotalRevenue") devuelve la referencia como el texto 'Sales'!$E$38:$E$38 y no un Range. SaveAsNamedTable y SaveAsNamedRange en un Range hacen el mismo trabajo.

Ninguna de las cuatro llamadas verifica un nombre existente. Ejecuta el estilizador una segunda vez en un libro de trabajo que ya ha sido estilizado y AddNamedTable lanza ArgumentException con el mensaje "El libro de trabajo ya contiene una tabla con el nombre: SalesData". AddNamedRange hace lo mismo para TotalRevenue, y las dos llamadas SaveAs lanzan las mismas dos excepciones. AddConditionalFormatting no lanza, y en nuestra prueba una segunda ejecución llevó la hoja de dos reglas de margen a cuatro. IronXL también rechazó el nombre de tabla Sales Table, con un ArgumentException que dice que los nombres no deben contener espacios.

Finish @src/FinanceReports/Styling/ReportStyler.cs with what's left in @docs/report-style.md.
That's the SalesData table, the TotalRevenue name and the Summary sheet rules.
Column sizing stays the final step.

Finance fixes figures directly in a saved workbook and sends it back for the house style.
So add a restyle <path> command to Program.cs.
It loads the file, calls ApplyHouseStyle and saves the file over itself.
Restyling a file twice has to leave exactly one table, one TotalRevenue name and two margin rules.

Show me that it holds:

1. Run the job once.
2. Make a copy of the output in out/ and restyle that copy twice.
3. After each pass, print the table names, named ranges, rule count and the value of Summary!B2.
Text

Eliminar las viejas reglas de margen con RemoveConditionalFormatting antes de agregar las nuevas, o saltarse una regla que la hoja ya tiene, mantiene el conteo de reglas en dos, y verificar GetNamedTableNames y GetNamedRanges antes de cada agregado impide que la segunda pasada lance.

¿Cómo pruebas estilos de Excel después de una recarga?

La suite necesita algunos asistentes antes que cualquier prueba única sea útil, uno para leer el XML de la hoja y uno para resolver colores de reglas, por lo que este prompt comienza con /plan. En modo plan, Copilot CLI bloquea ediciones a archivos de proyecto hasta que apruebes el plan.

/plan an xUnit suite in tests/FinanceReports.Tests that checks the house style after a reload.

Build the September report into a temp folder, save it and open it again with WorkBook.Load.
Then check each rule in docs/report-style.md against what the reopened file holds.

- Check FillPattern beside every fill color.
- Read the frozen pane from the Sales sheet XML with ZipArchive.
- For the margin rules, read each rule's range, operator and formula through IronXL.
- Resolve each rule's fill and font color from its dxf entry in xl/styles.xml.
- An indexed color there points into the indexedColors list, so follow it.
- Check FormattedCellValue for a sample of cells in every numeric column.
- Add a test that restyles a saved copy twice.
- For the widths, autosize a reloaded copy again and confirm no column moves.
- Never assert an exact column width.

Implement the plan, then run dotnet test.
Text

¿Por qué los valores de celda formateados dependen de la cultura?

IronXL formatea FormattedCellValue con la cultura actual de .NET. El libro de trabajo es el mismo archivo de cualquier manera, y la cadena de formato lee #,##0.00 en cada cultura que probamos.

  • en-CA: Una celda de ingresos mostró 176,366.84.
  • de-DE: La misma celda mostró 176.366,84.
  • fr-FR: La misma celda mostró 176 366,84, donde el espacio es un espacio estrecho sin interrupciones (U+202F).

Un margen de -0.075 formateado como 0.00% volvió como -7,50% en ambos de-DE y fr-FR. Text también cambia, y DecimalValue no lo hace.

La suite que Copilot escribió desde el prompt /plan compara esas cadenas directamente, por ejemplo Assert.Equal("47,999.33", ...) en la primera celda de ingresos. Lo ejecutamos de nuevo bajo de-DE y luego fr-FR. La prueba de estilo de casa falló ambas veces, con 47.999,33 y 47 999,33 como los valores reales, y las otras tres pruebas pasaron.

Establecer CultureInfo.CurrentCulture a en-US en la parte superior de esa prueba lo hizo pasar de nuevo para de-DE y fr-FR. Un libro de trabajo cargado con de-DE y leído después del cambio a en-US también dio 176,366.84, por lo que el ajuste que cuenta es el que está en vigor cuando la prueba lee la celda. Fija la cultura en cualquier prueba que compare cadenas de visualización, o compara DecimalValue y FormatString en su lugar. La computadora portátil de un colega o el entorno del agente de la nube puede funcionar con una cultura diferente a la máquina que produjo las cadenas esperadas.

¿Qué hace que un problema sea en el que el agente de la nube pueda actuar?

El agente de la nube recibe el título del problema, la descripción, los comentarios ya en el problema y las instrucciones agregadas en la asignación. GitHub declara que no ve los comentarios publicados después, por lo que cada requisito y la prueba que cierra el trabajo pertenecen al cuerpo del problema.

Title: Add an XLS copy of the monthly sales workbook for the ERP import

**Files:** src/FinanceReports/Program.cs, src/FinanceReports/Styling/ReportStyler.cs
**IronXL version:** as pinned in Directory.Packages.props
**Framework:** .NET 9

**Expected:** Each run writes out/monthly-sales-2026-09.xls next to the XLSX,
with the same values and the house style in docs/report-style.md, except the
SalesData table. The TotalRevenue name and Summary!B2 stay.

**Actual:** The ERP import accepts only .xls, and finance converts the file by
hand every month.

**Constraints:** Leave the XLSX output unchanged. Build the XLS workbook with
WorkBook.Create(ExcelFileFormat.XLS) rather than saving the XLSX under a new
extension. In XLS, set every fill before any font color. No new packages.

**Acceptance:** dotnet test passes, plus tests that reopen the .xls and check
the header fill and white header text, the four number formats, the
TotalRevenue name and the operator and formula of both margin rules.
Markdown

Las reglas XLS en el problema provienen de medidas.

  • Tablas nombradas: AddNamedTable y SaveAsNamedTable en un libro de trabajo XLS lanzan NotSupportedException con "Solo XLSX admite tablas nombradas".
  • SaveAs con una ruta .xls: En el libro de trabajo XLSX, SaveAs lanzó FormulaParseException, y su mensaje decía que el rango nombrado TotalRevenue no existía en el libro de trabajo actual.
  • Orden de relleno: XLS almacena colores en una paleta compartida, y en una sonda una fuente de encabezado establecida en blanco antes de que se agregaran tres rellenos volvió como #ddebf7, el segundo de esos rellenos, mientras que establecer los rellenos primero lo mantuvo como #ffffff.
  • Rellenos de reglas: Leer el relleno de una regla de márgenes desde el archivo XLS recargado lanzó NullReferenceException, por lo que la línea de aceptación pide el operador y fórmula de cada regla y no sus colores.

¿Por qué fallan las pruebas del agente de la nube en un proyecto IronXL?

Por defecto, el entorno del agente ejecuta Ubuntu Linux. Cuando todas las pruebas de estilo fallan juntas en una rama que el agente empujó, lee la primera excepción antes del diff. Un LicensingException señala la clave de licencia.

El agente de la nube no puede leer secretos de Actions, Codespaces o Dependabot, por lo que la clave necesita un secreto de Agents. Agrega IRONXL_LICENSE_KEY bajo Configuración, luego Secrets y variables, luego Agents, y el agente lo recibe como una variable de entorno. Las solicitudes de extracción del agente aterrizan en el repositorio real, por lo que mantiene la protección de la rama y la aprobación humana encendida.

¿Por qué falla el estilo en libros de trabajo de otras bibliotecas?

Un libro de trabajo de la oficina EMEA, escrito por un trabajo de Python en openpyxl con el mismo diseño que el informe, lanzó InvalidOperationException con "El objeto Nullable debe tener un valor" desde el primer configurador de estilo llamado sobre él, ya sea que estableciera texto en negrita o un formato numérico. ApplyHouseStyle funcionó en cada libro de trabajo que escribe nuestro propio trabajo, lo que hace que parezca un error en el estilizador cuando la causa está en el archivo.

A colleague added tests/FinanceReports.Tests/PartnerWorkbookTests.cs and it fails.
It covers the workbooks the EMEA office sends, which a Python job writes with openpyxl.
It throws InvalidOperationException "Nullable object must have a value".
The exception comes from deep inside the first style setter.
ApplyHouseStyle still passes on our own output.

Before you edit anything, find out what causes it and tell me:

1. Open TestData/partner/emea-2026-09.xlsx and one workbook our job writes with ZipArchive.
2. Compare the fill entries in xl/styles.xml.
3. Try a single style setter on each workbook.

Then fix it at the point where the restyle command and this test load a workbook.
Leave the partner file untouched on disk and add no package.
Run dotnet test when you're done.
Text

El primer relleno del archivo del socio es <patternFill />, sin atributo patternType, que openpyxl 3.1.5 escribe para su relleno por defecto. El archivo de nuestro trabajo tiene <patternFill patternType="none"/> en el mismo lugar. IronXL cargó el archivo del socio y leyó sus valores sin un error. Cargándolo, guardándolo a través de IronXL y cargándolo de nuevo mantuvo el elemento desnudo y aún lanzó. Agregar el atributo faltante a ese elemento en memoria y cargar el paquete parcheado, a través de WorkBook.Load(Stream) en nuestra sonda o desde una copia temporal, permitió que se aplicara el estilo completo de la casa, y el archivo en disco se mantuvo como lo envió el socio.

Mantener la solución en el paso de carga impide que el asistente atrape la excepción dentro del estilizador, lo que ocultaría el problema y dejaría el libro de trabajo del socio sin estilo.

¿Qué debes verificar antes de fusionar?

La documentación de GitHub muestra /review enviado como un prompt copilot -p, por lo que esta revisión puede ejecutarse desde un script antes de fusionar.

/review the commits on this branch after the first one.
Check them against docs/report-style.md and both instruction files under .github.

Flag any of these:

- a color compared with case-sensitive equality
- an AutoSizeColumn call that runs before a later format or font change
- an AddNamedTable, AddNamedRange or AddConditionalFormatting call with no guard for a second run
- a test that pins an exact column width or compares workbook bytes
- an IronXL member that isn't in IronXL.xml in the NuGet cache

Give each finding its file and line. Don't edit anything.
Text

El prompt nombra ambos archivos de instrucciones para que las reglas de estilo se apliquen a toda la revisión y no solo a los archivos que el patrón coincide. La revisión de código de Copilot en GitHub también admite el archivo específico del camino.

El diff aún necesita una lectura humana para la única cosa que la revisión y las pruebas pueden pasar por alto, que es si los valores cambiaron. El estilo debe dejar cada número y fecha como el informe lo escribió, y cada fórmula excepto Summary!B2, que el documento de estilo mueve al nombre TotalRevenue. Los totales deben coincidir con la alimentación CSV.

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

Copilot CLI recibió los seis prompts en secuencia sin nadie en el teclado. Los primeros cinco compartieron una sesión, con el prompt /plan ejecutado en modo plan y piloto automático, y /review se ejecutó como su propia llamada copilot -p. El objetivo era una solución de informes construida para esta guía en .NET 9, con un trabajo de consola que escribe el libro de trabajo de septiembre sin estilo desde una alimentación CSV, un proyecto xUnit sin pruebas aún, y el documento de estilo. Un commit antes del prompt del socio agregó el libro de trabajo de EMEA y la prueba fallida del colega. Cada cifra a continuación proviene de reconstruir la solución, volver a ejecutar el trabajo y ejecutar las pruebas una vez que Copilot había terminado. La guía de asistentes de codificación AI convierte este tipo de verificación en una prueba repetible.

  • Nuestra verificación de estilo pasó 23 de 30 comprobaciones después del primer prompt, cada encabezado, datos y verificación de Total entre ellas. Pasó 25 de 30 después de las reglas, el panel y las anchuras, y 31 de 31 después de los nombres y el comando de reestilo, con cada valor todavía coincidiendo con la alimentación CSV.
  • Después del segundo prompt, las anchuras de las columnas coincidieron exactamente con nuestro estilizador de referencia, y ambas reglas de márgenes se sentaron en F2:F37.
  • Restilizar una copia dos veces dejó una tabla, un nombre TotalRevenue y dos reglas de márgenes, y Summary!B2 todavía devolvió 10,977,073.68.
  • La suite planificada pasó 3 de 3 pruebas. Mover el dimensionamiento de columnas antes de los formatos en una copia del código final hizo que fallara su prueba de anchura.
  • Después del prompt del socio, pasaron 4 de 4 pruebas y una copia reestilizada del libro de trabajo EMEA pasó todas las 32 comprobaciones.
  • La llamada /review no encontró ninguno de los cinco problemas listados.
  • Algunos pasos se ejecutaron de manera diferente a lo esperado. El primer prompt también agregó ambas reglas de márgenes, que la página deja para el segundo. En una ejecución anterior, la prueba de anchura solo verificó que existieran anchuras y pasó con columnas dimensionadas primero, por lo que el prompt /plan ahora pide una segunda pasada de ajuste automático. El problema, el agente de la nube, el secreto Agents y la revisión de la solicitud de extracción necesitan un repositorio alojado, por lo que ninguno de ellos se ejecutó.

La versión de Copilot CLI, el modelo Auto elegido, el tiempo de ejecución y la máquina de prueba se registran una vez para cada guía en el registro de ejecución.


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 2,393,101Versión:2026.11recién lanzado