パッケージ機能による配布

エクステンションの配布はバイナリによる直接配布に加えてパッケージ機能による配布が可能です。パッケージ機能を用いることでエクステンションやサンプルなどのコンテンツをバージョン管理した上で他ユーザーが利用することが容易になります。パッケージは Next Designの拡張機能で配布できます。

パッケージ化とそのメリット

パッケージ化とは Next Design の拡張機能を配布できるファイル形式として作成することです。エクステンションの配布やアップデートが非常にシンプルになります。主に次のようなメリットがあります。

インストールやアップデートが容易
- ワンクリックでエクステンションのインストールやアンインストール、アップデートができるようになります。
- 新しいバージョンの公開時に Next Design の画面でユーザーに通知できます。
バージョン管理が容易
- 複数のバージョンのエクステンションを配布できるためバージョン管理が容易です。
- Next Design の画面上でパッケージの概要やバージョン別の変更点を表示できます。
- 特定の Next Design のバージョンで動作するようなエクステンションを開発できます。
専用のサーバー不要で配布できる
- 独自のパッケージ展開用フォルダを登録できるため、ネットワークフォルダや GitHub/GitLab、Subversion 等のバージョン管理ツールを用いた簡易的な配布が可能です。
プロファイルやサンプルを配布できる
- エクステンションに限らず、プロファイルやプロジェクトのテンプレートを配布できます。

前提

パッケージ化に必要なツールや環境を準備します。すでにインストール済みの場合はスキップしてください。

NDExtをインストールします。

NDExt はエクステンションの開発を支援するコマンドラインツールです。コマンドプロンプトから次のように実行するだけでインストールできます。このプログラムを動作させるには .NET 6.0 SDK のインストールが必要です。

dotnet tool install --global NDExt

Visual Studio でプロジェクトテンプレートを用いてエクステンションのプロジェクトを作成します。

コマンドプロンプトから次のコマンドを実行すれば Visual Studio のテンプレートとして登録されます。
```
dotnet new --install NextDesign.Extension.ProjectTemplates
```

パッケージの作成

Next Design のエクステンションのパッケージを作成するにはいくつかの方法がありますが、 Visual Studio とコマンドラインツール NDExt を利用した方法が最もシンプルです。ここでは Visual Studio を用いた設定方法について次の順で説明します。

Visual Studio でエクステンションのプロジェクトを作成します。

Visual Studio のプロジェクトの設定ダイアログでパッケージの情報を設定します。

Visual Studio 2022 の場合は次のようなダイアログとなっています。

各プロパティの説明は次の通りです。

設定項目	説明
パッケージ ID	パッケージを区別する一意の名前です。 "MyCompany.SomePackage" のように指定します。アルファベットと `.` や数値のみを用いてください。下図の①に該当します。
パッケージバージョン	パッケージを識別するバージョンとして利用します。 “1.0.0” などになります。下図の③に該当します。
作成者	パッケージの作成者の情報です。会社名等を入力してください。
説明	パッケージのタイトルと説明に利用します。任意の文字列となります。パッケージのタイトルには1行目のみ利用されるのに対して、パッケージの説明には全文が利用されます。下図の②と⑤に該当します。
プロジェクト URL	パッケージに関するサイトの Url です。下図の④に該当します。

[拡張機能の管理]ダイアログでは次のように表示されます。

注意

パッケージ ID はすべてのパッケージでユニークになるようにしてください。また日本語名はエラーになるので使わないでください。
説明プロパティはパッケージのタイトル、パッケージの説明として利用します。
新しいバージョンを公開する場合は パッケージバージョン を更新してください。 "1.0.0" で作成した場合の更新は "1.0.1" のようにより大きな数値にします。
バージョン番号の形式が、x.x.x(xは任意の数字)ではない場合は、インストール後に Next Design から無効化できません。

パッケージのビルド

パッケージのビルドには NDExt を用います。コマンドラインで次のようにコマンドを実行すると、実行ディレクトリ以下にあるすべてのエクステンションのプロジェクト( csproj )を探し、ビルドしてパッケージ化します。

C:\MyProjects\NdExt1\NdExt1> ndext pack

