The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

如何封裝 PowerShell 模組並且上架到 PowerShell Gallery 資源庫

昨天發行了一個 linqpad-folders-powershell-module 模組到 PowerShell Gallery,我打算特別用這篇文章記錄一下發行的過程與注意事項。

  1. 登入 PowerShell Gallery 並取得一把 API Key

    image

    建立的時候要設定以下欄位:

    • Key Name: PushPackages
    • Expires in: 365 days
    • Select Scopes: Push > Push new packages and package versions
    • Glob Pattern: * (wildcard)

    image

    建立完成後,要立刻按下 Copy 複製 API Key 下來,因為離開此頁面之後就再也無法取得了!

    image

  2. 建立 PowerShell Module 專案並建立 Module Manifest 檔 ( *.psd1 )

    先建立一個專案資料夾

    mkdir linqpad-folders-powershell-module
    cd linqpad-folders-powershell-module
    

    加入 PowerShell Module 主程式: linqpad-folders-powershell-module.psm1

    使用 New-ModuleManifest 快速建立一個模組宣告檔 (Module Manifest) 範本

    New-ModuleManifest `
      -Path .\linqpad-folders-powershell-module.psd1 `
      -PassThru
    

    這個 linqpad-folders-powershell-module.psd1 檔案包含著所有該模組的完整定義,之後要上架的時候也會拿這裡的資訊產生相對應的 linqpad-folders-powershell-module.nuspec 封裝規格檔 (NuGet),所以必須認真的填寫。

  3. 設定模組宣告檔 (Module Manifest)

    這裡最重要的一個設定,就是「模組名稱」了,模組名稱預設會等於 *.psd1 的檔名,而且通常該檔案所在的「資料夾名稱」會等於「模組名稱」。

    其次就是必要的 ModuleVersion 模組版本設定,這裡必須設定為 X.X.X.X 這樣的格式,建議將預設的 0.0.1 修改為 0.0.1.0 這樣的格式。

    檔案中的 RootModule 用來指定主要的 PowerShell Module 檔案路徑 (*.psm1),所有的 Functions 與 Cmdlets 都會擺在這個檔案內。

    還有像是 AuthorCompanyNameCopyrightDescription 就盡量寫清楚。

    上架模組最好可以宣稱哪些東西要匯出給使用者使用,所以 FunctionsToExportCmdletsToExportVariablesToExportAliasesToExport 記得要依據實際狀況設定。

    然後還有個 PrivateData 要設定幾項重要的 Metadata,像是 TagsLicenseUriProjectUriIconUri 能設定就都設定上去。

    最後,你可以用 Test-ModuleManifest 測試模組宣告檔有沒有設定錯誤:

    Test-ModuleManifest -Path .\linqpad-folders-powershell-module.psd1
    
  4. 使用 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 才行。

    image

    我在參數宣告之前加入了以下 [CmdletBinding(SupportsShouldProcess)] 宣告:

    function Set-LINQPadFolder {
    
        [CmdletBinding(SupportsShouldProcess)]
        param(
            [Parameter()]
            [string]
            $DefaultPath = '~/Documents',
    
            [Parameter()]
            [string]
            $TargetPath = '~/Dropbox/Tools/LINQPad'
        )
    
  5. 加入 LICENSE 授權宣告檔

    我一般都加入 MIT License 授權的內容。

  6. 測試發行到 PowerShell Gallery

    透過以下命令,就可以測試看看能否成功發佈模組上去,這裡的 -WhatIf 參數不會將你的模組直接發佈,而是測試看看發佈時會不會有甚麼問題。

    Publish-Module `
        -Path "G:\Projects\linqpad-folders-powershell-module\" `
        -NuGetApiKey $apiKey `
        -WhatIf `
        -Verbose
    
  7. 正式發行到 PowerShell Gallery

    只要將 -WhatIf 參數移除,就可以執行正式的發行作業。

    Publish-Module `
        -Path "G:\Projects\linqpad-folders-powershell-module\" `
        -NuGetApiKey $apiKey `
        -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 的完整過程,以下則是安裝與使用的方法:

  1. 安裝模組

    Install-Module linqpad-folders-powershell-module -Force
    

    若是要更新版本,可以使用以下命令:

    Update-Module linqpad-folders-powershell-module -Force
    
  2. 使用模組中的 Functions 或 Cmdlets

    Set-LINQPadFolder -TargetPath '~/Dropbox/Tools/LINQPad'
    

相關連結