昨天發行了一個 linqpad-folders-powershell-module 模組到 PowerShell Gallery,我打算特別用這篇文章記錄一下發行的過程與注意事項。
-
登入 PowerShell Gallery 並取得一把 API Key
建立的時候要設定以下欄位:
- Key Name:
PushPackages
- Expires in:
365 days
- Select Scopes:
Push
> Push new packages and package versions
- Glob Pattern:
*
(wildcard)
建立完成後,要立刻按下 Copy 複製 API Key 下來,因為離開此頁面之後就再也無法取得了!
-
先建立 PowerShell Module 專案資料夾
mkdir linqpad-folders-powershell-module
cd linqpad-folders-powershell-module
-
建立 Module Manifest 檔 ( *.psd1
)
使用 New-ModuleManifest
快速建立一個模組宣告檔 (Module Manifest) 範本
New-ModuleManifest `
-Path .\linqpad-folders-powershell-module.psd1 `
-PassThru
這個 linqpad-folders-powershell-module.psd1
檔案包含著所有該模組的完整定義,之後要上架的時候也會拿這裡的資訊產生相對應的 linqpad-folders-powershell-module.nuspec
封裝規格檔 (NuGet),所以必須認真的填寫。
-
加入 PowerShell Module 主程式 ( *.psm1
)
原始碼: linqpad-folders-powershell-module.psm1
-
設定模組宣告檔 (Module Manifest)
這裡最重要的一個設定,就是「模組名稱」了,模組名稱預設會等於 *.psd1
的檔名,而且通常該檔案所在的「資料夾名稱」會等於「模組名稱」。
其次就是必要的 ModuleVersion
模組版本設定,這裡必須設定為 X.X.X.X
這樣的格式,建議將預設的 0.0.1
修改為 0.0.1.0
這樣的格式。
檔案中的 RootModule
用來指定主要的 PowerShell Module 檔案路徑 (*.psm1
),所有的 Functions 與 Cmdlets 都會擺在這個檔案內。
還有像是 Author
、CompanyName
、Copyright
、Description
就盡量寫清楚。
上架模組最好可以宣稱哪些東西要匯出給使用者使用,所以 FunctionsToExport
、CmdletsToExport
、VariablesToExport
、AliasesToExport
記得要依據實際狀況設定。
然後還有個 PrivateData
要設定幾項重要的 Metadata,像是 Tags
、LicenseUri
、ProjectUri
、IconUri
能設定就都設定上去。
最後,你可以用 Test-ModuleManifest
測試模組宣告檔有沒有設定錯誤:
Test-ModuleManifest -Path .\linqpad-folders-powershell-module.psd1
-
使用 PSScriptAnalyzer 分析 PowerShell Module (*.psm1
) 是否有問題
先安裝 PSScriptAnalyzer 模組
Install-Module -Name PSScriptAnalyzer
用以下命令分析 linqpad-folders-powershell-module.psm1
程式碼是否有建議改善事項:
Invoke-ScriptAnalyzer -Path ./linqpad-folders-powershell-module.psm1
由於我的 Function 名稱為 Set-LINQPadFolder
,使用了 Set-
開頭的命名,因此被要求要設定支援 ShouldProcess
才行。
我在參數宣告之前加入了以下 [CmdletBinding(SupportsShouldProcess)]
宣告:
function Set-LINQPadFolder {
[CmdletBinding(SupportsShouldProcess)]
param(
[Parameter()]
[string]
$DefaultPath = '~/Documents',
[Parameter()]
[string]
$TargetPath = '~/Dropbox/Tools/LINQPad'
)
-
加入 LICENSE
授權宣告檔
我一般都加入 MIT License 授權的內容。
-
測試發行到 PowerShell Gallery
透過以下命令,就可以測試看看能否成功發佈模組上去,這裡的 -WhatIf
參數不會將你的模組直接發佈,而是測試看看發佈時會不會有甚麼問題。
Publish-Module `
-Path "G:\Projects\linqpad-folders-powershell-module\" `
-NuGetApiKey $env:PowerShellGalleryApiKey `
-WhatIf `
-Verbose
-
正式發行到 PowerShell Gallery
只要將 -WhatIf
參數移除,就可以執行正式的發行作業。
Publish-Module `
-Path "G:\Projects\linqpad-folders-powershell-module\" `
-NuGetApiKey $env:PowerShellGalleryApiKey `
-Verbose
最後如果出現以下訊息,就代表成功發佈了!
VERBOSE: Successfully published module 'linqpad-folders-powershell-module' to the module publish location 'https://www.powershellgallery.com/api/v2/package/'. Please allow few minutes for 'linqpad-folders-powershell-module' to show up in the search results.
上述完整的原始碼放在這裡: https://github.com/doggy8088/linqpad-folders-powershell-module
以上就是發行 PowerShell 模組到 PowerShell Gallery 的完整過程,以下則是安裝與使用的方法:
-
安裝模組
Install-Module linqpad-folders-powershell-module -Force
若是要更新版本,可以使用以下命令:
Update-Module linqpad-folders-powershell-module -Force
-
使用模組中的 Functions 或 Cmdlets
Set-LINQPadFolder -TargetPath '~/Dropbox/Tools/LINQPad'
相關連結