ndext pack コマンドの実行に成功すると ndpackages という出力フォルダに nupkg ファイルが作成されます。このファイルがパッケージファイルです。
パッケージファイルは NdExt1.1.0.0.nupkg というように、 {PackageId}.{Version}.nupkg という形式になっています。
nupkg の中身は zip ファイルです。この zip ファイル内にパッケージの定義ファイル( nuspec ファイル)とエクステンションやプロファイルのファイルが含まれています。

nupkg のファイルを閲覧編集できるツールである NuGet Package Explorer で nupkg ファイルを開くと次のようになっています。

extensions フォルダの下の数字は対応する Next Design のバージョンです。そのサブフォルダに配布するエクステンションのバイナリが配置されます。
samples フォルダ , templates フォルダは Next Design のサンプル、テンプレート機能を登録する場合に利用します。 NDExt new でプロジェクトファイルを作成した場合、 pkgContents フォルダの samples フォルダ, templates フォルダが作成されますので、その下にNext Designのプロジェクトファイル、テンプレートプファイルを配置します。 ndext pack でパッケージをビルドすると自動的にパッケージに登録されます。

注意

ビルド時には Next Design を終了しておいてください。 Next Design を起動しているとパッケージ化に失敗する場合があります。
サンプルやテンプレートのファイルやドキュメントなど、日本語のファイル名をパッケージの構成ファイルに含めると失敗するのでファイル名は英語にしてください。

パッケージの公開

Next Designの拡張機能の[設定]ボタンから、 パッケージソース を追加し、この nupkg ファイルを配置すれば公開できます。パッケージソースとはディレクトリもしくは NuGet サーバーと呼ばれる Web サーバー（ Web サイト）となります。ここでは最も簡単な方法としてパッケージソースにフォルダを用いた公開について説明します。

パッケージソースを追加します。
- [ファイル] メニュー > [拡張機能の管理] をクリックして、[拡張機能の管理]ダイアログを開きます。
- [設定]ボタンを押下して[拡張機能の設定]ダイアログを表示し、[追加]ボタンを押下します。
- パッケージを配布するフォルダ指定します。ネットワークやローカルフォルダとなります。
パッケージソースにパッケージをコピーします。

パッケージソースのフォルダにビルドした nupkg ファイルをコピーします。

各ユーザーにパッケージソースの情報を展開し、拡張機能としてインストールしてもらいます。

これで Next Designの拡張機能としてパッケージを公開できます。

ヒント

パッケージソースのフォルダを使った展開には次の方法が考えられます。

ユーザーがアクセスできるネットワークフォルダで共有する
- 社内や組織内のみで共有するには最も単純な方法です。 .nupkg を格納したネットワークフォルダをパッケージソースとして設定してください。
OneDrive、GoogleDrive などでフォルダ共有する
- クラウドで社外ネットワークとも共有する方法です。クラウドドライブ上に .nupkg を格納したフォルダを作り複数ユーザーで共有してください。各自はローカルのドライブをパッケージソースとして設定します。
GitHub / GitLab や Subversion を用いて公開する
- Git 等に馴染みがあり、組織やネットワークを超えて複数のユーザーで簡易的にエクステンションを公開する場合に有効な方法です。 GitHub や Subversion 等のローカルの作業フォルダをパッケージソースとして登録します。
- 構成管理の機能で最新にアップデートします。新しいパッケージをユーザーに公開するにはリポジトリを最新にしてもらう必要がありますが、公開に特別な環境は必要ありません。

パッケージのアップデート

パッケージをアップデートするにはバージョン番号を更新してパッケージを作成します。パッケージソースのフォルダには同じパッケージ Id で複数のバージョンを格納できます。

プロジェクトの設定の パッケージバージョン を新しいバージョンに変更します。例えば "1.1.0" の場合は "1.2.0" のようにします。
パッケージをビルドします。
作成した .nupkg ファイルは、 MyExtA.1.2.0.nupkg のようになっているとします。このファイルをパッケージソースのフォルダに配置します。

例えば、パッケージソースのフォルダ内のファイル構成が次のようになっていると、 MyExtA と MyExtB のパッケージがあり、それぞれ2つのバージョンを公開していることになります。

