はじめてのPowerShellモジュール公開

PowerShell Advent Calendar 2016 3日目の記事です。

qiita.com

はじめに

先月簡単なPowerShellモジュールを作ってPowerShell Galleryで公開しました。

その際に公式なドキュメントが全然無く苦労したので本エントリで手順をまとめることにしました。

内容についてはあまり詳細には触れず最低限の手順だけを記載し、モジュールを作って公開するための第一歩になれば良いかなというスタンスで進めていきます。

作成したモジュールについて

最初に軽く前提の説明を。

偉大なる先駆者たち

すべてのきっかけは@mzpさんのこのツイートからはじまっています。

sushiが流れる様子です pic.twitter.com/Dp7OpyXFRt
— mzp (@mzp) 2016年11月19日

そして@p_ck_さんのVim版。

Vim だってステータスラインに🍣を流せる pic.twitter.com/W7qAtH2ckv
— Pocke(ぽっけ) (@p_ck_) 2016年11月19日

PSSushiBar

これらの影響を受けて私もPowerShell版を作りました。

流行に乗ってPowerShellでも🍣を流してみた。 pic.twitter.com/qhQT2ARygy
— stknohg.ps1 (@stknohg) 2016年11月21日

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をクリックします。

f:id:stknohg:20161123231840p:plain

サインインの方法を聞かれますので、Personal accountを選びます。
(企業アカウントであればWork or school accountを選ぶことになるでしょうが今回は割愛します)

f:id:stknohg:20161123231920p:plain

契約条件の更新が出た場合はそのまま次へ。

f:id:stknohg:20161123232152p:plain

アクセス許可を求められるのではいを選択します。

f:id:stknohg:20161123232230p:plain

続けてPowerShell Galleryで使うユーザー名(私はstknohgにしています)を入力しRegisterをクリックします。

f:id:stknohg:20161123233325p:plain

これでユーザー登録は完了し以下の画面に遷移します。

モジュールを公開するには後述するNuget API Keyが必要になりますので、View your profileをクリックしてアカウント情報を確認します。

f:id:stknohg:20161123232324p:plain

画面下部の認証情報にAPI Keyがありますのでこの内容を控えておきます。

f:id:stknohg:20161123232520p:plain

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のディレクトリ構成は下図の様になっています。

f:id:stknohg:20161202061937p:plain

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 を参照してください。

#
# Module manifest例
#
@{
    GUID = '********-****-****-****-************' # 自分のGUIDを設定する
    ModuleVersion = '1.0'
    Description = '🍣'

    Author = 'stknohg'
    CompanyName = 'stknohg'
    Copyright = '(c) 2016 stknohg. All rights reserved.'

    NestedModules = @('PSSushiBar.psm1')

    # TypesToProcess = @()
    # FormatsToProcess = @()
    FunctionsToExport = @('Get-SushiCount', 'Start-SushiBar', 'Stop-SushiBar')
    # CmdletsToExport = @()
    # VariablesToExport = '*'
    # AliasesToExport = @()

    PrivateData = @{
        PSData = @{
            ProjectUri = 'https://github.com/stknohg/PSSushiBar'
            LicenseUri = 'https://github.com/stknohg/PSSushiBar/blob/master/LICENSE'
            # IconUri = ''
            # ReleaseNotes = ''
            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"

f:id:stknohg:20161130064054p:plain

エラーが出なければ成功です。

モジュールの公開

検証が終わったら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

f:id:stknohg:20161203002827p:plain

内部でNugetを使っていますので、Nuget.exeの更新など聞かれる場合があります。
エラーが出ずに終了すれば完了です。

公開情報の確認

PowerShell GalleryのMy AccountからManage My Itemsを選択すると、公開したモジュールの情報を確認できます。

f:id:stknohg:20161130064124p:plain

f:id:stknohg:20161130064243p:plain

必要に応じてWEB上からモジュール情報を変更することも可能です。

f:id:stknohg:20161130064314p:plain

4. モジュールのインストール

公開したモジュールはFind-Moduleで検索、Install-Moduleでインストールできる様になりますので実際に試して最終確認をします。

検索

Find-Module -Name PSSushiBar

f:id:stknohg:20161130064610p:plain

インストール

Install-Module -Name PSSushiBar -Scope CurrentUser

f:id:stknohg:20161130064636p:plain

確認

Get-Module PSSushiBar -ListAvailable

f:id:stknohg:20161202065845p:plain

5. モジュールのバージョンアップ

公開したモジュールをバージョンアップする場合はモジュールマニフェストのModuleVersionを新しいバージョンに書き換え、再度Publish-ModuleすればOKです。

まとめ

以上となります。

簡単にですが自作したモジュールをPowerShell Galleryに公開するまでの手順をまとめました。
手順や情報を調べるのが面倒ですが、一旦覚えてしまえばさほど苦労する手順ではありませんので是非みなさんも試してみてください。

参考にしたサイト

補足として本エントリを書くにあたって参考にしたサイトを記載しておきます。

Building a PowerShell Module – Rambling Cookie Monster
- 全体的に参考にしました。
The PowerShell Gallery | Microsoft Docs
- 公式のドキュメントです。

*1:詳細についてはHow to Write a PowerShell Module Manifest参照してください

しばたテックブログ

気分で書いている技術ブログです。

はじめてのPowerShellモジュール公開

はじめに

作成したモジュールについて

偉大なる先駆者たち

PSSushiBar

はじめてのPowerShellモジュール公開

0. 前提条件

1. PowerShell Galleryのユーザー登録

2. モジュールの設定

本エントリで必要な前提知識

ディレクトリ構成

モジュールマニフェストの作成

モジュールマニフェストの内容について

3. モジュールの公開

PowerShellGet

モジュールマニフェストの検証

モジュールの公開

公開情報の確認

4. モジュールのインストール

検索

インストール

確認

5. モジュールのバージョンアップ

まとめ

参考にしたサイト