NuGet サーバー実装ガイド

場合によっては、独自の NuGet パッケージ フィードを実装する必要があります。 さまざまな方法で独自のフィードをホストできる 既存の実装 の多くが存在しますが、公式の NuGet クライアント ソフトウェアとパッケージ フィードの間のプロトコルが文書化されているため、独自のフィード実装を最初から構築できます。

プロトコルは時間の経過と同時に進化し、このガイドは NuGet パッケージ サーバーを実装したい、または既に実装しているものを対象としています。

2015 年の NuGet V3 プロトコルの最初のリリース以降、NuGet は開発者に豊富なエクスペリエンスを提供するように進化してきました。そのため、パッケージ リポジトリは、ホストされたパッケージからメタデータを正確に取得し、さまざまな形式でメタデータを返すだけでなく、パッケージ コンシューマーに追加の価値を提供するために追加の作業を行う必要があります。 たとえば、検索とパッケージのメタデータ エンドポイントには、nupkg の nuspec ファイルで見つかったメタデータ以上のものが含まれています。

このガイドでは、V2 プロトコルは基本的に文書化されておらず、2015 年以降、NuGet クライアントとサーバーの通信に推奨されるプロトコルは V3 プロトコルであるため、NuGet V3 プロトコルに焦点を当てています。 詳細については、プロトコルのバージョン管理に関する記事を参照してください。

年代順

既存の NuGet リポジトリの作成者が NuGet の最新の機能を最新の状態に保つために、ドキュメントの残りの部分で説明されている関連機能の時系列を次に示します。

所有者フィールド

パッケージ マニフェスト ファイル (.nuspec) フィールドのうち、<authors>と<owners>の 2 つについて考えてみます。 サード パーティのコンテンツをパッケージ化するパッケージ作成者は、多くの場合、サード パーティの名前を [ <authors> ] フィールドに入力します。 <owners> フィールドは、パッケージをリポジトリに発行したユーザーを示すことを目的としていたため、問題や質問をパッキングする場合に連絡する必要があるユーザーを示します。

これは 2013 年のブログ記事で説明されているため、 <owners> フィールドは .nuspec ファイルでは非推奨と見なされます。 パッケージのマニフェストにこのメタデータが含まれている場合は、無視する必要があります。 検索リソースまたはパッケージ メタデータ リソースの JSON 応答の owners プロパティで、.nuspec ファイルの <owners> フィールドの値を返さないでください。

リポジトリにパッケージごとのアクセス許可がある場合は、検索およびパッケージ メタデータ リソースの JSON 応答の owner メタデータに新しいバージョンを発行するアクセス許可を持つアカウントを報告することをお勧めします。

verified 検索応答フィールド

Visual Studio のパッケージ マネージャー UI では、新しいフィールドverifiedがtrueに設定されている場合、検索サービスの結果のパッケージの横に青いチェックマークが表示されます。

NuGet.org では、パッケージ プレフィックス データ (NuGet API の一部ではなく、サーバー側のデータ) でこれを使用するため、このチェックマークは、パッケージを所有するアカウントがパッケージをアップロードしたときにのみ表示されます。 たとえば、プレフィックス microsoft.* を持つパッケージは、パッケージが nuget.org 上の Microsoft アカウントによって所有されている場合にのみ検証されます。予約済みプレフィックスが実装される前にパッケージ ID が microsoft. で始まるパッケージをアップロードしたユーザーは、この検証済みチェックマークを持っていません。 NuGet.org では、プレフィックスを排他的にすることはできません。これにより、だれでも Contoso.ToolWithPlugins.Community.*でパッケージをアップロードできますが、検証済みのチェックマークは表示されません。

セマンティック バージョン 2.0.0 のサポート

NuGet では 、 System.Version とセマンティック バージョンの間のハイブリッドがサポートされていますが、セマンティック バージョン 2.0.0 のサポートは 2017 年に追加されました。 そのため、3.6.0 より前のバージョンのクライアントにバージョンを返す NuGet API リソースは、セマンティック バージョン 1.0.0 と互換性のないセマンティック 2.0.0 機能を使用するパッケージを返してはなりません。