packageSource\
  MyExtA.1.0.0.nupkg
  MyExtA.1.2.0.nupkg
  MyExtB.2.0.0.nupkg
  MyExtB.2.1.0.nupkg

新しいバージョンを公開すると Next Design のステータスバー上でアップデート可能なパッケージがあることを通知アイコンで確認できます。
アイコンをクリックすると[拡張機能の管理]ダイアログが表示されます。アップデートがあるパッケージを確認できるので[更新]ボタンを押下してアップデートできます。

高度なトピック

ここではパッケージによる配布に関する高度なトピックについて説明します。

スタートページに表示させるプロジェクトを登録する

作成した Visual Studio プロジェクトにある pkgContents フォルダにサンプルやテンプレートの Next Design プロジェクトファイルを配置することで、 Next Design のスタートページに表示できます。

pkgContents フォルダにスタートページに表示させるサンプルやテンプレートのプロジェクトを登録します。

注記

ファイルのプロパティで出力ディレクトリにコピーするように設定する必要はありません。
サンプルとテンプレートはともに、プロジェクトファイルのコピーを新規作成します。動作の大きな違いはありませんが、プロファイルを配布する場合はテンプレート形式で配布することを推奨します。

パッケージを国際対応する

次のように、 タイトル と 説明 に複数言語の設定ができます。現在の UI の表示言語に従って自動的に適切な言語を選択して UI に表示します。

国際対応のパッケージ情報を入力します。

プロジェクトの設定で { "ja" : "日本語の説明" , "en" : "english here"} のように日本語と英語向けのテキストを入力します。タイトルには1行目のみ利用されるのに対して、説明には全文が利用されます。
Next Design の表示言語に従ってパッケージの表示テキストが切り替わるようになります。
なお、 NuGet Package Explorer で確認すると Description が次のようになっています。

動作するNext Designのバージョンを指定する

Next Design のバージョンを指定するにはパッケージのビルド時に -v 引数で動作する Next Design のバージョンを指定してください。このバージョン以上で動作するようになります。

C:\MyProjects\NdExt1\NdExt1> ndext pack -v 2.5

ビルド結果は次のようになります。

独自のパッケージ公開サーバーを用意する

Next Design のパッケージのサーバーは NuGet V2/V3 プロトコルに準拠しています。組織など限られたユーザーのみアクセスできるサーバーをリリースするには独自の NuGet サーバーを準備する必要があります。詳しくは Microsoft の独自の NuGet フィードをホスティングするを参照してください。

パッケージ内のフォルダ構成

すべてのアプリのバージョンで動作させる場合、 extensions の直下の番号を 2.0 にします。

.\extensions\
  2.0\
    NdExt1\
        sampleExtension.dll
        markdig.dll

複数の Next Design のバージョンに対応する場合は次のようにします。

.\extensions\
  2.0\
    NdExt1\
      sampleExtension.dll
      markdig.dll
      manifest.json
  2.5\
    NdExt1\
      sampleExtension.dll
      markdig.dll
      manifest.json

複数のエクステンションを配置する場合は次のように配置をします。

.\extensions\
  2.0\
    NdExt1\
      images\
        xx.png
      ext1.dll
      manifest.json
    NdExt2\
      images\
        xx.png
      ext2.dll
      manifest.json
  
.\samples\
  2.0\
    aaa.nproj

.\templates\
  2.5\
    aaa.nprot
    bbb.nprot

その他のツールを用いたパッケージ作成の方法

Next Design のパッケージは NuGet の仕組みを利用しています。そのため、 Visual Studio と NDExt を用いる以外に次の方法があります。

nuspec ファイルを直接作成し dotnet pack コマンドでパッケージ化する
Nuget Package Explorer を用いて作成する

パッケージ化とそのメリット​

前提​

パッケージの作成​

パッケージのビルド​

パッケージの公開​

パッケージのアップデート​

高度なトピック​

スタートページに表示させるプロジェクトを登録する​

パッケージを国際対応する​

動作するNext Designのバージョンを指定する​

独自のパッケージ公開サーバーを用意する​

パッケージ内のフォルダ構成​

その他のツールを用いたパッケージ作成の方法​