Usando IronBarcode com GitHub Copilot, no IDE e no GitHub
Os projetos do IronBarcode falham nos runners do GitHub devido à ausência de dependências nativas e chaves de licença. A build do Linux precisa de um pacote de plataforma que contenha essas dependências, e toda chamada de código de barras precisa de uma chave. O Copilot se depara com esses dois requisitos quando compila seu projeto no GitHub, e testes que falham sem explicação o levam a caçar um bug que nunca esteve no código.
Nada disso requer sair do seu IDE. O GitHub Copilot está disponível no Visual Studio, VS Code e JetBrains, então sua solução existente, referências de projeto, configurações do NuGet e pipeline de build permanecem onde estão.
Nenhum plugin do Copilot é fornecido para IronBarcode, e não há configuração para ativar. Tudo o que o Copilot sabe sobre códigos de barras vem do repositório, das convenções que você salva em commits lá e do ambiente que você entrega. O assistente lida com uma região de corte ou uma alteração de margem dentro de um arquivo. Bem informado, ele pode carimbar códigos de barras em um PDF ou corrigir uma falha de leitura no GitHub sem precisar de sua supervisão.
A detecção por aprendizado de máquina do próprio IronBarcode é um recurso separado, com seu próprio exemplo de limiar de confiança, e nada aqui afeta isso.
Início RápidoAbra sua solução em qualquer IDE que você já use e utilize o Copilot Chat com o projeto no contexto. #solution é a referência do Visual Studio que delimita uma solicitação para toda a solução. No VS Code, use #codebase em vez disso.
#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.
O exemplo requer duas chamadas, uma para criar o símbolo e outra para carimbá-lo na página que você especifica, e o guia de carimbos de códigos de barras em PDFs cobre o índice da página e os argumentos de posicionamento. As duas chamadas devem aparecer na sugestão. Alternativamente, você pode enviar a mesma solicitação para o assistente no GitHub, que será executado sem supervisão em um branch e entregará um pull request. Isso muda o que você precisa preparar.
Dois pontos de segurança antes de começar. Primeiro, mantenha as chaves de licença fora de prompts e commits armazenando-as em configurações, variáveis de ambiente ou segredos do repositório, conforme descrito no guia de chaves de licença. Segundo, lembre-se de que o acesso de gravação permite ao Copilot abrir pull requests reais, então a proteção de branch e a revisão humana continuam sendo sua principal salvaguarda.
Fluxo de trabalho mínimo em 5 passos
- Baixe a biblioteca de códigos de barras C# do NuGet
- Faça commit de
.github/copilot-instructions.mdcom as convenções do IronBarcode do projeto. - Use o chat inline para pequenas edições e o modo multi-arquivo do editor para edições maiores.
- Para trabalho não supervisionado, abra uma issue detalhada e entregue-a ao assistente no GitHub.
- Revise o pull request, verificando todos os nomes de API contra a referência de API.
Onde o Copilot se encaixa em um projeto já no Visual Studio?
O Copilot opera em três níveis, e o escopo se expande em cada um.
Sugestões de preenchimento de código e chat inline ficam no editor. Esses recursos são mais adequados para mudanças que podem ser descritas em uma única frase dentro de um arquivo, como mudar simbologia, adicionar uma margem ou limitar um leitor a um formato. Você descreve a mudança, revisa a diferença resultante e escolhe aceitar ou descartá-la.
O modo multi-arquivo do editor assume mudanças que abrangem vários arquivos. Ele seleciona os arquivos, executa comandos de terminal, revisa resultados e itera sobre erros. Use-o para migrações e refatoração.
O assistente no GitHub gerencia tarefas que você não deseja supervisionar diretamente. Você fornece instruções por meio de uma issue e, mais tarde, recebe um branch e um pull request. Nada vinculado ao editor pode fazer isso, então a maior parte do que segue diz respeito a esse modo.
Os três consultam bem a documentação. Direcione um para a referência de API, pergunte quais opções de BarcodeReaderOptions seu projeto mantém nos valores padrão e a resposta vem sem que seja preciso reunir as informações manualmente.
Como salvar em commits convenções seguidas em todas as interfaces?
Instruções personalizadas vivem no repositório, então elas moldam sugestões de IDE e execuções não supervisionadas de forma igual. Escreva-as uma vez e pare de repeti-las em prompts.
Use .github/copilot-instructions.md. É o arquivo do repositório inteiro, e se aplica nos IDEs, no GitHub e na revisão de código do Copilot. Se o IronBarcode for o padrão em mais de um repositório, defina as regras uma vez como instruções personalizadas da organização. Um proprietário de organização em um plano Business ou Enterprise do Copilot pode fazer isso, e essas instruções alcançam o Copilot Chat no github.com, a revisão de código do Copilot e o trabalho não supervisionado lá. O Copilot também lê AGENTS.md em qualquer lugar na árvore, com o arquivo mais próximo vencendo, além de um único CLAUDE.md ou GEMINI.md na raiz. Se seu repositório já mantém regras de código de barras em AGENTS.md para outra ferramenta, o Copilot as respeita e você não precisa de uma segunda cópia.
# 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.
Os modelos tendem a fornecer respostas confiantes em vez de admitir incertezas, então uma chamada como BarcodeScanner.DecodeImageFile() pode parecer válida até que a build falhe. Permitir que o modelo pare quando incerto não custa nada e mantém APIs inventadas fora do diff.
Para regras mais específicas, coloque um arquivo em .github/instructions/ chamado something.instructions.md. Use um padrão glob applyTo: no frontmatter para direcionar apenas arquivos correspondentes. Por exemplo, delimitar regras de códigos de barras para **/Services/** impede que elas afetem solicitações não relacionadas.
O que uma issue precisa conter para que o assistente possa agir?
Você escreve a issue e a atribui ao assistente. O corpo é o briefing inteiro do assistente, e ninguém está disponível para responder a perguntas adicionais depois que o trabalho começa.
Veja uma issue aberta em trinta segundos.
Title: Barcodes not scanning
Some labels don't scan. Can we fix it?
Esta issue não fornece nada concreto: sem referência de arquivo, sem indicação de quais rótulos são afetados, sem definição de comportamento correto e sem amostra falhando. O assistente adivinhará, e pode corrigir a coisa errada.
Aqui está a mesma falha escrita da maneira que um colega de equipe gostaria.
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.
Uma issue bem definida inclui seis elementos: arquivos relevantes, versões de framework e biblioteca, saída esperada específica, comportamento real (incluindo o que não ocorre), restrições claras e critérios de aceitação definidos.
A informação de que as etiquetas são decodificadas corretamente com IronBarcode mostra ao assistente que os códigos de barras são válidos e a falha está entre a imagem impressa e os scanners do depósito, o que elimina uma grande área da busca. Uma pasta de amostras transforma uma reclamação vaga em dados que o assistente pode testar.
Após a atribuição, o assistente executa a tarefa e retorna para revisão. Você verifica o diff em vez de acompanhar o trabalho.
Por que os testes do assistente falham em um projeto IronBarcode?
O assistente compila e testa no GitHub em um ambiente efêmero executado pelo GitHub Actions, em um runner Ubuntu a menos que você o tenha direcionado a um runner Windows ou auto-hospedado. Muitos projetos precisam apenas do código-fonte e de uma restauração de pacotes nesse ambiente. Um projeto IronBarcode precisa de dois extras. Ele precisa do pacote de plataforma cujas dependências nativas correspondam a esse runner, e precisa de uma chave de licença. Se qualquer um dos dois estiver ausente, todo teste que escreve ou lê um código de barras falha, independentemente do que o assistente mudou. Porque o IronBarcode lança LicensingException em vez de adicionar uma marca d'água, uma chave ausente parece um teste quebrado, não um segredo faltando.
O assistente culpa sua própria mudança e começa a editar código que já estava correto, e pode continuar fazendo isso por muito tempo.
Impeça isso preparando o ambiente em .github/workflows/copilot-setup-steps.yml. Em vez de adaptar um fluxo de trabalho de outro lugar, descreva o que o runner precisa e deixe o Copilot escrever o arquivo. Dois requisitos são fáceis de esquecer, então coloque ambos na solicitação. O job deve ter o nome copilot-setup-steps. E o fluxo de trabalho só é executado uma vez que o arquivo exista no seu branch padrão.
#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.
Leia o arquivo antes de fazer o commit. O nome do job deve corresponder exatamente, a versão do SDK deve corresponder ao seu projeto e a etapa de instalação de dependências deve seguir o guia do Linux em vez de se basear em um palpite. Faça o merge no seu branch padrão, porque o fluxo de trabalho não é executado a partir de um branch de funcionalidade.
Dois pontos determinam se isso funciona.
Primeiro, o assistente não recebe automaticamente sua chave de licença. Ele não pode acessar segredos de Actions, Codespaces ou Dependabot. Armazene a chave separadamente: nas configurações do repositório ou da organização, abra Segredos e variáveis, selecione a guia Agentes e adicione IRONBARCODE_LICENSE_KEY. Segredos de agentes chegam ao assistente como variáveis de ambiente, inclusive dentro de copilot-setup-steps.yml.
Segundo, o Copilot continua mesmo quando uma etapa de configuração falha. Ele pula as etapas restantes e começa o trabalho no estado em que o runner se encontra. Uma instalação de dependência que falhou silenciosamente então parece exatamente como um bug de código. Acione o fluxo de trabalho manualmente na guia Actions uma vez antes de depender dele.
O que você deve verificar antes de fazer o merge?
Revise o pull request do assistente como você faria com o branch de um colega. A revisão de código do Copilot pode fazer uma primeira passagem sobre a saída e capturar problemas mecânicos antes que uma pessoa o leia.
Para mudanças do IronBarcode, confirme três coisas antes de aprovar:
- Todo nome de API usado aparece na documentação: preste atenção especial a enums de codificação, em que um nome inventado, mas plausível, pode diferir por uma única letra maiúscula.
- Todo código de barras produzido pela alteração continua sendo lido corretamente: nem uma build bem-sucedida nem uma revisão de código provam que um rótulo é escaneado.
- A alteração permaneceu dentro das restrições definidas na issue: dado espaço, o assistente muitas vezes trata uma correção de bug como permissão para mudar simbologia ou reformular o padrão de chamada.
Solicite testes de ida e volta como parte padrão do mesmo pull request.
/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 comparações de bytes previne testes instáveis, pois codificadores de imagem podem produzir bytes diferentes em versões e plataformas, mesmo quando o código de barras decodificado permanece idêntico.
A falha está no código ou na leitura?
Falhas de leitura são a dúvida mais comum dos usuários do IronBarcode, e três causas representam quase todas elas. Os formatos nunca foram declarados, então o leitor procurou cada simbologia que conhece. O símbolo ocupa uma fração de uma foto grande. Ou a própria captura tem problemas: a imagem está desfocada, inclinada ou desbotada. As três causas estão do lado do leitor, então diga isso na solicitação.
#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.
Um diagnóstico fornece um raciocínio para verificar em vez de uma edição inexplicada para desvendar. Restrinja também a alteração ao leitor, ou o assistente resolverá um problema de leitura reimprimindo cada rótulo. Três páginas de documentação cobrem as configurações que o assistente deve usar, sobre velocidade, região de corte e correção de imagem.
A seção anterior cobre o outro caso. Quando o código lê corretamente na sua máquina, mas falha em um contêiner ou runner, o código raramente é o culpado. Cole a exceção completa, não um resumo, e direcione o assistente para o pacote de plataforma e o Dockerfile em vez da aplicação. A ausência de uma biblioteca nativa deve ser corrigida na imagem, não no código-fonte. Sem restrições, o assistente pode adicionar um try/catch que esconde a falha sem corrigi-la.
O que continua funcionando quando ninguém está assistindo?
Configure duas coisas primeiro. Instruções em .github/copilot-instructions.md guiam o assistente em um branch noturno, como guiam seu IDE durante o dia. Um copilot-setup-steps.yml que instala dependências nativas do IronBarcode, junto com a chave em segredos de Agentes, impede que ele depure código que nunca foi quebrado. Todo o resto é uso habitual do assistente, e tudo corre melhor com essas duas coisas em funcionamento.
A revisão é a mesma, seja ela feita dez segundos depois de uma sugestão de preenchimento de código ou na manhã seguinte a um pull request, e é avaliada pelos critérios fixos do guia de assistentes e agentes de codificação assistida por IA. Claude Code, ChatGPT Codex, Cursor e Google Antigravity têm orientações dedicadas.
Solução de problemas
- Aplique uma Chave de Licença no IronBarcode quando um pull request voltar com todos os testes de código de barras em vermelho.
- Código de Barras Não Reconhecido quando um rótulo é escaneado na sua mesa, mas não no depósito.
- Pacotes NuGet do IronBarcode para fixar o pacote que seu arquivo de instruções deve nomear.
- Use IronBarcode no Linux para as dependências nativas que o runner deve instalar.
Dúvidas?
Se você tiver dúvidas, entre em contato com support@ironsoftware.com
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.