2 つのバージョンの最も重要な違いは、プレリリース ラベルとメタデータ文字列です。 セマンティック バージョン 1.0.0 仕様では、プレリリース ラベルの一部として許可される唯一の文字のサンプル正規表現文字列として[0-9A-Za-z-]が提供され、メタデータ文字列はサポートされていません。 セマンティック バージョン 2.0.0 仕様では、プレリリース識別子を.文字で区切ることができます (また、数値識別子の先頭に 0 を付けるのを禁止します)、さらに、+の後にビルド メタデータを追加できます。

パッケージ メタデータ リソース (RegistrationsBaseUrl) では、3.6.0 より前のリソース バージョンでは、準拠しているパッケージのみを返す必要があります。NET のSystem.Versionまたはセマンティック バージョン 1.0.0。 つまり、バージョンがセマンティック バージョン 2.0.0 にのみ準拠しているパッケージは、これらのクライアント バージョンからは見えません。

同様に、 検索クエリ サービス (SearchQueryService) と オートコンプリート サービス (SearchAutocompleteService) によって、クエリ パラメーター &semVerLevel={version} 追加されました。 semVerLevelが見つからない場合は、値が1.0.0と見なします。 パッケージ メタデータ リソースと同様に、バージョンがセマンティック バージョン 2.0.0 とのみ互換性があるパッケージは、 semVerLevel 値が 2.0.0 未満の場合は返されません。

埋め込みファイル

パッケージ アイコン、 ライセンス、および readme ファイルは、パッケージに埋め込むことができます (推奨されます)。 これらのファイルには、URL エンドポイントが必要です。静的ファイル サーバーに展開して配置するか、要求に応じて .nupkg からファイルを動的に抽出する URL を使用して、 nupkg全体をダウンロードせずに表示できます。 パッケージ リポジトリがパッケージの参照とパッケージの詳細の表示を提供する場合は、URL を使用して、Web サイトに埋め込まれたコンテンツを顧客に表示できます。

最後に、 パッケージ メタデータ リソース と 検索リソース には、JSON 応答の iconUrl、 licenseUrl、または readmeUrl プロパティにホストされている URL が含まれている必要があります。 パッケージ (.nupkg ファイル) は、クライアント機能 (ロック ファイルと署名済みパッケージ) によって、パッケージが改ざんされたときに変更が検出されるため、変更しないでください。

ライセンスは SPDX 式または埋め込みファイル (両方ではなく) である可能性があることに注意してください。 ライセンス式を使用するパッケージは、検索およびパッケージ メタデータの結果で表される場合、 licenseUrl をライセンス式に設定し、URL をエンコードして、 https://licenses.nuget.org/の末尾に追加することができます。 たとえば、https://licenses.nuget.org/Apache-2.0 のようにします。 NuGet.org サーバー チームには、 licenses.nuget.org に関する追加のドキュメントがあります。

既知の脆弱性と非推奨のデータ

パッケージ メタデータ リソース (RegistrationsBaseUrl)

パッケージ メタデータ リソースには、非推奨と脆弱性の情報を含めることができます。 これにより、お客様は、Visual Studio のパッケージ マネージャー ユーザー インターフェイスでパッケージを閲覧したり、他の IDE と同等のパッケージを閲覧したりして、重要なセキュリティまたはメンテナンスの問題を通知することができます。

パッケージ リポジトリが別のリポジトリからの "アップソーシング" パッケージである場合は、独自のフィード内のパッケージをミラー化するために、非推奨または脆弱性データがあるかどうかを定期的に元のソースを確認し、そのメタデータを独自のリポジトリにミラー化することをお勧めします。 パッケージ リポジトリが特に nuget.org からアップソーシングされている場合は、最後にチェックした時刻 (カーソル) の状態を維持することで、Catalog リソースを使用して、ミラーリングするパッケージのパッケージ更新があるかどうかを効率的に確認できます。アップストリーム フィードから多数のパッケージ メタデータ JSON ファイルをダウンロードする必要はありません。 開始に役立つサンプル コードで カタログ リソースを使用 する方法に関するガイドがあります。

