Uso de IronBarcode con GitHub Copilot, en el IDE y en GitHub
Los proyectos de IronBarcode fallan en los runners de GitHub por falta de dependencias nativas y claves de licencia. La compilación en Linux necesita un paquete de plataforma que lleve esas dependencias, y cada llamada de código de barras necesita una clave. Copilot se encuentra con ambos requisitos cuando compila su proyecto en GitHub, y las pruebas fallidas que no logra explicar lo envían a buscar un error que nunca estuvo en el código.
Nada de esto requiere salir de su IDE. GitHub Copilot está disponible en Visual Studio, VS Code y JetBrains, por lo que su solución existente, referencias de proyectos, configuraciones de NuGet y pipeline de compilación permanecen donde están.
No se distribuye ningún plugin de Copilot para IronBarcode, y no hay ninguna opción que activar. Todo lo que Copilot sabe sobre los códigos de barras proviene del repositorio, de las convenciones que usted guarda allí en commits y del entorno que le proporciona. El asistente maneja una región de recorte o un cambio de margen dentro de un archivo. Si se le informa lo suficiente, puede estampar códigos de barras en un PDF o corregir un escaneo fallido en GitHub sin que usted lo supervise.
La detección propia de aprendizaje automático de IronBarcode es una característica separada con su propio ejemplo de umbral de confianza, y nada de lo que sigue lo afecta.
Inicio rápidoAbra su solución en el IDE que ya utiliza y plantee esto a Copilot Chat con el proyecto en contexto. #solution es la referencia de Visual Studio que limita una solicitud a toda la solución. En VS Code, use #codebase en su lugar.
#solution Add the BarCode package to this project. In Program.cs, copy an
existing invoice PDF, then stamp a Code 128 barcode of the invoice number onto
the first page of the copy with StampToExistingPdfPage, which writes in place.
Take the license key from IRONBARCODE_LICENSE_KEY, never inline. Build, and fix
anything that breaks.
El ejemplo necesita dos llamadas, una para crear el símbolo y otra para estamparlo en la página que indique, y la guía para estampar códigos de barras en PDFs cubre el índice de página y los argumentos de colocación. Debería ver ambas llamadas en la sugerencia. Alternativamente, puede enviar la misma solicitud al asistente en GitHub, que se ejecutará sin supervisión en una rama y le entregará una solicitud de extracción. Eso cambia lo que necesita preparar.
Dos puntos de seguridad antes de comenzar. Primero, mantenga las claves de licencia fuera de las indicaciones y los commits almacenándolas en configuración, variables de entorno o secretos del repositorio como se describe en la guía de claves de licencia. Segundo, recuerde que el acceso de escritura permite a Copilot abrir solicitudes de extracción reales, por lo que la protección de ramas y la revisión humana siguen siendo su principal salvaguarda.
Flujo de trabajo mínimo en 5 pasos
- Descargue la biblioteca de códigos de barras para C# desde NuGet
- Guarde en un commit
.github/copilot-instructions.mdcon las convenciones de IronBarcode del proyecto - Use el chat en línea para pequeñas ediciones y el modo de múltiples archivos del editor para ediciones mayores
- Para trabajo sin supervisión, cree una incidencia detallada y asígnesela al asistente en GitHub
- Revise la solicitud de extracción, verificando cada nombre de API en la referencia de API
¿Dónde encaja Copilot en un proyecto ya en Visual Studio?
Copilot opera en tres niveles, y el alcance se amplía en cada uno.
Las sugerencias de autocompletado en línea y el chat están en el editor. Son mejores para cambios que pueden describirse en una sola oración dentro de un archivo, como cambiar la simbología, agregar un margen o limitar un lector a un formato. Usted describe el cambio, revisa el diff resultante y decide si lo acepta o lo descarta.
El modo de múltiples archivos del editor asume cambios que abarcan varios archivos. Selecciona los archivos, ejecuta comandos de la terminal, revisa resultados e itera sobre errores. Úselo para migraciones y refactorización.
El asistente en GitHub maneja tareas que no desea supervisar directamente. Usted proporciona instrucciones mediante una incidencia, y más tarde recibe una rama y una solicitud de extracción. Nada vinculado al editor puede hacer eso, así que la mayor parte de lo que sigue concierne a ese modo.
Los tres leen bien la documentación. Dirija uno a la referencia de API, pregunte qué opciones de BarcodeReaderOptions deja su proyecto en sus valores predeterminados, y recibirá la respuesta sin tener que recopilarla manualmente.
¿Cómo guardar en commits convenciones que se apliquen en todas las interfaces?
Las instrucciones personalizadas residen en el repositorio, por lo que dan forma a las sugerencias del IDE y a las ejecuciones no supervisadas por igual. Escríbalas una vez y deje de repetirlas en las indicaciones.
Use .github/copilot-instructions.md. Es el archivo de todo el repositorio, y se aplica en los IDEs, en GitHub y en la revisión de código de Copilot. Si IronBarcode es el estándar en más de un repositorio, establezca las reglas una vez como instrucciones personalizadas de organización en su lugar. Un propietario de organización en un plan de Copilot Business o Enterprise puede hacer eso, y esas instrucciones llegan a Copilot Chat en github.com, revisión de código de Copilot, y trabajo sin supervisión allí. Copilot también lee AGENTS.md en cualquier lugar del árbol, con prioridad para el archivo más cercano, además de un solo CLAUDE.md o GEMINI.md en la raíz. Si su repositorio ya mantiene reglas de código de barras en AGENTS.md para otra herramienta, Copilot las respeta y no necesita una segunda copia.
# Copilot instructions
## Barcodes
- IronBarcode is this repository's barcode library. The package is BarCode, the
namespace is IronBarCode, and no competing package may be introduced.
- Reference: https://ironsoftware.com/barcode/csharp/llms.txt
Skill file: https://ironsoftware.com/barcode/csharp/skill.md
- The BarCode version is pinned in Directory.Packages.props. Changing it is its
own pull request, never a side effect of another change.
- License keys come from configuration or IRONBARCODE_LICENSE_KEY, and never
appear in source, in a commit, or in a pull request description.
- Cite a documentation page for any IronBarcode member you are not certain of.
Saying you are unsure is an acceptable answer.
## Testing
- A barcode change is not complete until the generated barcode has been decoded
and compared with the value that was written.
- Assert on decoded values and formats. Never compare image bytes.
## Pull requests
- Say which IronBarcode APIs the change introduces, and link the page for each.
- If the barcode tests fail, check the runner environment before changing code
that the issue did not ask you to touch.
Los modelos tienden a proporcionar respuestas expresadas con seguridad en lugar de reconocer la incertidumbre, por lo que una llamada como BarcodeScanner.DecodeImageFile() puede parecer válida hasta que falle la compilación. Permitir que el modelo se detenga cuando no está seguro no cuesta nada y mantiene las APIs inventadas fuera del diff.
Para reglas más específicas, coloque un archivo en .github/instructions/ llamado something.instructions.md. Use un patrón glob de applyTo: en su frontmatter para apuntar solo a archivos coincidentes. Por ejemplo, limitar las reglas de código de barras a **/Services/** evita que afecten solicitudes no relacionadas.
¿Qué hace que una incidencia sea abordable por el asistente?
Escriba la incidencia y luego asígnela. El cuerpo contiene todas las instrucciones que recibe el asistente, y no habrá nadie para responder preguntas de seguimiento una vez que comience.
Aquí hay una presentada en treinta segundos.
Title: Barcodes not scanning
Some labels don't scan. Can we fix it?
Esta incidencia no proporciona nada concreto: sin referencia de archivo, sin indicación de qué etiquetas están afectadas, sin definición de comportamiento correcto y sin muestra fallida. El asistente adivinará, y puede corregir el problema equivocado.
Aquí está la misma falla escrita de la manera en que lo querría un compañero de equipo.
Title: Returns labels fail to scan at the depot; tracking numbers with lowercase letters
**Files:** Services/LabelService.cs, Services/ScanService.cs
**BarCode version:** as pinned in Directory.Packages.props
**Framework:** .NET 8
**Expected:** Every returns label is a Code 128 barcode, 400 by 120 px with the
value printed below, and reads back to the exact tracking number.
**Actual:** Labels for tracking numbers containing lowercase letters do not read
at the depot. Samples are in TestData/returns-failing/. The same labels read
correctly with IronBarcode on a developer machine. No exception is thrown.
**Constraints:** Do not change the symbology or the public signature of
LabelService.RenderPng. No new packages.
**Acceptance:** Existing tests pass, plus a new round-trip test covering every
file in TestData/returns-failing/ and a lowercase tracking number.
Una incidencia bien definida incluye seis elementos: archivos relevantes, versiones del framework y de la biblioteca, salida esperada específica, comportamiento actual (incluido lo que no ocurre), restricciones claras y criterios de aceptación definidos.
La línea que indica que las etiquetas se decodifican correctamente con IronBarcode le dice al asistente que los códigos de barras son válidos y que la falla se encuentra entre la imagen impresa y los escáneres del depósito, lo que elimina una gran área de búsqueda. Una carpeta de muestras convierte una queja vaga en datos que el asistente puede probar.
Después de la asignación, el asistente se va y vuelve para su revisión. Usted revisa el diff en lugar de verlo trabajar.
¿Por qué fallan las pruebas del asistente en un proyecto de IronBarcode?
El asistente compila y ejecuta pruebas en GitHub en un entorno efímero impulsado por GitHub Actions, en un runner de Ubuntu a menos que usted haya indicado uno de Windows o uno autohospedado. Muchos proyectos solo necesitan el código fuente y una restauración de paquetes allí. Un proyecto de IronBarcode necesita dos extras. Necesita el paquete de plataforma cuyas dependencias nativas coinciden con ese runner, y necesita una clave de licencia. Si falta cualquiera de los dos, cada prueba que escribe o lee un código de barras falla, independientemente de lo que cambie el asistente. Como IronBarcode lanza LicensingException en lugar de agregar una marca de agua, una clave faltante parece una prueba rota, no un secreto faltante.
El asistente culpa a su propio cambio y comienza a editar el código que ya era correcto, y puede seguir haciendo eso durante mucho tiempo.
Evítelo preparando el entorno en .github/workflows/copilot-setup-steps.yml. En lugar de adaptar un flujo de trabajo de otro lugar, describa lo que el runner necesita y deje que Copilot escriba el archivo. Dos requisitos son fáciles de pasar por alto, así que incluya ambos en la solicitud. El trabajo debe llamarse copilot-setup-steps. Y el flujo de trabajo solo se ejecuta una vez que el archivo existe en su rama predeterminada.
#project Write .github/workflows/copilot-setup-steps.yml for this repository.
The job must be named copilot-setup-steps exactly, or it is ignored. Trigger it
manually, and on push and pull request limited to that one file path.
Run it on ubuntu-latest with read access to repository contents. Check out the
repository, set up the .NET SDK for the version this project targets, install
the native dependencies IronBarcode needs on Ubuntu, then restore packages.
For those native dependencies, read
https://ironsoftware.com/barcode/csharp/get-started/linux/ and use what it lists
for Ubuntu rather than a list from memory. Add a comment saying the list can
change between releases.
Give me the finished YAML and nothing else.
Vuelva a leer el archivo antes de guardarlo en un commit. El nombre del trabajo debe coincidir exactamente, la versión del SDK debe coincidir con su proyecto y el paso de instalación de dependencias debe basarse en la guía de Linux, no en una suposición. Fusione el cambio en su rama predeterminada, porque el flujo de trabajo no se ejecuta desde una rama de funcionalidad.
Dos puntos determinan si esto funciona.
Primero, el asistente no recibe automáticamente su clave de licencia. No puede acceder a secretos de Actions, Codespaces o Dependabot. Almacene la clave por separado: en la configuración del repositorio o de la organización, abra Secretos y variables, seleccione la pestaña Agents y agregue IRONBARCODE_LICENSE_KEY. Los secretos de Agents llegan al asistente como variables de entorno, incluso dentro de copilot-setup-steps.yml.
Segundo, Copilot sigue adelante cuando un paso de configuración falla. Omite los pasos restantes y comienza a trabajar con el runner en el estado en que haya quedado. Una instalación de dependencia que falló silenciosamente entonces parece un error de código. Active el flujo de trabajo manualmente desde la pestaña de Actions una vez antes de depender de él.
¿Qué debe verificar antes de fusionar?
Revise la solicitud de extracción del asistente como lo haría con la rama de un compañero. La revisión de código de Copilot puede realizar una primera revisión del resultado y detectar problemas mecánicos antes de que una persona lo lea.
Para cambios en IronBarcode, confirme tres cosas antes de aprobar:
- Todos los nombres de API utilizados aparecen en la documentación: preste especial atención a las enumeraciones de codificación, donde un nombre inventado pero verosímil puede diferir por una sola letra mayúscula.
- Todos los códigos de barras que produce el cambio aún se leen: ni una compilación exitosa ni una revisión de código demuestran que una etiqueta se escanee.
- El cambio se mantuvo dentro de las restricciones que estableció la incidencia: si se le da margen, el asistente a menudo trata una corrección de errores como un permiso para cambiar la simbología o rehacer el patrón de llamada.
Solicite de forma habitual pruebas de ida y vuelta en la misma solicitud de extracción.
/tests Ensure tests are included in the same pull request, not in a subsequent one. A
barcode change without accompanying tests is not reviewable.
Every barcode generated by the service must read back to the value and format it
went in as. An image without a barcode should return no results rather than
throw an exception. All existing samples in TestData/ must read as expected.
Assert on decoded values, not image bytes, and say in the PR description which
of these cases were already covered prior to your change.
Evitar comparaciones de bytes previene pruebas inestables, ya que los codificadores de imagen pueden producir diferentes bytes entre versiones y plataformas incluso cuando el código de barras decodificado permanece idéntico.
¿Está el error en el código o en el escaneo?
Las lecturas fallidas son el motivo de consulta más común entre los usuarios de IronBarcode, y tres causas explican casi todas. Los formatos nunca fueron declarados, por lo que el lector buscó cada simbología que conoce. El símbolo ocupa una fracción de una foto grande. O la captura en sí es deficiente, ya sea borrosa, inclinada o desvaída. Las tres causas corresponden al lado del lector, así que indíquelo en la solicitud.
#project Use the editor's multi-file mode for this scenario, as it spans the reader and the test data.
Warehouse photos in TestData/depot/ come back empty from ScanService, while the
same physical labels read fine on a handheld scanner.
Explain the cause before making any changes. The fix should be applied
only in BarcodeReaderOptions, so expected formats, crop area, speed, and
image filters are in scope, while LabelService.cs is not.
Conclude by reporting how many of those photos were readable before your change
and how many are readable after.
Un diagnóstico le proporciona un razonamiento que puede verificar, en lugar de una edición sin explicación que deba descifrar. Limite también el cambio al lector, o el asistente resolverá un problema de escaneo reimprimiendo cada etiqueta. Tres páginas de documentación cubren los ajustes a los que debería dirigirse, en velocidad, región de recorte y corrección de imagen.
La sección anterior cubre el otro caso. Cuando el código de barras se lee correctamente en su máquina pero falla en un contenedor o runner, rara vez es culpa del código. Pegue la excepción completa, no un resumen, y dirija al asistente al paquete de la plataforma y al Dockerfile en lugar de a la aplicación. Una biblioteca nativa faltante debe incorporarse a la imagen, no al código fuente. Sin restricciones, el asistente puede agregar un try/catch que oculta el fallo sin corregirlo.
¿Qué sigue funcionando cuando nadie está mirando?
Configure dos cosas primero. Las instrucciones en .github/copilot-instructions.md guían al asistente en una rama nocturna al igual que guían a su IDE durante el día. Un copilot-setup-steps.yml que instala las dependencias nativas de IronBarcode, junto con la clave en los secretos de Agents, evita que el asistente depure código que nunca estuvo defectuoso. Todo lo demás es uso ordinario del asistente, y funciona mejor con esos dos elementos preparados.
La revisión es la misma ya sea que ocurra diez segundos después de una sugerencia de autocompletado o la mañana después de una solicitud de extracción, y se evalúa según los criterios establecidos en la guía de asistentes y agentes de programación con IA. Claude Code, ChatGPT Codex, Cursor y Google Antigravity tienen cada uno una guía dedicada.
Solución de problemas
- Aplique una clave de licencia en IronBarcode cuando una solicitud de extracción vuelva con todas las pruebas de códigos de barras en rojo.
- Código de barras no reconocido cuando una etiqueta se escanea en su equipo de escritorio y no en el depósito.
- Paquetes NuGet de IronBarcode para fijar el paquete que debe nombrar su archivo de instrucciones.
- Use IronBarcode en Linux para las dependencias nativas que el runner tiene que instalar.
¿Preguntas?
Si tiene alguna pregunta, contacte 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.