マイクロソフト系技術情報 Wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。

目次

概要

  • NuGetパッケージを作成してみたくなったので調査。

Nugetでできること。

追加できるファイル

パッケージの色々

その他

  • 複数のTarget Frameworksのサポート
  • appSettingsなど、*.configの編集

.NET Frameworkプロジェクト以外

.NET Standard.NET Core

.NET Standard.NET Coreも、.NET Frameworkと同じ。

Native Package(C++)

C++の、Native Packageも作成できる模様。

  • Qiita
  • microsoft.com

基本的な手順

Nugetのサイトにサインイン

  • Microsoftアカウントでサインアップ可能。
    • 連携するのはメールアドレスで、同時にユーザ名の入力が必要。
    • サインアップ後、サインインが可能になる。
    • ローカル・ログオン用のパスワードはアカウント編集画面から設定可能。

NugetのサイトからNuget.exeを取得

に遷移。

  • Windows x86 Commandline
    nuget.exe - recommended latest vn.n.n

をクリックして、nuget.exeをDownload。

nuspecファイルの生成

nuspecファイルとは?

  • パッケージのメタデータを含むXML形式のマニフェスト(公約文書)。
  • マニフェスト(公約文書)は常にパッケージに含まれる。
  • パッケージを構築し、消費者に情報を提供するために使用される。

nuspecファイルの出力準備

  • nuget.exeへのパスを通しておくか、
    プロジェクトファイル(*.csproj)のあるフォルダにnuget.exeを配置する。
  • AssemblyInfo?の属性値を使用するので、これに属性を記入しておく。
    • 規定値
      [assembly: AssemblyTitle("Public")]
      [assembly: AssemblyDescription("")]
      [assembly: AssemblyConfiguration("")]
      [assembly: AssemblyCompany("xxxxxxxxxx")]
      [assembly: AssemblyProduct("Public")]
      [assembly: AssemblyCopyright("Copyright (C) 2007,2016 xxxxxxxxxx")]
      [assembly: AssemblyTrademark("")]
      [assembly: AssemblyCulture("")]
  • 以下を追加(ただ、実際にやっている人は少なそう)
    [assembly : AssemblyMetadata("ProjectUrl", "http・・・")]
    [assembly : AssemblyMetadata("LicenseUrl", "http・・・")]

nuget.exeからnuspecファイルを出力

  • プロジェクトファイル(*.csproj)から生成する。
    • プロジェクトファイル(*.csproj)のあるフォルダで[nuget spec]コマンドを実行する。
      nuget spec
    • *.nuspecファイルが生成される(何故か、AssemblyInfo?の属性値が反映されなかった)。
      <?xml version="1.0"?>
      <package >
        <metadata>
          <id>$id$</id>
          <version>$version$</version>
          <title>$title$</title>
          <authors>$author$</authors>
          <owners>$author$</owners>
          <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
          <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
          <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
          <requireLicenseAcceptance>false</requireLicenseAcceptance>
          <description>$description$</description>
          <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
          <copyright>Copyright 2017</copyright>
          <tags>Tag1 Tag2</tags>
        </metadata>
      </package>
  • DLLファイル(*.dll)から生成する。
    • DLLファイル(*.dll)を指定して[nuget spec]コマンドを実行する。
      nuget spec [*.dllファイルパス]
    • *.nuspecファイルが生成される(こちらも、AssemblyInfo?の属性値が反映されていない)。
      <?xml version="1.0"?>
      <package >
        <metadata>
          <id>Public.dll</id>
          <version>1.0.0</version>
          <authors>(Windowsにログインしたユーザ名)</authors>
          <owners>(Windowsにログインしたユーザ名)</owners>
          <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
          <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
          <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
          <requireLicenseAcceptance>false</requireLicenseAcceptance>
          <description>Package description</description>
          <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
          <copyright>Copyright 2017</copyright>
          <tags>Tag1 Tag2</tags>
          <dependencies>
            <dependency id="SampleDependency" version="1.0" />
          </dependencies>
        </metadata>
      </package>

nuspecファイルの編集

  • 生成されたnuspecファイルを修正する。
  • それぞれの項目については下記を参照。