既知の脆弱性データベース (VulnerabilityInfo)

パッケージの復元中に高パフォーマンスの脆弱性スキャンを提供するために、NuGet は 、 VulnerabilityInfo リソースから既知の脆弱性の完全な一覧をダウンロードします。 Nuget.org は、 GitHub アドバイザリ データベースからレビューされたすべての GitHub アドバイザリの脆弱性データを提供します。これには、nuget.org でホストされていないパッケージが含まれます。

パッケージ リポジトリがファースト パーティ パッケージをホストしていて、独自のフィードを使用して顧客に脆弱性情報を提供したいが、まだ公開されているパッケージの脆弱性がない場合は、コンテンツが空の JSON 配列 ([]) である 1 つ以上の脆弱性ページを含む脆弱性インデックスを提供する必要があります。

パッケージ リポジトリが (nuget.org ではなく) 既定のリポジトリとしてアプリによって使用されることを意図している場合は、nuget.org の脆弱性データを使用できます。 1 つのオプションは、サービス インデックスで nuget.org の脆弱性インデックス URL を使用することです。 もう 1 つのオプションは、nuget.org の VulnerabilityInfo インデックスを定期的に確認し、変更されたページをダウンロードしてローカルにミラーリングすることです。

packageTypes 検索クエリ

.NET CLI では、 dotnet tool search コマンドを使用して .NET ツール パッケージを検索できます。 これは、パッケージの .nuspec ファイル <packageTypes> フィールドから値を読み取る、&packageTypes={value} クエリ パラメーターを検索クエリ リソースに追加することによって実装されます。

認証済みフィードの URL 構造

NuGet API の概要で説明されているように、すべての NuGet サーバー通信の開始 URL はサービス インデックスです。 このドキュメントには、NuGet クライアントがクエリを実行する他のすべてのリソースの URL が含まれています。 NuGet 6.7 (Visual Studio および MSBuild 17.7、.NET SDK 7.0.400) 以降、NuGet は .NET の HttpClientHandler.PreAuthenticate を使用します。これは、後続の URL が、以前に認証された URL の同じ仮想ディレクトリまたはサブディレクトリにある場合にのみ、匿名 HTTP 要求を回避します。 これにより、サーバーに送信される認証されていない HTTP 要求の数が大幅に減るため、サーバーのワークロードが削減されます。

いくつかの例を次に示します。

最後の例では、サーバーは正規の (この例では guid) 名前を持ち、1 つ以上のエイリアスを持つことができます。 サービス インデックス要求が非正規 URL (この例では feed の "フレンドリ" 名) で認証された場合、いいえ。正規 URL の下のリソースに対する要求は、PreAuthenticateのHttpClientHandlerの規則と一致しません。 ただし、非正規 URL が正規 URL ( https://pkgs.contoso.com/nuget/v3/{guid}/index.json) への HTTP リダイレクトである場合、この URL は HttpClientHandlerの資格情報キャッシュで使用されます。 この場合、リダイレクトにより、サービス インデックスに対するすべての要求に追加の待機時間が発生します。

NuGet の V3 API は静的ファイル サーバー上で動作するように設計されていますが、検索リソースは、要求を処理するために常に動的 Web サービスを必要とする例外です。 HttpClientHandlerのPreAuthenticateを利用するために、異なるサーバーで検索またはその他の NuGet API リソースをホストする場合は、リバース プロキシを使用して、サービス インデックス内のすべての顧客向け URL が "同じまたはサブディレクトリ" ルールを満たしていることを確認する必要があります。

埋め込み README ダウンロードを有効にする

特定のパッケージの README をダウンロードするために使用できる URL を構築するための 新しいリソース が文書化されました。 これにより、VS のパッケージ管理 UI などのクライアントは、ユーザーが以前にインストールしていないパッケージの埋め込み README を表示できます。 クライアントはこの URL を構築し、要求への応答を使用して README のダウンロードを試み、README が使用可能かどうかを判断します。 つまり、ユーザーが PM UI を移動する場合、サーバーは構築されたエンドポイントに対して複数の要求を想定する必要があります。