次の方法で共有


nuget.exe CLI を使用してパッケージを作成する

パッケージの内容や含まれるコードに関係なく、 nuget.exe または dotnet.exeのいずれかの CLI ツールを使用して、その機能を他の任意の数の開発者と共有して使用できるコンポーネントにパッケージ化します。 NuGet CLI ツールをインストールするには、「 NuGet クライアント ツールのインストール」を参照してください。 Visual Studio には CLI ツールが自動的に含まれないことに注意してください。

技術的には、NuGet パッケージは、 .nupkg 拡張子で名前が変更され、その内容が特定の規則に一致する ZIP ファイルにすぎません。 このトピックでは、これらの規則を満たすパッケージを作成する詳細なプロセスについて説明します。

パッケージ化は、パッケージとして配信するコンパイル済みコード (アセンブリ)、シンボル、またはその他のファイルで始まります ( 「概要とワークフロー」を参照)。 このプロセスは、パッケージに入るファイルのコンパイルやその他の生成とは無関係ですが、プロジェクト ファイル内の情報から描画して、コンパイル済みのアセンブリとパッケージを同期させることができます。

Important

このトピックは、SDK スタイル以外のプロジェクト (通常は Visual Studio 2017 以降のバージョンと NuGet 4.0 以降を使用する .NET Core および .NET Standard プロジェクト以外のプロジェクト) に適用されます。

パッケージ化するアセンブリを決定する

ほとんどの汎用パッケージには、他の開発者が独自のプロジェクトで使用できる 1 つ以上のアセンブリが含まれています。

  • 一般に、各アセンブリが個別に役立つ場合は、NuGet パッケージごとに 1 つのアセンブリを用意することをお勧めします。 たとえば、Utilities.dllに依存するParser.dllがあり、Parser.dllが単独で便利な場合は、それぞれに 1 つのパッケージを作成します。 これにより、開発者はParser.dllとは別にUtilities.dllを使用できます。

  • ライブラリが個別に役立たない複数のアセンブリで構成されている場合は、それらを 1 つのパッケージに結合しても問題ありません。 前の例を使用 Parser.dllUtilities.dllによってのみ使用されるコードが含まれている場合は、 Parser.dll を同じパッケージに保持しても問題ありません。

  • 同様に、 Utilities.dllUtilities.resources.dllに依存している場合は、後者が単独では役に立たない場合は、両方を同じパッケージに配置します。

実際には、リソースは特別なケースです。 パッケージがプロジェクトにインストールされると、NuGet はパッケージの DLL にアセンブリ参照を自動的に追加します。ただし、ローカライズされたサテライト アセンブリと見なされるため、という名前の DLL は.resources.dllきます (ローカライズされたパッケージの作成を参照)。 このため、重要なパッケージ コードを含むファイルには .resources.dll を使用しないでください。

ライブラリに COM 相互運用機能アセンブリが含まれている場合は、「COM 相互運用機能アセンブリを使用して パッケージを作成する」のガイドラインに従ってください。

.nuspec ファイルのロールと構造

パッケージ化するファイルがわかったら、次の手順では、 .nuspec XML ファイルにパッケージ マニフェストを作成します。

マニフェスト:

  1. パッケージの内容について説明し、それ自体がパッケージに含まれます。
  2. パッケージの作成の両方を実行し、パッケージをプロジェクトにインストールする方法について NuGet に指示します。 たとえば、マニフェストは、メイン パッケージのインストール時に NuGet がそれらの依存関係をインストールできるように、他のパッケージの依存関係を識別します。
  3. 以下で説明するように、必須プロパティと省略可能なプロパティの両方が含まれます。 ここに記載されていないその他のプロパティを含む正確な詳細については、 .nuspec リファレンスを参照してください

必須プロパティ:

  • パッケージ識別子。パッケージをホストするギャラリー全体で一意である必要があります。
  • Major.Minor.Patch[-Suffix] という形式の特定のバージョン番号。-Suffixプレリリース バージョンを識別します
  • ホストに表示されるパッケージ タイトル (nuget.org など)
  • 作成者と所有者の情報。
  • パッケージの長い説明。

一般的な省略可能なプロパティ:

プロパティを説明するコメントを含む一般的な (ただし架空の) .nuspec ファイルを次に示します。

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