以下、ザックリとした説明。

id

例 : Oracle.DataAccess?(.dll)とか、Microsoft.AspNet?.Identity(.dll)とか。

  • 一意
  • 名前空間っぽくする。
  • 社名などを使うと良い。
  • サンプルのパッケージは、*.Sampleを足す。

title

description

パッケージのザックリとした説明。

authors、owners

  • owners
    開発した個人。
  • authors
    著作権を持つ個人・団体。

projectUrl、licenseUrl、iconUrl

各種URLを設定する。

  • projectUrl
  • licenseUrl
  • iconUrl

version

  • 依存関係を解決する際に使用されるパッケージバージョン。
  • パッケージを単一のアセンブリに限定するためのもの。
  • 注 :
    • アセンブリバージョンではなく、パッケージバージョン
    • 故に、アセンブリバージョンと一致させる必要はない。
  • 基本的には、以下の3つを使用して「n.n.n」(Major.Minor.Patch)と構成する。
    • メジャーバージョン
    • マイナーバージョン
    • 下位互換性のあるバグ修正

.NET Framework アセンブリへの参照の追加

<frameworkAssemblies> 
  <frameworkAssembly assemblyName="System.Web" /> 
</frameworkAssemblies>

他のNugetパッケージへの依存関係の追加

<dependencies> 
  <dependency id="jQuery" /> 
</dependencies>

バージョンを指定可能。範囲指定も可能。

アセンブリの追加(*.dll)

targetを設定して、アセンブリ(*.dll)を同梱する。

<files> 
  <file src="bin\Release\*.*" target="lib\net45" /> 
</files>

参考

https://docs.microsoft.com/ja-jp/nuget/create-packages/creating-a-package

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>
    <!-- The identifier that must be unique within the hosting gallery -->
    <!-- ホスティングギャラリー内で一意でなければならないID -->
    <id>Contoso.Utility.UsefulStuff</id>

    <!-- The package version number that is used when resolving dependencies -->
    <!-- 依存関係を解決するときに使用されるパッケージのバージョン番号 -->
    <version>1.8.3.331</version>

    <!-- Authors contain text that appears directly on the gallery -->
    <!-- Authorsには、ギャラリーに直接表示されるテキストが含まれています -->
    <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は通常、ギャラリーのユーザーが同じownerによる他のパッケージを簡単に見つけることを可能にするnuget.org IDです。 -->
    <owners>dejanatc, rjdey</owners>

    <!-- License and project URLs provide links for the gallery -->
    <!-- licenseUrlとprojectUrlはギャラリーにリンクを提供します -->
    <licenseUrl>http://opensource.org/licenses/MS-PL</licenseUrl>
    <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

    <!-- The icon is used in Visual Studio's package manager UI -->
    <!-- このアイコンは、Visual Studioのパッケージ・マネージャUIで使用されます -->
    <iconUrl>http://github.com/contoso/UsefulStuff/nuget_icon.png</iconUrl>

    <!-- If true, this value prompts the user to accept the license when installing the package. -->
    <!-- trueの場合、この値は、パッケージのインストール時にライセンスを受け入れるようにユーザーに指示します。 -->
    <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は、パッケージ・マネージャのUIで使用できます。 nuget.orgギャラリーでは、ポータルに追加した情報が使用されます。 -->
    <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はギャラリーに表示され、tag検索に使用できます -->
    <tags>web utility http json url parsing</tags>

    <!-- Dependencies are automatically installed when the package is installed -->
    <!-- dependencyは、パッケージのインストール時に自動的に(他のパッケージが)インストールされます。 -->
    <dependencies>
      <dependency id="Newtonsoft.Json" version="9.0" />
    </dependencies>
  </metadata>

  <!-- A readme.txt will be displayed when the package is installed -->
  <!-- パッケージのインストール時に readme.txt が表示されます -->
  <files>
    <file src="readme.txt" target="" />
  </files>
</package>

パッケージ(nupkgファイル)の作成

プロジェクト・ファイルを使用

  • 以下のコマンドでパッケージを作成する。
    nuget pack [*.csprojファイルパス]
  • カレントでやれば、*.csprojファイルのパス指定は不要。
    nuget pack
  • リリースビルを選択する場合、
    nuget pack -Prop Configuration=Release

