The Will Will Web

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

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

📅 2022/03/10 08:20 📁 Windows, 系統管理

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

image

  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 專案資料夾

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

  3. 建立 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)，所以必須認真的填寫。

  4. 加入 PowerShell Module 主程式 ( *.psm1 )

    原始碼: linqpad-folders-powershell-module.psm1

  5. 設定模組宣告檔 (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

  6. 使用 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'
    )

  7. 加入 LICENSE 授權宣告檔

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

  8. 測試發行到 PowerShell Gallery

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

    Publish-Module `
    -Path "G:\Projects\linqpad-folders-powershell-module\" `
    -NuGetApiKey $env:PowerShellGalleryApiKey `
    -WhatIf `
    -Verbose

  9. 正式發行到 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 的完整過程，以下則是安裝與使用的方法：

  1. 安裝模組

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

    若是要更新版本，可以使用以下命令：

    Update-Module linqpad-folders-powershell-module -Force

  2. 使用模組中的 Functions 或 Cmdlets

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

相關連結

留言評論