依存関係の宣言とバージョン番号の指定の詳細については、「 packages.configパッケージのバージョン管理」を参照してください。 include要素のexclude属性とdependency属性を使用して、パッケージ内の依存関係からアセットを直接表示することもできます。 「.nuspec リファレンス - 依存関係」を参照してください。

マニフェストはそこから作成されたパッケージに含まれているため、既存のパッケージを調べることで、任意の数の追加の例を見つけることができます。 適切なソースは、コンピューター上 のグローバル パッケージ フォルダーであり、その場所は次のコマンドによって返されます。

nuget locals -list global-packages

任意の package\version フォルダーに移動し、.nupkg ファイルを.zip ファイルにコピーし、その.zip ファイルを開き、その中の.nuspecを調べます。

Visual Studio プロジェクトから .nuspec を作成する場合、マニフェストには、パッケージのビルド時にプロジェクトからの情報に置き換えられるトークンが含まれます。 Visual Studio プロジェクトからの .nuspec の作成を参照してください。

.nuspec ファイルを作成する

完全なマニフェストの作成は、通常、次のいずれかの方法で生成された基本的な .nuspec ファイルから始まります。

その後、ファイルを手動で編集して、最終的なパッケージに必要な内容が正確に記述されるようにします。

Important

生成された .nuspec ファイルには、 nuget pack コマンドを使用してパッケージを作成する前に変更する必要があるプレースホルダーが含まれています。 .nuspecにプレースホルダーが含まれている場合、そのコマンドは失敗します。

規則ベースの作業ディレクトリから

NuGet パッケージは、 .nupkg 拡張子で名前が変更された ZIP ファイルであるため、多くの場合、ローカル ファイル システムに必要なフォルダー構造を作成し、その構造から直接 .nuspec ファイルを作成するのが最も簡単です。 nuget pack コマンドは、そのフォルダー構造内のすべてのファイルを自動的に追加します (.で始まるフォルダーを除き、プライベート ファイルを同じ構造に保持できます)。

この方法の利点は、パッケージに含めるファイルをマニフェストで指定する必要がないようにすることです (このトピックの後半で説明します)。 ビルド プロセスでパッケージに入る正確なフォルダー構造を生成するだけで、プロジェクトに含まれていない可能性がある他のファイルを簡単に含めることができます。

  • ターゲット プロジェクトに挿入する必要があるコンテンツとソース コード。
  • PowerShell スクリプト
  • プロジェクト内の既存の構成ファイルとソース コード ファイルへの変換。

フォルダー規則は次のとおりです。

フォルダー Description パッケージのインストール時のアクション
(root) readme.txt の場所 パッケージのインストール時に、Visual Studio によってパッケージ ルートに readme.txt ファイルが表示されます。
lib/{tfm} 特定のターゲット フレームワーク モニカー (TFM) のアセンブリ (.dll)、ドキュメント (.xml)、およびシンボル (.pdb) ファイル アセンブリは、コンパイルとランタイムの参照として追加されます。 .xml.pdb プロジェクト フォルダーにコピーされます。 複数のターゲットフレームワークをサポートすることで、フレームワークのターゲット固有のサブフォルダーを作成する方法について参照してください。
ref/{tfm} 指定されたターゲット フレームワーク モニカー (TFM) のアセンブリ (.dll)、およびシンボル (.pdb) ファイル アセンブリはコンパイル時にのみ参照として追加されます。そのため、プロジェクトの bin フォルダーには何もコピーされません。
runtimes アーキテクチャ固有のアセンブリ (.dll)、シンボル (.pdb)、ネイティブ リソース (.pri) ファイル アセンブリはランタイムの参照としてのみ追加されます。他のファイルはプロジェクト フォルダーにコピーされます。 対応するコンパイル時アセンブリを提供するために、AnyCPU フォルダーの下に、対応する (TFM) /ref/{tfm}特定のアセンブリが常に存在する必要があります。 複数のターゲット フレームワークのサポートを参照してください。
コンテンツ 任意のファイル 内容がプロジェクト ルートにコピーされます。 コンテンツ フォルダーは、最終的にパッケージを使用するターゲット アプリケーションのルートと考えてください。 パッケージにアプリケーションの /images フォルダーにイメージを追加するには、パッケージの content/images フォルダーに配置します。
ビルド (3.x+) MSBuild .targets ファイルと .props ファイル プロジェクトに自動的に挿入されます。
buildMultiTargeting (4.0 以降) クロスフレームワーク ターゲット用の MSBuild .targets ファイルと .props ファイル プロジェクトに自動的に挿入されます。
buildTransitive (5.0 以降) MSBuild ファイルと、それを利用しているプロジェクトに推移的に流れるファイルを .targets.propsします。 機能に関するページをご覧ください。 プロジェクトに自動的に挿入されます。
ツール パッケージ マネージャー コンソールからアクセスできる PowerShell スクリプトとプログラム tools フォルダーは、パッケージ マネージャー コンソールのPATH環境変数にのみ追加されます (具体的には、プロジェクトのビルド時に MSBuild に設定されたには追加PATH)。

