PowerShell Advent Calendar 2016 3日目の記事です。
qiita.com
はじめに
先月簡単なPowerShellモジュールを作ってPowerShell Galleryで公開しました。
その際に公式なドキュメントが全然無く苦労したので本エントリで手順をまとめることにしました。
内容についてはあまり詳細には触れず最低限の手順だけを記載し、モジュールを作って公開するための第一歩になれば良いかなというスタンスで進めていきます。
作成したモジュールについて
最初に軽く前提の説明を。
偉大なる先駆者たち
すべてのきっかけは@mzpさんのこのツイートからはじまっています。
そして@p_ck_さんのVim版。
PSSushiBar
これらの影響を受けて私もPowerShell版を作りました。
PSSushiBarという名のPowerShellモジュールとして作成し、ソースはGitHubに上げています。
github.com
はじめてのPowerShellモジュール公開
ここから本題に入ります。
このPSSushiBarを例に、モジュールの設定からPowerShell Galleryへの登録、モジュール公開までの手順を順に説明します。
0. 前提条件
今回は64bit版 Windows 10、PowerShell 5.1の環境で試しています。
モジュールの機能はPowerShell 2.0から、モジュール公開のための機能(PowerShellGet)はPowerShell 3.0から利用可能で、古いバージョンではパラメーターの名称や手順が異なる場合がありますのでご注意ください。
1. PowerShell Galleryのユーザー登録
PowerShell Galleryでモジュールを公開するにあたって最初にユーザー登録が必要です。
ユーザー登録にはMicrosoftアカウントを使用しますので予めアカウントを作っておいてください。
はじめに、ブラウザでPowerShell Galleryにアクセスし、画面右上のRegister
をクリックします。
サインインの方法を聞かれますので、Personal account
を選びます。
(企業アカウントであればWork or school account
を選ぶことになるでしょうが今回は割愛します)
契約条件の更新が出た場合はそのまま次へ
。
アクセス許可を求められるのではい
を選択します。
続けてPowerShell Galleryで使うユーザー名(私はstknohgにしています)を入力しRegister
をクリックします。
これでユーザー登録は完了し以下の画面に遷移します。
モジュールを公開するには後述するNuget API Keyが必要になりますので、View your profile
をクリックしてアカウント情報を確認します。
画面下部の認証情報にAPI Key
がありますのでこの内容を控えておきます。
2. モジュールの設定
次に作成するモジュールの設定について説明します。
本エントリではモジュール作成自体の詳細には触れません。
そちらに関しては、PowerShell 4.0時点の内容ですが、ぎたぱそ先生の以下の記事が非常に有用なので参考にしてください。
tech.guitarrapc.com
本エントリで必要な前提知識
モジュールの公開に必要な前提知識について軽く説明しておきます。
モジュールマニフェスト
- 自作したモジュールを公開するためにはモジュールマニフェスト(
[モジュール名].psd1
)ファイルが必要になります。
- モジュールマニフェストはモジュールのバージョン等のメタ情報を記載するファイルとなり、名前は必ず
[モジュール名].psd1
にし、モジュール全体のルートディレクトリに配置する必要があります。
モジュールの種類とモジュールマニフェスト
先述のぎたぱそ先生の記事にある通り、モジュールはScript Modules
、Binary Modules
、Manifest Modules
、Dynamic Modules
の4種類存在しています。
この中で公開可能なのはScript Modules
、Binary Modules
、Manifest Modules
の3種類です。
モジュールを公開するのにモジュールマニフェスト(*.psd1)が必須であるなら全てManifest Modules
になると思われがちですが、モジュールマニフェストの記載方法よってモジュールの種類が分かれます。
モジュールの種類を何にするかはその用途や規模によって変わると思いますので適宜選択してください。
よくわからなければとりあえずManifest Modules
にしておいて良いと思います。
ディレクトリ構成
PSSushiBarのディレクトリ構成は下図の様になっています。
GitHubでソースを公開しているため、README.md
やLICENSE
がソースコードのルートに存在していますが、モジュールの公開で使うのはモジュールマニフェスト(PSSushibar.psd1
ファイル)のあるPSSushibar
ディレクトリになります。
PSSushibar.psm1
がモジュールのソースでここに必要な関数等が記述されています。
モジュールを公開するとモジュールマニフェストのあるディレクトリ配下のすべてのファイルがPowerShell Galleryにアップロードされダウンロードおよびインストール可能になります。
アップロードされるファイルを一部除外するといった例外を設けることはできません。
このため、上図の様にソースコードのルートとは別にモジュールのルートディレクトリを分けておき、アップロードしたくないファイル(PSSushiBarではREADME.mdなど)を別に分けることをお勧めします。
モジュールマニフェストの作成
モジュールマニフェストは基本的にNew-ModuleManifest
コマンドレットを使って作成します。
指定可能なパラメーターは多くありますが、最低限-Path
パラメーターだけ指定すればOKです。
New-ModuleManifest -Path [モジュールマニフェスト(*.psd1ファイル)のパス]
実行例)
New-ModuleManifest -Path .\PSSushibar.psd1
コマンドレットを実行するとモジュールマニフェストが生成されますので、テキストエディタ等でその内容を適宜編集します。
モジュールマニフェストの内容について
PSSushiBar.psd1
の内容を基に最低限設定が必要な項目について触れます。
個別の項目の詳細についてはMSDNの How to Write a PowerShell Module Manifest を参照してください。
@{
GUID = '********-****-****-****-************'
ModuleVersion = '1.0'
Description = '🍣'
Author = 'stknohg'
CompanyName = 'stknohg'
Copyright = '(c) 2016 stknohg. All rights reserved.'
NestedModules = @('PSSushiBar.psm1')
FunctionsToExport = @('Get-SushiCount', 'Start-SushiBar', 'Stop-SushiBar')
PrivateData = @{
PSData = @{
ProjectUri = 'https://github.com/stknohg/PSSushiBar'
LicenseUri = 'https://github.com/stknohg/PSSushiBar/blob/master/LICENSE'
Tags = @('🍣', 'sushi', '寿司')
}
}
}
項目 |
必須 |
内容 |
GUID |
〇 |
モジュールの識別子となるGUIDです。必ずNew-ModuleManifest やNew-GUID で生成する様にしてください。 |
ModuleVersion |
〇 |
モジュールのバージョンです。バージョンの記載方法は.NETアセンブリのそれと同じで [Major].[Minor].[BuildNumber].[Revision] になります。 |
Description |
- |
モジュールの説明。後から変更可能です。 |
Author |
- |
著者名。後から変更可能です。 |
CompanyName |
- |
会社名。後から変更可能です。 |
Copyright |
- |
コピーライト。後から変更可能です。 |
RootModule / NestedModules |
〇 |
モジュールの種類に応じてRootModuleおよびNestedModulesを設定します。PSSushiBarではNestedModulesを指定しManifest Modules にしています。*1 |
TypesToProcess |
△ |
公開する型データ(*.type.ps1xml)がある場合設定します。 |
FormatsToProcess |
△ |
公開するフォーマット(*.format.ps1xml)がある場合設定します。 |
FunctionsToExport |
△ |
公開するファンクション名を設定します。 |
CmdletsToExport |
△ |
公開するコマンドレット名を設定します。 |
VariablesToExport |
△ |
公開する変数がある場合設定します。 |
AliasesToExport |
△ |
公開するエイリアスがある場合設定します。 |
PrivateData |
- |
PowerShell Galleryに載せる各種情報などを記載します。 |
以上で公開までの前準備は完了です。
3. モジュールの公開
次に作成したモジュールをPowerShell Galleryに公開します。
PowerShellGet
モジュールを公開するにはPowerShellGet
の機能を使用します。
PowerShellGet
はPowerShell 5.0以降であれば標準でインストール済みです。
PowerShell 5.0以前の環境の場合はPowerShell Galleryみインストーラーがありますので、インストーラーをダウンロードしてインストールしておいてください。
モジュールマニフェストの検証
モジュールを公開する前にTest-ModuleManifest
コマンドレットを使いモジュールマニフェストの内容を検証します。
Test-ModuleManifest -Path '[モジュールマニフェスト(*.psd1ファイル)のパス]'
実行例)
Test-ModuleManifest -Path "C:\Project\github\PSSushiBar\PSSushiBar\PSSushibar.psd1"
エラーが出なければ成功です。
モジュールの公開
検証が終わったらPublish-Module
コマンドレットを使用してモジュールを公開します。
パラメーターはいろいろありますが、最低限以下の様に-Path
と-NugetApiKey
を指定すればOKです。
-NugetApiKey
に先ほどPowerShell Galleryから取得したAPI Keyを設定してください。
Publish-Module -Path [モジュールのルートパス] -NugetApiKey [PowerShell Galleryから取得したAPIKey]
実行例)
$params = @{
Path = 'C:\Project\github\PSSushiBar\PSSushiBar'
NuGetApiKey = '********-****-****-****-************'
}
Publish-Module @params
内部でNugetを使っていますので、Nuget.exe
の更新など聞かれる場合があります。
エラーが出ずに終了すれば完了です。
公開情報の確認
PowerShell GalleryのMy AccountからManage My Items
を選択すると、公開したモジュールの情報を確認できます。
必要に応じてWEB上からモジュール情報を変更することも可能です。
4. モジュールのインストール
公開したモジュールはFind-Module
で検索、Install-Module
でインストールできる様になりますので実際に試して最終確認をします。
検索
Find-Module -Name PSSushiBar
インストール
Install-Module -Name PSSushiBar -Scope CurrentUser
確認
Get-Module PSSushiBar -ListAvailable
5. モジュールのバージョンアップ
公開したモジュールをバージョンアップする場合はモジュールマニフェストのModuleVersion
を新しいバージョンに書き換え、再度Publish-Module
すればOKです。
まとめ
以上となります。
簡単にですが自作したモジュールをPowerShell Galleryに公開するまでの手順をまとめました。
手順や情報を調べるのが面倒ですが、一旦覚えてしまえばさほど苦労する手順ではありませんので是非みなさんも試してみてください。
参考にしたサイト
補足として本エントリを書くにあたって参考にしたサイトを記載しておきます。