powershell-expert

PowerShell 专家

使用 Microsoft 最佳实践和 PowerShell 生态系统，开发适用于生产环境的 PowerShell 脚本、工具和 GUI。

快速参考

脚本结构

#Requires -Version 5.1

<#
.SYNOPSIS
    Brief description.
.DESCRIPTION
    Detailed description.
.PARAMETER Name
    Parameter description.
.EXAMPLE
    Example-Usage -Name 'Value'
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [ValidateNotNullOrEmpty()]
    [string[]]$Name,

    [switch]$Force
)

begin {
    # One-time setup
}

process {
    foreach ($item in $Name) {
        # Per-item processing
    }
}

end {
    # Cleanup
}

函数模板

function Verb-Noun {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$Name,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('CN')]
        [string]$ComputerName = $env:COMPUTERNAME,

        [switch]$PassThru
    )

    process {
        if ($PSCmdlet.ShouldProcess($Name, 'Action')) {
            # Implementation
            if ($PassThru) { Write-Output $result }
        }
    }
}

工作流

1. 脚本开发

遵循命名和参数约定：

• Verb-Noun 格式，使用经批准的动词（Get-Verb）
• 使用验证属性进行强类型定义
• 通过 ValueFromPipeline 支持管道
• 对破坏性操作使用 -WhatIf/-Confirm

完整指南请参阅 best-practices.md。

2. GUI 开发

简单对话框使用 Windows Forms，复杂界面使用 WPF/XAML：

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing

$form = New-Object System.Windows.Forms.Form -Property @{
    Text          = 'Title'
    Size          = New-Object System.Drawing.Size(400, 300)
    StartPosition = 'CenterScreen'
}

有关控件、事件和模板，请参阅 gui-development.md。

3. PowerShell Gallery 集成

使用 PSResourceGet 搜索和安装模块：

# Search gallery
Find-PSResource -Name 'ModuleName' -Repository PSGallery

# Install module
Install-PSResource -Name 'ModuleName' -Scope CurrentUser -TrustRepository

使用 scripts/Search-Gallery.ps1 可进行增强搜索。

完整的 cmdlet 参考请参阅 powershellget.md。

关键模式

错误处理

try {
    $result = Get-Content -Path $Path -ErrorAction Stop
}
catch [System.IO.FileNotFoundException] {
    Write-Error "File not found: $Path"
    return
}
catch {
    throw
}

使用 Splatting 提高可读性

$params = @{
    Path        = $sourcePath
    Destination = $destPath
    Recurse     = $true
    Force       = $true
}
Copy-Item @params

管道最佳实践

# Stream output immediately
foreach ($item in $collection) {
    Process-Item $item | Write-Output
}

# Accept pipeline input
param(
    [Parameter(ValueFromPipeline)]
    [string[]]$InputObject
)
process {
    foreach ($obj in $InputObject) {
        # Process each
    }
}

模块推荐

推荐模块时，请搜索 PowerShell Gallery。以下是常见的入门选择——推荐前务必通过模块验证进行核实：

类别	常用模块
Azure	Az、Az.Compute、Az.Storage
测试	Pester、PSScriptAnalyzer
控制台	PSReadLine、Terminal-Icons
密钥	Microsoft.PowerShell.SecretManagement
Web	Pode（Web 服务）、PoshRSJob（异步）
GUI	WPFBot3000、PSGUI

文档查询

请通过实时来源核实 cmdlet 语法和模块可用性，而不要依赖记忆中的细节。每个 learn.microsoft.com 上的 PowerShell 页面都由公开 MicrosoftDocs 仓库中的 Markdown 生成——请获取 Markdown，而不是渲染后的页面。源文件体积小得多，不包含导航界面或 JavaScript，并且能原样保留语法块和参数表。

原始 Markdown 源（WebFetch）

使用 WebFetch 工具访问 raw.githubusercontent.com。直接根据以下模板构造 URL — 不要先搜索。

命令类型	URL 模板
核心 PowerShell Get-ChildItem、Write-Output、Invoke-Command	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/{Module}/{Cmdlet}.md
概念性内容 about_Splatting、about_CommonParameters	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/Microsoft.PowerShell.Core/About/{about_Topic}.md
仅限 Windows Get-ADUser、Get-DnsServerZone、Get-MpComputerStatus	https://raw.githubusercontent.com/MicrosoftDocs/windows-powershell-docs/main/docset/winserver2025-ps/{Module}/{Cmdlet}.md
Gallery / 打包 Install-PSResource、Find-PSResource	https://raw.githubusercontent.com/MicrosoftDocs/powershell-docs-psget/main/powershell-gallery/powershellget-3.x/Microsoft.PowerShell.PSResourceGet/{Cmdlet}.md
卫星模块 Invoke-ScriptAnalyzer、Get-Secret	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs-Modules/main/reference/ps-modules/{Module}/{Cmdlet}.md