nuspecファイルを使用

  • 高度な設定」を行う場合はnuspecファイルを作成・指定して実行する。
    nuget pack [*.nuspecファイルパス]

nupkgファイルの内容確認方法

  • 「*.nupkg、*.symbols.nupkg」は ZIP ファイルなので、
    拡張子を「*.zip」にすれば、解凍して実際に含まれる ファイルを確認可能。

NuGet への登録

コマンドラインから

  • Access Keyを取得する。 Accountページに遷移してAPI Keysを取得する。
  • 以下のコマンドでNuGet へ登録する。
    • 方法1(urlのv1は、バージョン指定?)
      nuget push -source http://packages.nuget.org/v1/ [*.nupkgファイルパス] [access key]
  • 方法2(URLは不要?)
    nuget setapikey [access key] 
    nuget push [*.nupkgファイルパス] 

Webサイトから

NuGet Gallery でアップロードする場合、API Keysは不要。

公開前に(ローカルで)テスト実行する。

  • ざっくり、
    • Nugetパッケージ・マネージャーの設定で、
      パッケージ ソース(ローカルPCのフォルダ)を追加する。
    • ソリューションのNugetパッケージの管理を開き、
      追加したパッケージ ソースを選択して「参照」の検索窓から検索する。
      ソリューションのNugetパッケージの管理
  • 検索されたNugetパッケージを選択してインストールする。
  • packagesフォルダには以下のようにインストールされる。
    Touryo.Public.2.0.0
     ├ lib
     |  └ net46
     |      ├ Public.dll
     |      └ Public.XML
     └ Touryo.Public.2.0.0.nupkg
  • なお、依存関係も自動的に反映されるようで、
    このプロジェクトのpackages.configで使用しているパッケージも同時にインストールされた。

バージョンアップする。

nuspec ファイルの version を書き換えて同じように nupkg をアップロード。

高度な設定

パッケージにファイルを含める

パッケージに含めるファイル

  • ターゲットプロジェクトに挿入するコンテンツとソースコード
  • PowerShellスクリプト(インストールスクリプト、NuGet 2.xでのみサポート)
  • プロジェクト内の既存の構成ファイルおよびソースコードファイルへの変換

作業ディレクトリのフォルダ構造レイアウトの規則

#フォルダ説明パッケージのインストール時の動作
1toolsPackage Manager Consoleパッケージ・マネージャコンソールからアクセスできるPowershellスクリプトとプログラム内容はプロジェクトフォルダにコピーされ、ツールフォルダはPATH環境変数に追加される。
2libアセンブリファイル(.dll)、ドキュメント(.xml)ファイル、およびシンボル(.pdb)ファイルアセンブリは参照として追加される。 .xmlと.pdbはプロジェクトフォルダにコピーされる。
3content任意のファイルコンテンツはプロジェクトルートにコピーされる。
4buildMSBuild .targetsと.propsファイルプロジェクトファイル(NuGet 2.x)またはproject.lock.json(NuGet 3.x)に自動的に挿入される。

パッケージへのインクルード

nuspecファイルの<metadata>要素と同じ階層に、
<files>か<contentFiles>要素を追加することで、ファイルをインクルード出来る。

  • アセンブリ・ファイル
    • ファイルは*.nupkgファイルを作成するときに自動的にインクルードされる。
    • <files>要素を使用し、自動動作を回避、インクルード・ファイルを明示的に制御できる。

複数のTarget Frameworksのサポート

https://docs.microsoft.com/ja-jp/nuget/create-packages/supporting-multiple-target-frameworks

パッケージにファイルを含める」の方法で、複数バージョンを同梱するだけでいい。

設定

以下は、nuspecファイルの設定例

 <files>
   <file src="bin\Release\net46\MyAssembly.dll" target="lib\net46" />
   <file src="bin\Release\net461\MyAssembly.dll" target="lib\net461" />    
   <file src="bin\Release\uap\MyAssembly.dll" target="lib\uap" />    
   <file src="bin\Release\netcore\MyAssembly.dll" target="lib\netcore" />
 </files>