フォルダー構造には、任意の数のターゲット フレームワークに対して任意の数のアセンブリを含めることができるため、このメソッドは、複数のフレームワークをサポートするパッケージを作成するときに必要です。

いずれの場合も、目的のフォルダー構造が整ったら、そのフォルダーで次のコマンドを実行して、 .nuspec ファイルを作成します。

nuget spec

ここでも、生成された.nuspecには、フォルダー構造内のファイルへの明示的な参照は含まれていません。 NuGet には、パッケージの作成時にすべてのファイルが自動的に含まれます。 ただし、マニフェストの他の部分でプレースホルダー値を編集する必要があります。

アセンブリ DLL から

アセンブリからパッケージを作成する単純なケースでは、次のコマンドを使用して、アセンブリ内のメタデータから .nuspec ファイルを生成できます。

nuget spec <assembly-name>.dll

このフォームを使用すると、マニフェスト内のいくつかのプレースホルダーがアセンブリの特定の値に置き換えられます。 たとえば、 <id> プロパティはアセンブリ名に設定され、 <version> はアセンブリ バージョンに設定されます。 ただし、マニフェスト内の他のプロパティはアセンブリ内に一致する値を持たないため、プレースホルダーが含まれています。

Visual Studio プロジェクトから

.nuspecまたは.csproj ファイルから.vbprojを作成すると便利です。これらのプロジェクトにインストールされている他のパッケージは依存関係として自動的に参照されるためです。 プロジェクト ファイルと同じフォルダーで次のコマンドを使用するだけです。

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

結果の <project-name>.nuspec ファイルには、パッケージ化時にプロジェクトの値に置き換えられる トークン が含まれます。これには、既にインストールされている他のパッケージへの参照も含まれます。

.nuspec に含めるパッケージ依存関係がある場合は、代わりに nuget pack を使用し、生成された .nupkg ファイル内から .nuspec ファイルを取得します。 たとえば、次のコマンドを使用します。

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

トークンは、プロジェクト プロパティの両側の $ 記号で区切られます。 たとえば、この方法で生成されたマニフェストの <id> 値は、通常、次のように表示されます。

<id>$id$</id>

このトークンは、パッキング時にプロジェクト ファイルの AssemblyName 値に置き換えられます。 プロジェクト値と .nuspec トークンの正確なマッピングについては、「 置換トークン」のリファレンスを参照してください

トークンを使用すると、プロジェクトを更新するときに、 .nuspec のバージョン番号などの重要な値を更新する必要が軽減されます。 (必要に応じて、常にトークンをリテラル値に置き換えることができます)。

後で .nupkg ファイルを生成するための nuget パックの実行 に関するページで説明されているように、Visual Studio プロジェクトから作業するときに使用できる追加のパッケージ化オプションがいくつかあります。

ソリューションレベルパッケージ

NuGet 2.x のみ。 NuGet 3.0 以降では使用できません。

NuGet 2.x では、パッケージ マネージャー コンソールのツールまたは追加のコマンド ( tools フォルダーの内容) をインストールするソリューション レベルのパッケージの概念がサポートされましたが、ソリューション内のプロジェクトに参照、コンテンツ、ビルドのカスタマイズは追加されません。 このようなパッケージには、直接の libフォルダー、 content フォルダー、または build フォルダーにファイルが含まれていないので、それぞれの libcontent、または build フォルダーにファイルが含まれる依存関係はありません。

NuGet は、インストールされているソリューション レベルのパッケージを、プロジェクトのpackages.config ファイルではなく、.nuget フォルダー内のpackages.config ファイルで追跡します。

既定値を持つ新しいファイル

次のコマンドは、プレースホルダーを含む既定のマニフェストを作成します。これにより、適切なファイル構造から始めます。

nuget spec [<package-name>]

