NuGetパッケージの開発と公開のバックアップ(No.12)

[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 †

idとは別の名称、呼称など。
例えば、Newtonsoft.Jsonに対するJson.NETなど。
https://www.nuget.org/packages/Newtonsoft.Json/

↑

description †

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

↑

authors、owners †

owners
開発した個人。

authors
著作権を持つ個人・団体。

参考
- Owner or Author ? What’s the Difference?
  http://kelleykeller.com/owner-vs-author-whats-the-difference/

↑

projectUrl、licenseUrl、iconUrl †

各種URLを設定する。

projectUrl
licenseUrl
iconUrl

↑

version †

依存関係を解決する際に使用されるパッケージバージョン。
パッケージを単一のアセンブリに限定するためのもの。

注 :
- アセンブリバージョンではなく、パッケージバージョン
- 故に、アセンブリバージョンと一致させる必要はない。

基本的には、以下の3つを使用して「n.n.n」（Major.Minor.Patch）と構成する。
- メジャーバージョン
- マイナーバージョン
- 下位互換性のあるバグ修正

α、β版のバージョンは以下が参考になる。
- NuGet Gallery | LambdicSql_β
  https://www.nuget.org/packages/LambdicSql/0.0.3
  https://www.nuget.org/packages/LambdicSql/0.1.0
  - idはRelease版と共通にして、
  - titleにα、βの版文字を含める
- Pre-release versions in NuGet packages | Microsoft Docs
  https://docs.microsoft.com/ja-jp/nuget/create-packages/prerelease-packages#semantic-versioning
  - -alpha: Alpha release, typically used for work-in-progress and experimentation
  - -beta: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs.
  - -rc: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge.
  - -xxx: NuGet version does not support string such as "1.0.1-build.23".
    And, like this is always considered a pre-release version.

参考
- 安藤幸央のランダウン（51）：意外と知らないバージョン表記・数字の豆知識 - ＠IT
  http://www.atmarkit.co.jp/ait/articles/1003/26/news106.html

↑

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

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

↑

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

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

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

Dependency Versions in NuGet | Microsoft Docs
https://docs.microsoft.com/ja-jp/nuget/create-packages/dependency-versions

↑

アセンブリの参照の追加（*.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>

↑

パッケージの作成 †

↑

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

以下のコマンドでパッケージを作成する。
```
nuget pack [*.csprojファイルパス]
```

カレントでやれば、*.csprojファイルのパス指定は不要。
```
nuget pack
```

リリースビルを選択する場合、
```
nuget pack -Prop Configuration=Release
```

↑

nuspecファイルを使用 †

手動で「パッケージにファイルを含める」場合はnuspecファイルを指定して実行する。
```
nuget pack [*.nuspecファイルパス]
```

↑

NuGet への登録 †

↑

コマンドラインから †

Access Keyを取得する。 Accountページに遷移してAPI Keysを取得する。
- NuGet Gallery | Edit Profile
  https://www.nuget.org/account
- E-Mail Confirmationが必要。

以下のコマンドでNuGet へ登録する。
- 方法１（urlのv1は、バージョン指定？）
```
nuget push -source http://packages.nuget.org/v1/ [*.nupkgファイルパス] [access key]
```

方法２（URLは不要？）

nuget setapikey [access key] 
nuget push [*.nupkgファイルパス]

↑

Webサイトから †

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

NuGet Gallery | Upload Package
https://www.nuget.org/packages/manage/upload

↑

公開前にテスト実行する。 †

以下が参考になる。
- .NET開発の新標準「NuGet」入門（後編）－＠IT
  http://www.atmarkit.co.jp/fdotnet/chushin/nuget_02/nuget_02_02.html

ざっくり、
- Nugetパッケージマネージャーの設定で、
  パッケージソース（ローカルPCのフォルダ）を追加する。
- ソリューションの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でのみサポート）
プロジェクト内の既存の構成ファイルおよびソースコードファイルへの変換

↑

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

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

↑

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

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

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

コンテンツ・ファイル
- contentFiles要素を使用する。

↑

複数の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 Packages（ローカライズ） †

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 Packages（デバッグ用） †

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

primary package
- DLLのみを同梱。
- パッケージ名
  {identifier}.nupkg

symbol package

*.dll、*.pdb、*.xml、ソース・ファイル（任意）を同梱。

nuspecファイルの書き方の例

<files>
    <file src="Full\bin\Debug\*.dll" target="lib\net40" />
    <file src="Full\bin\Debug\*.pdb" target="lib\net40" />
    <file src="Silverlight\bin\Debug\*.dll" target="lib\sl40" />
    <file src="Silverlight\bin\Debug\*.pdb" target="lib\sl40" />
    <file src="**\*.cs" target="src" />
</files>

作成方法（以下の何れか）

nuget pack [*.nuspecファイルパス] -Symbols
nuget pack [*.csprojファイルパス] -Symbols

パッケージ名
{identifier}.symbols.nupkg

上記がガイドラインだが、個人的には、

primary packageに、*.dll、*.pdb、*.xmlを同梱し、
ソースファイルは、Github等から取得する

のがイイと考えている。

↑

package type †

NuGet 3.5以降で設定可能。

Dependency（既定値）
上記の説明はコレ。

DotnetCliTool?
.NET Coreプロジェクトにのみインストールできる.NET Core CLI ツール

カスタムタイプパッケージ
DependencyとDotnetCliTool?以外のタイプは、
Visual StudioのNuGet Package Managerによって認識されない。

↑

注意 †

↑

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

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

↑

ビルド †

'*.pdbを同梱する場合は、ビルド時のフォルダ構成に注意すること。

↑

デバッグ †

なお、NuGetパッケージで展開されているモジュール内の
デバッグ実行が必要になった時の手順も確立しておく必要がある。

↑

前提 †

NuGetパッケージの同梱物をビルドする際に、*.pdbを出力する。
NuGetパッケージに、*.dllに加え、*.pdbを同梱する。

↑

準備 †

NuGetパッケージのモジュールを指定のフォルダに配置する。

↑

デバッグ実行 †

上記の準備が整えば、デバッグ実行で、これらのファイルに

ステップ・インしたり、
ブレーク・ポイントを設定したり、

して、デバック実行を、することができる。

↑

デバッグできない場合 †

しかし、

ステップ・インする際に、
「ソースファイルがモジュールがビルドされたときのものと異なります。デバッガでこのファイルを使用しますか？」

ブレーク・ポイントを設定した際に、
「ブレークポイントは、現在の設定ではヒットしません。ソースコードが元のバージョンと異なります。」

というメッセージが表示されデバッグできない場合がある。

この場合は、

ソースファイルがモジュールがビルドされたときのものと異なります。デバッガでこのファイルを使用しますか？
https://visual-studio-professional.com/source-file-module-build
[ツール] ---> [オプション] ---> [デバッグ] ---> [全般] の順にクリックし、
[元のバージョンと完全に一致するソースファイルを必要とする] チェックボックスをオフにする。

の手順に従って、

デバッグ実行が可能な設定に変更することができる。

↑

依存関係 †

↑

Dependenciesタグ †

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

↑

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

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

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

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

↑

参考 †

↑