結果

パッケージのインストール後のpackagesフォルダのlibフォルダは以下のようになる。

  • lib\{framework name}[{version}]
  • 例:
    \lib
        \net46
            \MyAssembly.dll
        \net461
            \MyAssembly.dll
        \uap
            \MyAssembly.dll
        \netcore
            \MyAssembly.dll

参考

Dapperのnuspecファイルが参考になる。

  • dapper-dot-net/dapper.nuspec at master · perliedman/dapper-dot-net
    https://github.com/perliedman/dapper-dot-net/blob/master/dapper.nuspec#L67
     <files>
       <file src="Dapper NET45\bin\Release\Dapper.dll" target="lib\net45" />
       <file src="Dapper NET45\bin\Release\Dapper.pdb" target="lib\net45" />
       <file src="Dapper NET45\bin\Release\Dapper.xml" target="lib\net45" />
       
       <file src="Dapper NET40\bin\Release\Dapper.dll" target="lib\net40" />
       <file src="Dapper NET40\bin\Release\Dapper.pdb" target="lib\net40" />
       <file src="Dapper NET40\bin\Release\Dapper.xml" target="lib\net40" />
       
       <file src="Dapper NET35\bin\Release\Dapper.dll" target="lib\net35" />
       <file src="Dapper NET35\bin\Release\Dapper.pdb" target="lib\net35" />
       <file src="Dapper NET35\bin\Release\Dapper.xml" target="lib\net35" />
     </files>

様々なパッケージ

Localized Package(ローカライズ)

https://docs.microsoft.com/ja-jp/nuget/create-packages/creating-localized-packages

以下の2つの方法がある。

  • Localized resource assembly(Localized satellite assembly)を同梱する。
    • ワイルドカードを使用する方法。
    • xxxx.resources.dllを個別に同梱することもできる。
  • 個別にLocalized satellite packagesを作成する。
    (Microsoft.Owin.ja や Microsoft.AspNet?.Mvc.ja 的な)

Symbol Package(デバッグ用)

package type

NuGet 3.5以降で設定可能。

  • Dependency(既定値)
    上記の説明はコレ。
  • DotnetCliTool?
    .NET Coreプロジェクトにのみインストールできる.NET Core CLI ツール
  • カスタムタイプパッケージ
    DependencyとDotnetCliTool?以外のタイプは、
    Visual StudioのNuGet Package Managerによって認識されない。

注意

一度登録すると通常消せない。

  • バージョン番号を上げてアップロードすることでアップデートする。
  • 必要に応じて、
    • 旧バージョンを非表示にすることはできる。
    • 別途、運営に連絡して削除することもできる。

依存関係

Dependenciesタグ

NuGetサイトに表示されるのは、*.nspecファイルのDependenciesタグ明記したもの。

自動的に追加されるNuGetパッケージ

しかし、NuGetから追加された時には、

  • package.configによるのか、
  • バイナリ解析によるのか、

不明だが自動的に依存関係にあるNuGetパッケージが追加される。

参考

NuGetパッケージの開発と公開

nuspecファイルの定義例

著名なパッケージを参考にする。

Open棟梁のパッケージを参考にする。

nuspecファイルのメタデータ要素

必要なメタデータ要素(最小要件)

#要素説明
1id大文字と小文字を区別しない、nuget.orgなどのパッケージ・ギャラリー内で一意なパッケージ識別子。
IDにはURLに有効でないスペースや文字含めない。
2versionmajor.minor.patchパターンのパッケージのバージョン。
バージョン番号には、プレリリースパッケージに記載されているリリース前のサフィックスが含まれている場合がある。
3descriptionnuget.orgでパッケージのページを表示したときに表示される概要説明文
4authorsパッケージ著者のカンマ区切りのリスト。