<package-name>を省略すると、結果のファイルはPackage.nuspecContoso.Utility.UsefulStuffなどの名前を指定すると、ファイルはContoso.Utility.UsefulStuff.nuspec

結果の .nuspec には、 projectUrlなどの値のプレースホルダーが含まれます。 ファイルを使用して最終的な .nupkg ファイルを作成する前に、必ずファイルを編集してください。

一意のパッケージ識別子を選択し、バージョン番号を設定する

パッケージ識別子 (<id> 要素) とバージョン番号 (<version> 要素) は、パッケージに含まれる正確なコードを一意に識別するため、マニフェストの 2 つの最も重要な値です。

パッケージ識別子のベスト プラクティス:

  • 一意性: 識別子は、nuget.org またはパッケージをホストするギャラリー全体で一意である必要があります。 識別子を決定する前に、該当するギャラリーを検索して、名前が既に使用されているかどうかを確認します。 競合を回避するには、 Contoso.など、識別子の最初の部分として会社名を使用することをお勧めします。
  • 名前空間に似た名前: ハイフンではなくドット表記を使用して、.NET の名前空間に似たパターンに従います。 たとえば、Contoso.Utility.UsefulStuffContoso-Utility-UsefulStuffではなく、Contoso_Utility_UsefulStuffを使用します。 コンシューマーは、パッケージ識別子がコードで使用される名前空間と一致する場合にも役立ちます。
  • サンプル パッケージ: 別のパッケージの使用方法を示すサンプル コードのパッケージを生成する場合は、.Sampleのように、識別子にサフィックスとしてContoso.Utility.UsefulStuff.Sampleをアタッチします。 (サンプル パッケージは、もちろん他のパッケージに依存します)。サンプル パッケージを作成する場合は、前述の規則ベースの作業ディレクトリ メソッドを使用します。 content フォルダーで、サンプル コードを \Samples\<identifier> のように \Samples\Contoso.Utility.UsefulStuff.Sample という名前のフォルダーに配置します。

パッケージ バージョンのベスト プラクティス:

  • 一般に、パッケージのバージョンをライブラリと一致するように設定しますが、これは厳密には必要ありません。 これは、パッケージを 1 つのアセンブリに制限する場合の単純な問題です。前述の「 パッケージ化するアセンブリの決定」で説明しました。 全体的に、NuGet 自体は、アセンブリ バージョンではなく依存関係を解決するときにパッケージ バージョンを処理することに注意してください。
  • 標準以外のバージョンスキームを使用する場合は、「パッケージのバージョン管理」で説明されているように、NuGet の バージョン管理規則を考慮してください。

次の一連の簡単なブログ記事は、バージョン管理を理解するのにも役立ちます。

readme とその他のファイルを追加する

パッケージに含めるファイルを直接指定するには、<files> ファイル内の .nuspec ノードを使用します。このノードは、 タグに<metadata>

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

ヒント

規則ベースの作業ディレクトリアプローチを使用する場合、readme.txt をパッケージ ルートに配置し、他のコンテンツを content フォルダーに配置できます。 マニフェストには <file> 要素は必要ありません。

パッケージ ルートに readme.txt という名前のファイルを含めると、パッケージを直接インストールした直後にそのファイルの内容がプレーン テキストとして表示されます。 (依存関係としてインストールされたパッケージの Readme ファイルは表示されません)。 たとえば、HtmlAgilityPack パッケージの readme がどのように表示されるかを次に示します。

インストール時の NuGet パッケージの readme ファイルの表示

<files> ファイルに空の.nuspec ノードを含める場合、NuGet には、lib フォルダーに含まれる内容以外のコンテンツはパッケージに含まれません。

MSBuild のプロパティとターゲットをパッケージに含める

場合によっては、ビルド中にカスタム ツールやプロセスを実行するなど、パッケージを使用するプロジェクトにカスタム ビルド ターゲットまたはプロパティを追加することが必要になる場合があります。 NuGet パッケージの MSBuild のプロパティとターゲットの詳細を確認できます

プロジェクトのビルド フォルダー内に <package_id>.targets または <package_id>.props ( Contoso.Utility.UsefulStuff.targets など) を作成します。

次に、 .nuspec ファイルで、 <files> ノードで次のファイルを参照してください。

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

パッケージがプロジェクトに追加されると、NuGet にはこれらのプロパティとターゲットが自動的に含まれます。

nuget パックを実行して .nupkg ファイルを生成する