{version} 为 5.1、7.4、7.5、7.6、7.7 之一。根据上下文确定版本 — #Requires、pwsh、ISE 或明确说明的平台。如果没有任何线索，请同时获取 7.5 和 5.1 版本，并说明参数差异，因为选错版本会得到看似正确、但在用户的 shell 中无法运行的语法。

WebFetch 提示词：提取完整的语法块、包含类型和默认值的完整参数表，以及示例。

URL 构造遵循以下三条规则：

1. 大小写有影响。 原始路径区分大小写，而 learn.microsoft.com 不区分。 .../activedirectory/Get-ADUser.md 会返回 404；.../ActiveDirectory/Get-ADUser.md 会返回 200。保留模块名称原有的大小写。
2. 绝不指向文件夹。 Raw 只提供文件内容 — 任何以 / 结尾的 URL 都会返回 404。它没有目录列表接口。
3. 转换页面 URL。 将 github.com/{owner}/{repo}/blob/{branch}/{path} 改写为 raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}。

如何将 cmdlet 路由到正确的存储库、模块和版本文件夹，请参阅 doc-sources.md，其中还列有完整的模块清单和 404 故障排查表。无法确定正确路径时，请查阅该文档。

回退链

只有在失败时才逐步升级，每次只进行一步：

步骤	工具	使用时机
1	WebFetch 原始 Markdown	默认 — 始终优先尝试
2	WebFetch contents API https://api.github.com/repos/{owner}/{repo}/contents/{path}	文件夹名称未知时。返回可顺利解析的纯 JSON；未认证时每小时 60 次请求
3	WebFetch learn.microsoft.com	没有原始源文件时（第三方模块、仅在 Learn 上发布的文章）
4	WebSearch	无法推导路径时。查询：{Cmdlet-Name} site:learn.microsoft.com/en-us/powershell — 然后将结果转换回原始 URL，并返回步骤 1
5	本地执行	工具不可用时。请用户运行 Get-Help {Cmdlet} -Full 或 Get-Command {Cmdlet} -Syntax

如果所有步骤都失败，请明确说明不确定性，而不要猜测：

"我无法通过在线文档核实此内容。请运行以下命令确认： Get-Command Cmdlet-Name -Syntax"

模块验证

Gallery 软件包没有 Markdown 源文件。直接对列表页面使用 WebFetch：

• URL：https://www.powershellgallery.com/packages/{ModuleName}
• 提示词：Extract: module name, latest version, last updated date, total downloads, and whether it shows any deprecation warning or 'unlisted' status

404 表示该模块可能不存在——使用 WebSearch 搜索 {ModuleName} PowerShell module site:powershellgallery.com 进行确认。如果两个工具都不可用，请执行 scripts/Search-Gallery.ps1 -Name 'ModuleName'。

场景	要求
用户询问模块 X 是否存在	必须在 Gallery 上验证
推荐特定模块	必须验证该模块存在且未弃用
声明模块版本要求	必须在 Gallery 上检查当前版本
提供精确的 cmdlet 语法	应该对照原始 Markdown 验证
一般最佳实践	静态参考资料即可

良好（已根据实时数据验证）：

“ImportExcel（v7.8.10，2024 年 10 月更新，下载量超过 1,700 万次）提供 Export-Excel，无需安装 Excel 即可创建电子表格。”

不佳（未经验证）：

“使用 Excel-Tools 模块导出数据。” ← 该模块可能不存在

渲染后的文档

手动浏览这些页面；获取资料时优先使用上述原始来源。

资源	URL
PowerShell 文档	https://learn.microsoft.com/en-us/powershell/
模块浏览器	https://learn.microsoft.com/en-us/powershell/module/
PowerShell Gallery	https://www.powershellgallery.com

参考文件

主题	文件
文档路由、原始 URL 映射、404 故障排除	references/doc-sources.md
命名、参数、管道、错误处理、代码风格	references/best-practices.md
Windows Forms、WPF、控件、事件、模板	references/gui-development.md
查找、安装、更新、发布模块	references/powershellget.md

包含的脚本

脚本	用途
scripts/Search-Gallery.ps1	格式化的 PowerShell Gallery 搜索，支持旧版 Find-Module 回退