IronBarcode を GitHub Copilot と併用する方法(IDE 内および GitHub 上で)

Curtis Chau
Curtis Chau
更新日: 2026年9月21日

IronBarcode プロジェクトは、ネイティブ依存関係の欠如とライセンスキーの不足により、GitHub ランナーで失敗します。 Linux ビルドでは、それらの依存関係を含むプラットフォームパッケージが必要であり、すべてのバーコード呼び出しにキーが必要です。 CopilotはGitHubでプロジェクトをビルドする際にこの両方の問題に直面し、テスト失敗の理由が分からないと、コードに存在しないバグを探し始めます。

これらすべてを IDE を離れることなく実行できます。GitHub Copilot は、Visual Studio、VS Code、および JetBrains で利用可能なので、既存のソリューション、プロジェクト参照、NuGet 設定、およびビルドパイプラインはそのままにしておくことができます。

IronBarcode 用の Copilot プラグインは出荷されておらず、オンにするための設定もありません。 Copilot がバーコードについて知っていることはすべて、リポジトリ、そこでコミットした規約、および提供された環境から得られます。 アシスタントは、クロップ領域や 1 つのファイル内の余白の変更を処理します。十分に説明されていれば、PDF にバーコードをスタンプしたり、GitHub 上で失敗したスキャンを改善したりすることが可能です。

IronBarcode 独自の機械学習による検出は、別の機能として提供されており、その信頼閾値の例も含まれていますが、ここではそれに触れていません。

クイックスタート
NuGetNuGet でインストール

PM > Install-Package BarCode

NuGetパッケージマネージャーコンソールで上記のコマンドを実行するか、NuGetパッケージマネージャーでパッケージを検索して、IronBarcodeをインストールします。

既に使用している任意の IDE でソリューションを開いて、プロジェクトをコンテキストに加えて Copilot Chat にこれを伝えてください。 #solution は、リクエストをソリューション全体にスコープするための Visual Studio 参照です。 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.
Text

例では、シンボルを作成するための 1 つの呼び出しと、名前を指定したページにスタンプを押すための 1 つの呼び出しの 2 つが必要で、PDF にバーコードをスタンプするガイドではページ索引と配置の引数が取り扱われています。 提案でその双方を確認できます。 あるいは、GitHub 上のアシスタントに同じ要求を送ることもできます。これにより、ブランチ上で監督なしに作業が実行され、プルリクエストが届きます。それで準備が変わります。

始める前に 2 つの安全ポイントがあります。 まず、ライセンスキーをプロンプトやコミットに含めないように注意し、ライセンスキーガイドに従って、設定・環境変数・リポジトリのシークレットとして保存します。 次に、書き込みアクセスが Copilot に実際のプルリクエストを開かせることを忘れないでください。そのため、ブランチ保護と人間によるレビューが主要な安全策となります。



Copilot は既に Visual Studio にあるプロジェクトにどのようにフィットしますか?

Copilot は 3 つのレベルで操作しますが、各レベルでスコープが広がります。

インライン補完とチャットはエディター内にあります。 それらは、シンボロジーの切り替え、余白の追加、リーダーを 1 つの形式に限定するなど、1 つのファイル内で 1 つのステートメントで説明可能な変更に最適です。 変更を説明し、結果の diff をレビューし、受け入れるか破棄するかを選択します。

エディターのマルチファイルモードは、複数のファイルにわたる変更を引き受けます。 ファイルを選択し、ターミナルコマンドを実行し、結果をレビューし、エラーを繰り返し解決します。 移行やリファクタリングに使用してください。

GitHub 上のアシスタントは、直接監督したくないタスクを管理します。 問題を通じて指示を提供し、後でブランチとプルリクエストを受け取ります。エディターに結びついたものではできませんので、以降は主にそのモードに関するものです。

3つのモードはすべて、ドキュメントを適切に読み取れます。 API リファレンスを参照させ、プロジェクト内でデフォルトのままになっているBarcodeReaderOptionsの設定を質問すれば、手作業で情報を集めずに回答を得られます。

すべてのインターフェースに適用する規約をコミットするには?

カスタム指示はリポジトリに置くため、IDEの提案にも、監督なしでの実行にも適用されます。一度記述すれば、プロンプトで繰り返す必要はありません。