アセンブリまたは規則ベースの作業ディレクトリを使用する場合は、nuget pack ファイルで.nuspecを実行してパッケージを作成し、<project-name>を特定のファイル名に置き換えます。

nuget pack <project-name>.nuspec

Visual Studio プロジェクトを使用する場合は、プロジェクト ファイルで nuget pack を実行します。プロジェクトの .nuspec ファイルが自動的に読み込まれ、プロジェクト ファイル内の値を使用して、その中のすべてのトークンが置き換えられます。

nuget pack <project-name>.csproj

プロジェクトはトークン値のソースであるため、トークンの置換にはプロジェクト ファイルを直接使用する必要があります。 nuget pack ファイルで.nuspecを使用する場合、トークンの置換は行われません。

いずれの場合も、 nuget pack は、 .git.hgなど、期間で始まるフォルダーを除外します。

NuGet は、マニフェスト内のプレースホルダー値の変更を忘れるなど、修正が必要なエラーが .nuspec ファイルに存在するかどうかを示します。

nuget pack成功すると、「パッケージの発行」の説明に従って、適切なギャラリーに発行できる.nupkg ファイル作成されます。

ヒント

作成後にパッケージを調べるのに役立つ方法は、 パッケージ エクスプローラー ツールでパッケージを開く方法です。 これにより、パッケージの内容とそのマニフェストがグラフィカルに表示されます。 また、結果の .nupkg ファイルの名前を .zip ファイルに変更し、その内容を直接調べることもできます。

追加オプション

さまざまなコマンド ライン スイッチと nuget pack を使用して、ファイルを除外したり、マニフェストのバージョン番号をオーバーライドしたり、出力フォルダーを変更したりできます。 完全な一覧については、 pack コマンドリファレンスを参照してください

Visual Studio プロジェクトで一般的なオプションを次に示します。

  • 参照先プロジェクト: プロジェクトが他のプロジェクトを参照している場合は、 -IncludeReferencedProjects オプションを使用して、参照先のプロジェクトをパッケージの一部として、または依存関係として追加できます。

    nuget pack MyProject.csproj -IncludeReferencedProjects
    

    この包含プロセスは再帰的であるため、 MyProject.csproj がプロジェクト B と C を参照し、それらのプロジェクトが D、E、F を参照する場合、B、C、D、E、F のファイルがパッケージに含まれます。

    参照先プロジェクトに独自の .nuspec ファイルが含まれている場合、NuGet はその参照先プロジェクトを依存関係として追加します。 そのプロジェクトを個別にパッケージ化して発行する必要があります。

  • ビルド構成: 既定では、NuGet はプロジェクト ファイル内の既定のビルド構成セット (通常は デバッグ) を使用します。 リリースなどの別のビルド構成からファイルをパックするには、構成で -properties オプションを使用します。

    nuget pack MyProject.csproj -properties Configuration=Release
    
  • シンボル: コンシューマーがデバッガーでパッケージ コードをステップ実行できるようにするシンボルを含めるには、 -Symbols オプションを使用します。

    nuget pack MyProject.csproj -symbols
    

パッケージのインストールをテストする

パッケージを発行する前に、通常はプロジェクトにパッケージをインストールするプロセスをテストする必要があります。 テストでは、必ずしもすべてのファイルがプロジェクト内の正しい場所に配置されることを確認します。

通常の パッケージ インストール手順を使用して、Visual Studio またはコマンド ラインでインストールを手動でテストできます。

自動テストの基本的なプロセスは次のとおりです。

  1. .nupkg ファイルをローカル フォルダーにコピーします。
  2. nuget sources add -name <name> -source <path> コマンドを使用して、パッケージ ソースにフォルダーを追加します (nuget ソースを参照)。 このローカル ソースは、任意のコンピューターで 1 回だけ設定する必要があることに注意してください。
  3. nuget install <packageID> -source <name>を使用して、そのソースからパッケージをインストールします。ここで、<name>nuget sourcesに指定されたソースの名前に一致させます。 ソースを指定すると、パッケージがそのソースから単独でインストールされます。
  4. ファイル システムを調べて、ファイルが正しくインストールされていることを確認します。

次のステップ

.nupkg ファイルであるパッケージを作成したら、「パッケージの発行」の説明に従って、選択したギャラリーに発行できます。

次のトピックで説明するように、パッケージの機能を拡張したり、他のシナリオをサポートしたりすることもできます。

最後に、注意する必要がある追加のパッケージの種類があります。