IDE 및 GitHub에서 GitHub Copilot과 함께 IronBarcode 사용하기
IronBarcode 프로젝트는 네이티브 종속성 누락 및 라이선스 키 누락으로 인해 GitHub 실행기에서 실패합니다. Linux 빌드는 해당 종속성을 포함한 플랫폼 패키지가 필요하며, 모든 바코드 호출에 키가 필요합니다. Copilot은 GitHub에서 프로젝트를 빌드할 때 이 두 요구 사항에 직면합니다. 테스트 실패의 원인을 설명하지 못하면 코드에 존재하지 않는 버그를 찾기 시작합니다.
이 작업을 위해 IDE를 벗어날 필요는 없습니다. GitHub Copilot은 Visual Studio, VS Code 및 JetBrains에서 사용할 수 있으므로 기존 솔루션, 프로젝트 참조, NuGet 설정 및 빌드 파이프라인은 그대로 유지됩니다.
IronBarcode에 대한 Copilot 플러그인이 제공되지 않으며, 켜기 위한 설정도 없습니다. Copilot이 바코드에 대해 아는 모든 정보는 저장소에 커밋한 규칙과 제공한 환경에서 나옵니다. 도우미는 한 파일 내에서 크롭 영역 또는 마진 변경을 처리합니다. 충분히 잘 설명되면, PDF에 바코드를 스탬프하는 것이나 GitHub에서 실패한 스캔을 고치는 것도 직접 지켜보지 않아도 가능할 수 있습니다.
IronBarcode의 자체 머신 러닝 감지는 자체 신뢰도 임계값 예제를 가진 별도의 기능이며 아래 내용은 그것을 다루지 않습니다.
빠른 시작이미 사용 중인 어느 IDE든지 열고 프로젝트 컨텍스트에서 이 내용을 Copilot Chat에 넣으세요. Visual Studio에서는 #solution 참조로 요청 범위를 전체 솔루션으로 지정합니다. VS Code에서는 대신 #codebase를 사용하세요.
#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.
예제는 두 번의 호출이 필요합니다. 하나는 심볼을 생성하고 다른 하나는 이름이 지정된 페이지에 스탬프를 찍는 것입니다. PDF에 바코드 스탬프 가이드는 페이지 인덱스와 배치 인수를 다룹니다. 제안에서 둘 다 확인할 수 있어야 합니다. 대안으로, 같은 요청을 GitHub의 도우미에 보내면 분기가 무감독으로 실행되며 풀 요청을 제공합니다. 그러면 준비해야 할 것이 변경됩니다.
시작하기 전에 두 가지 안전점이 있습니다. 라이선스 키 가이드에 설명된 대로 라이선스 키를 구성, 환경 변수 또는 리포지토리 비밀에 저장하여 프롬프트와 커밋에서 제외합니다. 둘째, 쓰기 권한이 Copilot이 실제 풀 요청을 열도록 허용하기 때문에 분기 보호와 인간 검토는 여전히 주요 보호 장치입니다.
5단계 기본 워크플로
- NuGet에서 C# 바코드 라이브러리 다운로드
- 프로젝트의 IronBarcode 관례와 함께
.github/copilot-instructions.md를 커밋하세요. - 작은 수정에는 인라인 채팅을 사용하고, 더 큰 수정에는 편집기의 다중 파일 모드를 사용하세요
- 무감독 작업에는 세부적인 이슈를 작성하여 GitHub의 도우미에게 전달하세요
- 풀 요청을 검토하고 API 레퍼런스와 일치하는 모든 API 이름을 확인하세요
Copilot이 Visual Studio에 이미 있는 프로젝트에 맞는 곳은 어디입니까?
Copilot은 세 가지 수준에서 작동하며, 각 수준에서 범위가 넓어집니다.
인라인 완료와 채팅은 편집기에 있습니다. 이들은 심볼로지 전환, 마진 추가, 리더를 하나의 형식으로 제한 등 하나의 파일 내에서 단일 문장으로 설명할 수 있는 변경 사항에 가장 적합합니다. 변경 사항을 설명하고, 결과 diff를 검토하고, 수락하거나 무시할 지 선택하세요.
편집기의 다중 파일 모드는 여러 파일에 걸친 변경 사항을 처리합니다. 파일을 선택하고 터미널 명령을 실행하며 결과를 검토하고 오류를 반복적으로 수정합니다. 마이그레이션과 리팩토링에 사용하세요.
GitHub의 도우미는 직접 감독하고 싶지 않은 작업을 관리합니다. 문제를 통해 지침을 제공하고 나중에 분기와 풀 요청을 받습니다. IDE 내부 기능으로는 이런 작업을 수행할 수 없으므로, 이후 내용은 주로 GitHub에서의 작업 모드를 다룹니다.
세 가지 모두 문서를 잘 읽습니다. API 레퍼런스로 직접 안내하고, 프로젝트가 기본값으로 남기는 BarcodeReaderOptions이 무엇인지 물어보면 직접 정보를 모으지 않고도 답을 얻을 수 있습니다.
모든 인터페이스에 적용할 규칙은 어떻게 커밋합니까?
사용자 정의 지침은 리포지토리에 존재하며, 이는 IDE 제안과 무감독 실행을 모두 형성합니다. 한 번 작성하고 프롬프트에서 반복하지 마세요.
.github/copilot-instructions.md을 사용하세요. 이는 리포지토리 전체의 파일이며, IDE, GitHub, Copilot 코드 검토 모두에 적용됩니다. IronBarcode가 여러 리포지토리에 걸쳐 표준이라면 대신 조직 맞춤형 지침으로 규칙을 한 번 설정하세요. Copilot Business나 Enterprise 요금제의 조직 소유자는 그렇게 할 수 있으며, 그러한 지침은 github.com의 Copilot Chat, Copilot 코드 검토, 무감독 작업에 도달합니다. Copilot은 디렉터리 트리에서 가장 가까운 파일이 우선 적용되는 AGENTS.md를 읽고, 루트에서 단일 CLAUDE.md 또는 GEMINI.md를 읽습니다. 리포지토리가 이미 다른 도구에 AGENTS.md 형식의 바코드 규칙을 유지하고 있다면, Copilot은 이를 존중하고 두 번째 복사본이 필요하지 않습니다.
# 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.
모델은 불확실성을 인정하기보다는 자신감 있는 답을 제공하는 경향이 있으며, BarcodeScanner.DecodeImageFile() 같은 호출이 유효해 보일 수 있지만 빌드가 실패할 때까지입니다. 모델이 불확실할 때 멈추도록 허용하는 것은 비용이 들지 않으며, 발명된 API가 diff에 포함되지 않도록 합니다.
보다 구체적인 규칙을 위해 .github/instructions/에 파일을 something.instructions.md으로 이름을 지정하여 배치하세요. 일치하는 파일만 대상으로 하는 applyTo: 글로브를 프런트매터에 사용하세요. 예를 들어, **/Services/**에 바코드 규칙을 범위로 설정하면 관련 없는 요청에 영향을 미치지 않도록 합니다.
도우미가 실행할 수 있는 문제는 무엇입니까?
문제를 작성한 다음 할당합니다. 본문은 도우미에게 제공되는 전체 작업 지침이며, 시작되면 후속 질문에 대답할 사람이 없습니다.
여기 30초 만에 제출된 것이 있습니다.
Title: Barcodes not scanning
Some labels don't scan. Can we fix it?
이 문제는 구체적인 것을 제공하지 않습니다. 파일 참조도 없고, 영향을 받는 레이블의 표시도 없고, 올바른 동작에 대한 정의도 없으며, 실패한 샘플도 없습니다. 도우미가 추측하며, 잘못된 것을 수정할 수 있습니다.
동일한 버그를 팀원이 작업하기에 적합한 방식으로 작성하면 다음과 같습니다.
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.
잘 정의된 문제는 다음과 같은 여섯 가지 요소를 포함합니다: 관련 파일, 프레임워크 및 라이브러리 버전, 구체적인 예상 출력, 실제 동작(발생하지 않는 것을 포함), 명확한 제한 조건, 및 정의된 승인 기준.
IronBarcode로 레이블이 올바르게 디코딩된다는 설명은 바코드가 유효하고 결함이 인쇄된 이미지와 창고 스캐너 사이에 있다는 것을 도우미에게 알려줍니다. 이는 검색 영역을 크게 줄입니다. 샘플 폴더는 모호한 불만을 도우미가 테스트할 수 있는 데이터로 변환합니다.
할당 후, 도우미는 작업을 마치고 검토를 위해 돌아옵니다. 작업하는 모습을 보는 대신 diff를 확인합니다.
왜 IronBarcode 프로젝트에서 도우미의 테스트가 실패합니까?
도우미는 GitHub Actions 기반의 임시 환경에서 빌드와 테스트를 수행합니다. Windows 또는 자체 호스팅 실행기를 지정하지 않으면 Ubuntu 실행기를 사용합니다. 많은 프로젝트는 그곳에서 소스와 패키지 복원만 필요합니다. IronBarcode 프로젝트는 두 가지가 추가로 필요합니다. 해당 실행기에 맞는 네이티브 종속성을 가진 플랫폼 패키지와 라이선스 키가 필요합니다. 둘 중 하나가 없으면, 도우미가 변경한 것과 상관없이 바코드를 읽거나 쓰는 모든 테스트가 실패합니다. IronBarcode는 워터마크를 대신하여 LicensingException라는 예외를 던지기 때문에 키가 누락될 경우는 누락된 비밀이 아니라 깨진 테스트처럼 보입니다.
도우미는 자신의 변경 사항이 원인이라고 판단하여 이미 올바른 코드를 수정하기 시작하며, 이런 작업을 오랫동안 반복할 수 있습니다.
환경을 .github/workflows/copilot-setup-steps.yml에 준비하여 이를 방지하세요. 다른 곳에서 워크플로를 적응시키는 대신, 실행기가 필요한 것을 설명하고 Copilot이 파일을 작성하도록 하세요. 두 가지 요구사항은 놓치기 쉬우므로 두 가지를 요청에 포함하세요. 작업 이름은 copilot-setup-steps로 지정해야 합니다. 파일이 기본 분기에 존재할 때만 워크플로가 실행됩니다.
#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.
커밋하기 전에 파일을 다시 읽어보세요. 작업 이름이 정확히 일치해야 하며, SDK 버전이 프로젝트와 일치해야 하며, 종속성 단계는 Linux 가이드를 추적해야 하며 추측에 의존하지 않아야 합니다. 기본 분기로 병합하세요, 왜냐하면 워크플로가 기능 분기에서 실행되지 않기 때문입니다.
두 가지 점이 작동 여부를 결정합니다.
첫째, 도우미는 자동으로 라이선스 키를 받지 않습니다. Actions, Codespaces, 또는 Dependabot 비밀에 접근할 수 없습니다. 라이선스 키를 별도로 저장하세요: 리포지토리 또는 조직 설정에서 Secrets and variables를 열고, Agents 탭을 선택하여 IRONBARCODE_LICENSE_KEY를 추가하세요. Agents 비밀 값은 copilot-setup-steps.yml 실행 중에도 환경 변수로 도우미에게 전달됩니다.
둘째, Copilot은 설정 단계가 실패할 때 계속 진행됩니다. 남은 단계를 건너뛰고 실행기가 있는 상태에서 작업을 시작합니다. 조용히 실패한 종속성 설치는 그 후 정확히 코드 버그처럼 보입니다. 의존하기 전에 한 번 Actions 탭에서 수동으로 워크플로를 트리거하세요.
병합 전에 무엇을 확인해야 합니까?
팀원의 분기를 검토하듯 도우미의 풀 요청을 검토하세요. Copilot 코드 검토는 사람이 읽기 전에 출력을 첫 번째로 검사하고 기계적 문제를 잡을 수 있습니다.
IronBarcode 변경을 승인하기 전에 세 가지를 확인하세요.
- 사용된 모든 API 이름이 문서에 나타납니다: 대문자 한 글자로 차이가 나는 그럴듯한 가짜 인코딩 열거형에 특히 주의하세요.
- 변경이 만들어내는 모든 바코드는 여전히 읽을 수 있어야 합니다: 빌드 통과나 코드 검토가 레이블이 스캔된다는 것을 증명하지 않습니다.
- 변경 사항은 이슈에 설정된 제한 조건 내에 머물렀습니다: 여유를 주면, 도우미는 버그 수정을 심볼로지 변경 또는 호출 패턴 재작업 권한으로 처리할 수 있습니다.
왕복 테스트를 동일한 풀 요청에 표준 요청으로 만드세요.
/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.
이미지 인코더는 디코딩된 바코드가 같아도 버전과 플랫폼에 따라 다른 바이트를 생성할 수 있습니다. 바이트 비교를 피하면 이로 인한 불안정한 테스트를 방지할 수 있습니다.
코드에 결함이 있나요 아니면 스캔에 결함이 있나요?
실패한 읽기는 IronBarcode 사용자가 가장 자주 묻는 질문이며 거의 모든 원인이 세 가지 때문입니다. 형식을 지정하지 않아 리더가 지원하는 모든 심볼로지를 검색했습니다. 심볼은 큰 사진의 일부분을 차지합니다. 또는 캡처 자체가 흐릿하거나, 기울어져 있거나, 바랜 상태입니다. 세 가지 모두 리더 측에서 처리할 문제이므로 요청에 이를 명시하십시오.
#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.
진단을 먼저 요청하면 설명 없이 수정된 코드를 분석하는 대신 원인에 대한 추론을 검토할 수 있습니다. 수정 범위도 리더로 제한하십시오. 그렇지 않으면 도우미는 모든 레이블을 다시 인쇄하는 방식으로 스캔 문제를 해결하려 할 수 있습니다. 사용해야 할 설정은 다음 세 문서에서 설명합니다: 속도, 크롭 영역, 이미지 수정입니다.
이전 섹션에서 다른 경우를 다룹니다. 코드가 로컬 머신에서는 제대로 읽히지만, 컨테이너나 실행기에서 실패할 때, 코드는 거의 문제가 아닙니다. 전체 예외를 붙여넣고, 애플리케이션 대신 플랫폼 패키지 및 Dockerfile로 도우미를 지시하세요. 누락된 네이티브 라이브러리는 소스가 아닌 이미지에 속합니다. 제한 없이 두면, 실패를 숨긴 채로 해결하지 않고 try/catch를 추가할 수 있습니다.
아무도 지켜보지 않을 때 무엇이 계속 작동합니까?
두 가지를 먼저 설정하세요. .github/copilot-instructions.md의 지침이 도우미에게 밤새 분기를 안내하듯, 낮 동안 IDE를 안내합니다. IronBarcode의 네이티브 종속성을 설치하는 copilot-setup-steps.yml과 에이전트의 비밀 값으로 저장한 키는 원래 문제가 없던 코드를 디버깅하는 일을 방지합니다. 그 밖의 모든 것은 평범한 도우미 사용이며, 그 두 가지가 설정되어 있으면 더 잘 됩니다.
완료 10초 후나 풀 요청 다음날 아침이나 리뷰는 동일하며, AI 코딩 도우미 및 에이전트 가이드의 고정 기준에 대해 점수가 매겨집니다. Claude Code, ChatGPT Codex, Cursor, 및 Google Antigravity 각각 전용 안내가 있습니다.
문제 해결
- 풀 요청의 모든 바코드 테스트가 실패할 때 IronBarcode에 라이선스 키 적용.
- 책상에서는 레이블이 스캔되나 창고에서는 스캔되지 않을 때, 바코드 인식되지 않음.
- 지침 파일에 명시할 패키지 버전을 고정하려면 IronBarcode NuGet 패키지 가이드를 참조하십시오.
- 실행기가 설치해야 하는 네이티브 종속성에 대한 Linux에서 IronBarcode 사용하기.
질문?
질문이 있으시면 support@ironsoftware.com으로 문의하세요.
커티스 차우는 칼턴 대학교에서 컴퓨터 과학 학사 학위를 취득했으며, Node.js, TypeScript, JavaScript, React를 전문으로 하는 프론트엔드 개발자입니다. 직관적이고 미적으로 뛰어난 사용자 인터페이스를 만드는 데 열정을 가진 그는 최신 프레임워크를 활용하고, 잘 구성되고 시각적으로 매력적인 매뉴얼을 제작하는 것을 즐깁니다.