.github/copilot-instructions.md を使用してください。 これはリポジトリ全体のファイルであり、IDE、GitHub、Copilot のコードレビューに適用されます。 IronBarcode が複数のリポジトリで標準となっている場合、組織のカスタム指示としてルールを 1 回設定します。 Copilot Business または Enterprise プランの組織オーナーはこれを行うことができ、その指示は github.com の Copilot Chat、Copilot コードレビュー、無人作業に届きます。 Copilot は AGENTS.md をツリー内の任意の場所で読み込み、最も近いファイルが優先され、さらにルートにある単一のCLAUDE.mdまたはGEMINI.mdも読み込みます。 リポジトリがすでに別のツールのために AGENTS.md にバーコードルールを保持している場合、Copilot はそれを尊重し、2 番目のコピーは不要です。

# 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.
Markdown

モデルは不確かであると認めるよりも、自信のある回答を返す傾向があります。そのため、BarcodeScanner.DecodeImageFile()のような呼び出しも、ビルドに失敗するまでは有効に見えることがあります。不確かなときは停止してよいと指示しておけば、コストをかけずに、実在しないAPIが差分に混入するのを防げます。

より具体的なルールは、.github/instructions/にsomething.instructions.mdという名前のファイルを配置して記述します。フロントマターのapplyTo:グロブで、一致するファイルのみを対象にします。例えば、バーコードのルールを**/Services/**に限定すれば、無関係なリクエストへの影響を防げます。

アシスタントが実行できるIssueを書くには?

Issueを記述してアシスタントに割り当てます。本文が指示のすべてとなり、作業開始後に追加の質問に答える人はいません。

次は、30秒で作成したIssueの例です。

Title: Barcodes not scanning

Some labels don't scan. Can we fix it?
Markdown

この問題は具体的な情報を提供しません。ファイル参照も、影響を受けるラベルも、正しい動作の定義も、失敗しているサンプルもありません。 アシスタントは推測し、間違ったものを修正するかもしれません。

同じ不具合を、チームメイトが必要とする情報を含めて書き直すと、次のようになります。

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.
Markdown

よく定義された問題は、6 つの要素を含みます:関連するファイル、フレームワークおよびライブラリのバージョン、具体的な期待される出力、実際の動作(何が起こらないかを含む)、明確な制約、定義された受け入れ基準。

IronBarcodeではラベルを正しくデコードできるという記述により、バーコード自体は有効で、印刷画像と配送拠点のスキャナーの間に原因があるとアシスタントに伝わります。これにより、調査範囲を大幅に絞れます。サンプルフォルダーを示すことで、曖昧な報告がテスト可能なデータになります。

割り当て後はアシスタントが作業を進め、完了するとレビューを求めます。作業中の様子を監視する代わりに、差分を確認します。

なぜアシスタントのテストは IronBarcode プロジェクトで失敗するのか?

アシスタントは、GitHub Actions によって駆動される一時的な環境で GitHub 上でビルドとテストを行いますが、Windows または自己ホスト型のランナーへの指示がない限り、Ubuntu ランナーで行われます。 多くのプロジェクトは、そこでのソースとパッケージのリストアのみを必要とします。 IronBarcode プロジェクトには 2 つの追加が必要です。 そのランナーに一致するネイティブ依存関係を持つプラットフォームパッケージと、ライセンスキーが必要です。 どちらが欠けていても、アシスタントが変更した内容に関係なく、バーコードの読み書きテストはすべて失敗します。 IronBarcode が透かしを入れる代わりに LicensingException を投げるため、キーが欠けている場合、壊れたテストであるかのように見えます。

アシスタントは自身の変更が原因だと考え、元から正しかったコードを編集し始めます。その状態が長く続くこともあります。

これを防ぐには、.github/workflows/copilot-setup-steps.ymlで環境を準備します。別のワークフローを流用する代わりに、ランナーに必要なものを説明し、Copilotにファイルを作成させます。見落としやすい2つの要件を、両方ともリクエストに含めてください。ジョブ名は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.
Text

コミット前にファイルを読み返してください。ジョブ名は完全に一致し、SDKのバージョンはプロジェクトと一致している必要があります。依存関係のインストール手順は、推測ではなくLinuxガイドを根拠にしてください。ワークフローはフィーチャーブランチからは実行されないため、デフォルトブランチにマージします。

2 つのポイントがこれがうまくいくかどうかを決定します。

まず、アシスタントはライセンスキーを自動では受け取りません。Actions、Codespaces、Dependabotのシークレットにはアクセスできません。キーは別途保存します。リポジトリまたは組織の設定で[Secrets and variables]を開き、Agentsタブを選択して、IRONBARCODE_LICENSE_KEYを追加してください。Agentsのシークレットは環境変数としてアシスタントに渡され、copilot-setup-steps.yml内でも利用できます。

次に、セットアップステップが失敗してもCopilotは処理を続けます。残りのステップをスキップし、その時点のランナーの状態で作業を開始します。気付かないうちに依存関係のインストールが失敗すると、コードの不具合と見分けがつかなくなります。運用する前に、Actionsタブからワークフローを一度手動で実行してください。

ヒント: プルリクエストでバーコードテストが失敗する場合、問題をコード変更に割り当てる前にランナー環境とライセンスシークレットを確認してください。 プラットフォーム要件については、Linux 設定ガイドとNuGet パッケージガイドを参照してください。記憶に頼らないでください。

マージする前に何を確認すべきですか?

チームメイトのブランチと同じように、アシスタントのプルリクエストをレビューします。 Copilot コードレビューは、出力を一巡して機械的な問題を人間が読む前にキャッチできます。

IronBarcode の変更について、承認する前に 3 つのことを確認してください:

  • 使用したすべてのAPI名がドキュメントにある:エンコーディングの列挙型は特に注意して確認してください。もっともらしい架空の名前が、大文字1文字だけ異なる場合があります。
  • 変更によって生成されたすべてのバーコードがまだ読み取れる:ビルドが通ることも、コードレビューが済むことも、ラベルがスキャンされることを証明しません。
  • 変更がIssueで定めた制約内に収まっている:制約が緩いと、アシスタントはバグ修正を、シンボロジーの変更や呼び出しパターンの再構成まで許可されたものと解釈しがちです。

ラウンドトリップテストを同じプルリクエストに含めることを、標準の要求にしてください。

/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.
Text

画像エンコーダーは、デコードされるバーコードが同じでも、バージョンやプラットフォームによって異なるバイト列を生成することがあります。バイト列の比較を避ければ、それによるテストの不安定化を防げます。

コードの不具合なのか、スキャンの不具合なのか?

読み取りの失敗はIronBarcodeのユーザーから最も多く寄せられる質問で、そのほとんどは3つの原因に当てはまります。形式を指定していないため、リーダーが対応するすべてのシンボロジーを探索している場合、バーコードが大きな写真のごく一部しか占めていない場合、そしてぼけ、傾き、白飛びなどで撮影品質が低い場合です。いずれも読み取り側の問題なので、リクエストでその旨を明示してください。

#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.
Text

診断を求めれば、説明のない編集の意図を解き明かす代わりに、その根拠を確認できます。変更範囲も読み取り側に限定してください。さもないと、アシスタントはすべてのラベルを再印刷することでスキャンの問題を解決することになります。 3 つのドキュメンテーションページは、速度、クロップ領域、画像補正の設定をカバーしています。

以前のセクションでは、他のケースをカバーしています。 コードが自分のマシンで正しく読み取れる場合でも、コンテナやランナーでは失敗する場合、コードが原因であることはめったにありません。 要約ではなく、完全な例外を貼り付け、アプリケーションではなくプラットフォームパッケージや Dockerfile を直接指示してください。 ネイティブライブラリが不足しているのはイメージであり、ソースではありません。 制約しなければ、失敗を隠して修正しない try/catch を追加するかもしれません。

誰も見ていないときに動作し続けるものは何ですか?

最初に2つを設定してください。.github/copilot-instructions.mdの指示は、日中のIDEと同じように、夜間のブランチ作業でもアシスタントを導きます。IronBarcodeのネイティブ依存関係をインストールするcopilot-setup-steps.ymlと、Agentsのシークレットに保存したキーがあれば、元から正常なコードを誤ってデバッグするのを防げます。それ以外は通常のアシスタントの使い方と同じで、この2つを整えることで作業が円滑になります。

補完の10秒後でも、プルリクエストが届いた翌朝でも、レビューの方法は同じです。AI コーディングアシスタントとエージェントガイドに示された一定の基準で評価します。 Claude Code、ChatGPT Codex、Cursor、およびGoogle Antigravity は、各々の専用ガイダンスがあります。


トラブルシューティング


ご質問はありますか?

質問がある場合は、support@ironsoftware.com にお問い合わせください。

Curtis Chauは、カールトン大学でコンピュータサイエンスの学士号を取得し、Node.js、TypeScript、JavaScript、およびReactに精通したフロントエンド開発を専門としています。直感的で美しいユーザーインターフェースを作成することに情熱を持ち、Curtisは現代のフレームワークを用いた開発や、構造の良い視覚的に魅力的なマニュアルの作成を楽しんでいます。

もっと読む

準備はできましたか?

NuGetダウンロード数 2,564,559バージョン:2026.11ちょうどリリースされました