オプションのメタデータ要素(必要に応じて追加)

  • 単項目
    #要素名説明
    1titleパッケージには、一般的にはUIで使用される、パッケージの人間にとって使いやすいタイトルがnuget.orgやVisual Studioのパッケージ・マネージャで表示される。
    指定しない場合、パッケージIDが代わりに使用される。
    2ownersnuget.orgでプロファイル名を使用しているパッケージ作成者のカンマ区切りのリスト。
    これらはnuget.orgのNuGet Galleryに表示され、同じ著者によるパッケージの相互参照に使用されている。
    3projectUrlパッケージのホームページのURL。
    多くの場合、UI表示とnuget.orgに表示される。
    4licenseUrlパッケージのライセンスのURL。
    nuget.orgと同様にUI表示にも表示されることがよくある。
    5iconUrlUI表示でパッケージのアイコンとして使用する透過背景を持つ64x64画像のURL。
    6requireLicenseAcceptance?パッケージをインストールする前に、パッケージライセンスを受け入れるようにクライアントに指示する必要があるかどうかを指定するブール値。
    7developmentDependency(2.8+)パッケージが開発専用依存としてマークされるかどうかを指定するブール値。
    パッケージが他のパッケージへの依存として含まれないようにする。
    8summaryVisual Studioから検索して表示される一覧表示用のパッケージの短い説明。
    省略された場合、記述の切り詰められたバージョンが使用される。
    9releaseNotes(1.5+)このパッケージのリリースで行われた変更の説明。
    パッケージ説明の代わりにVisual Studioパッケージ・マネージャの[更新]タブなどのUIでよく使用される。
    10copyright(1.5+)パッケージの著作権詳細。
    11languageパッケージのロケールID。
    ローカライズされたパッケージの作成を参照。
    12tagsパッケージを記述するタグとキーワードのスペース区切りリストで、
    検索とフィルタリングのメカニズムを通じたパッケージの発見可能性を支援する。
    13serviceable(3.3+)内部NuGet専用
    14minClientVersion?(2.5+)このパッケージをインストールできるNuGetクライアントの最小バージョンを指定する。
    このバージョンは、nuget.exeとVisual Studio Package Managerによって適用される。
    これは、パッケージがNuGetクライアントの特定のバージョンで追加された.nuspecファイルの特定の機能に依存する場合に使用される。
    例えば、developmentDependency属性を使用するパッケージは、minClientVersion?に「2.8」を指定する。
    同様に、contentFiles要素を使用するパッケージ(次のセクションを参照)は、minClientVersion?を "3.3"に設定する。
    また、2.5より前のNuGetクライアントはこのフラグを認識しないため、minClientVersion?で使用する値に関係なく、常にパッケージのインストールを拒否する。
  • 複数項目
    #要素名説明
    1packageTypes(3.3+)伝統的な依存パッケージ以外のパッケージのタイプを指定する0個以上の<packageType>要素の集合。
    各packageTypeにはnameとversionの属性がある。パッケージタイプの設定を参照。
    2dependenciesパッケージの依存関係を指定する0個以上の<dependency>要素の集合。
    各依存関係には、id、version、include(3.x +)、およびexclude(3.x +)の属性がある。
    下記の依存関係を参照。
    3frameworkAssemblies(1.2+)このパッケージに必要な.NET Frameworkアセンブリ参照を識別する0個以上の<frameworkAssembly>要素のコレクション。
    パッケージを使用するプロジェクトに参照が確実に追加される。
    各frameworkAssemblyにはassemblyName属性とtargetFramework属性がある。
    下記のフレームワークアセンブリ参照GACの指定を参照。
    4references(1.5+)プロジェクトの参照として追加される、パッケージのlibフォルダ内のアセンブリを命名する0個以上の<reference>要素のコレクション。
    各参照にはファイル属性がある。
    <references>は、<reference>要素を含むtargetFramework属性を持つ<group>要素も含むことができる。
    省略すると、libのすべての参照が含まれる。
    下記の明示的アセンブリ参照の指定を参照。
    5contentFiles(3.3+)コンシューマプロジェクトに含めるコンテンツファイルを識別する<files>要素のコレクション。
    これらのファイルは、プロジェクトシステム内でどのように使用されるべきかを記述する一連の属性で指定される。
    下記のパッケージに含めるファイルの指定を参照。

NuGetパッケージのデバッグ


Tags: :.NET開発, :デプロイ, :NuGet


添付ファイル: fileNuget.png 124件 [詳細]

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2018-09-15 (土) 18:05:41 (67d)