PowerShell 命名约定和最佳实践

---

PowerShell 采用独特的动词-名词对命名约定，提高了用户和开发人员的清晰度。使用此约定，命令 (Cmdlet)、函数和别名变得具有自我描述性，您可以快速推断 Cmdlet 将执行的操作。

我将在本 PowerShell 教程中讨论有关 PowerShell 命名约定的所有内容。

PowerShell 命名约定

使用 PowerShell 时，遵守既定的命名约定可以提高脚本和模块的可读性和可维护性。

Cmdlet 和函数：对于 cmdlet 和函数，请使用经过批准的动词，后跟单数名词，并用连字符分隔。 PowerShell 提供了经过批准的动词列表以保持一致性。例如，Get-Process 优于 ObtainProcess。

变量：变量应该有清晰的、描述性的名称来反映其用途。对局部变量使用驼峰命名法，对全局变量和常量使用 PascalCase。命名良好的变量的一个示例是 $userInput。

脚本和模块：命名脚本和模块时，选择能够简洁描述其功能的名称。避免使用缩写，而是选择完整的单词以消除歧义。

Cmdlet

获取项目

Function

转换为 Json

Variable

$totalCount

Script

备份服务器.ps1

Module

用户管理.psm1

请记住，cmdlet、变量、脚本和模块之间的一致性有利于您和其他将来可能使用或维护您的代码的人。通过坚持这些基本约定，您将提高 PowerShell 脚本的清晰度和专业性。

PowerShell Cmdlet 命名

在 PowerShell 中，cmdlet 命名是一种提供清晰、自描述命令的系统方法。此约定可确保整个 PowerShell 生态系统的一致性，使您能够更轻松地有效识别和利用 cmdlet。

动名词对用法

PowerShell 中的 Cmdlet 遵循动词-名词模式，其中动词指示 cmdlet 将执行的操作，名词指定执行操作的实体。例如，cmdlet Get-Command 的结构使得 Get 是检索信息的操作，而 Command 是正在检索的实体。坚持这种模式对于保持脚本的一致性和可预测性至关重要。

标准动词定义和用法

PowerShell 定义了一组批准的动词，以确保 cmdlet 执行的操作的一致性。使用Get-Verb可以为您提供这些动词的列表。对于创建等常见操作，您应该使用新建，对于阅读，选择获取，对于更新，应用设置。以下是一些标准动词及其预期动作的简短列表：

• 获取：检索数据
• 设置：修改现有数据
• 添加：追加数据
• 删除：删除数据
• 新建：创建新实例
• 请务必使用这些批准的动词，使您的 cmdlet 直观并与其他人创建的 cmdlet 保持一致。

名词命名最佳实践

命名 cmdlet 的名词部分时，应该具体并避免歧义。名词应反映 cmdlet 所作用的实体，并且不应包含动词。避免使用复数名词以符合 PowerShell 的命名约定。以下是良好名词用法的示例：

• 对于列出进程的 cmdlet：Get-Process（不是 Get-Processes）
• 复制文件：Copy-Item（不是Copy-Items或Copy-File）

PowerShell脚本和函数结构

在 PowerShell 中，脚本和函数的结构极大地提高了它们的清晰度和易用性。正确的命名和设计可确保您的代码可访问且可维护。

脚本模块设计

您的脚本模块充当一组函数的容器。必须：

• 使用 PascalCase 格式的描述性名称，例如 UserManagement 或 NetworkDiagnostics。
• 包括包含您的函数的 .psm1 文件，以及描述模块及其依赖项的 .psd1 清单文件。

PowerShell 函数定义约定

PowerShell 中定义良好的函数具有以下特征：

• 名称遵循 - 格式，名词采用 PascalCase，例如 Get-Process。
• 动词应该来自批准的列表，可以通过执行 Get-Verb 来检索。
• 对于高级功能，请使用 CmdletBinding 属性启用类似 cmdlet 的功能。

参数命名最佳实践

参数对于脚本的灵活性至关重要。确保您的参数名称是：

• 清晰且具有描述性：例如，使用 -FilePath 而不是 -Path。
• 没有下划线或连字符的 PascalCase，例如 -UserName。

对于接受特定值的参数：

• 使用 ValidateSet 属性来限制输入，从而提高可用性并减少错误。
• 要接受来自管道的输入，请使用 ValueFromPipeline 属性，允许用户将值直接通过管道传输到参数。

PowerShell 变量和数组命名约定

在 PowerShell 中，成功的脚本编写取决于您有效处理变量和数组的能力。这些实体的正确命名和使用可以提高可读性和可维护性。

变量命名指南

当您命名变量时：

• 避免保留字：不要使用 PowerShell 保留的关键字，例如 $true、$false、$null ，或循环和条件关键字，例如 $for 和 $while。
• 具有描述性：变量名称应清楚地表明其用途或内容，以提高代码的可读性。例如，使用 $userName 而不是 $un。
• 考虑范围前缀：合并范围前缀以阐明变量的范围。使用 $local:VarName 作为本地范围，使用 $script:VarName 作为脚本范围，必要时考虑使用 $global:VarName 作为全局变量。

数组的使用和命名约定

数组是处理项目集合的基础。

• 声明意图：定义一个具有特定用途的数组，确保名称反映内容，例如用于进程数组的 $processList 。
• 初始化语法：您可以使用$myArray=@()声明一个数组，并用元素填充它，$myArray='element1', 'element2'代码>.
• 接受数组作为参数：编写 cmdlet 或函数时，允许数组参数启用批量操作，如 Get-Process -Name $processNames 中所示。

明智命名和使用的 PowerShell 数组和变量可以提高脚本的效率和流畅性。

PowerShell 错误处理和调试最佳实践

有效的错误处理和调试对于在 PowerShell 中创建强大的脚本至关重要。您需要战略性地管理脚本错误，并具备在出现问题时调试脚本的技能。

使用ErrorAction参数

-ErrorAction 参数对于控制 PowerShell 如何响应非终止错误至关重要。您可以指定 Stop、Continue、SilentlyContinue 或 Inquire 等行为。以下是一个简短的概述：

• 停止：遇到错误时停止脚本的执行。
• 继续：打印错误消息并继续执行的默认行为。
• SilentlyContinue：抑制错误消息并继续执行。
• 查询：出现错误时提示您采取措施。

请记住将 -ErrorAction 与 cmdlet 一起使用来定义内联错误处理行为。

示例：

Get-Item "Path\To\Nonexistent\File" -ErrorAction Stop

调试 PowerShell 脚本

调试时，利用 PowerShell 的内置调试器。使用断点暂停脚本执行并分析当前状态。断点有以下几种类型：

• 行断点：在特定行暂停执行。
• 变量断点：访问或修改变量时触发。
• 命令断点：当特定命令即将运行时停止。

设置行断点：

Set-PSBreakpoint -Script "script.ps1" -Line 15

此外，在 cmdlet 中使用 Debug 参数可在 cmdlet 中发生错误时触发调试器。

示例：

Invoke-Command -ScriptBlock { param($path) Get-Content $path } -ArgumentList "Path\To\File" -Debug

了解和使用这些工具将允许您更有效地处理错误和调试，从而显着增强您的 PowerShell 脚本编写体验。

PowerShell 代码可读性的最佳实践

编写 PowerShell 脚本时，遵守清晰的命名约定可以大大增强代码的可读性。您应该精确命名 cmdlet、函数和变量，以反映它们的用途和功能。

Cmdlet 命名：始终使用 Pascal 大小写作为 cmdlet 名称（例如，Get-Item）。它是 PowerShell 中采用的标准，与 .NET 框架约定保持一致，使您的 cmdlet 易于识别。

变量：变量名称应该具有描述性且简洁，使其在应用程序上下文中的使用不言自明。示例：$userName 而不是 $usr。

函数名称：与 cmdlet 类似，使用 Pascal 大小写和特定名词作为函数名称（例如 ConvertTo-Json）。这不仅有助于可发现性，而且有助于理解函数执行的操作。

参数：选择能够清楚描述其含义的参数名称。例如，[string] $FilePath 比 [string] $str1 更容易理解。

大括号：将左大括号放在函数、if 或循环语句的末尾，而不是放在新行上。这是保持代码整洁和结构化的常见做法。

• 示例： function Get-LogContent { Param([string] $Path) # 这里是您的代码 } if ($errorCondition) { Write-Host "发生错误。" }

在 PowerShell 脚本中维护这些最佳实践将确保它们不仅对您和将来可能使用或修改您的代码的其他人来说是可读的，而且是可维护的。

PowerShell 安全和执行策略

使用 PowerShell 时，您的安全至关重要。 PowerShell 包含执行策略功能，这是脚本环境安全性的一个重要方面。执行策略确定 PowerShell 加载配置文件和运行脚本的条件，有助于防止执行未经授权或恶意的脚本。

以下是管理执行策略的方法：

• 查看当前策略：使用Get-ExecutionPolicy检查当前执行策略设置。
• 设置策略：使用Set-ExecutionPolicy更改策略，可用策略范围从Restricted（不运行脚本）到Unrestricted（所有脚本运行）。

PowerShell 的引擎不会强制执行执行策略，而是充当防止无意的脚本执行的指南。请记住，执行策略并不能防御恶意行为者，但它们确实为您的系统提供了一层保护。

执行政策范围：

• MachinePolicy：影响计算机上的所有用户。
• UserPolicy：适用于当前用户配置文件。
• 进程：仅影响当前的 PowerShell 会话。
• CurrentUser：仅针对当前用户。
• LocalMachine：适用于计算机上的所有用户。

按以下顺序为这些范围赋予优先级：MachinePolicy、UserPolicy、Process、CurrentUser、本地机器。

请记住始终遵循最小权限原则进行操作，设置执行策略，这些策略对您的任务具有必要的限制，但允许您的脚本高效运行。使用-Scope 参数指定在使用Set-ExecutionPolicy 时希望更改的范围。如果在 Windows 上工作，请注意组策略可能会覆盖您的执行策略设置。

示例：

# Check the current execution policy
Get-ExecutionPolicy

# Set an execution policy for the current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

通过保持警惕并了解 PowerShell 的执行策略，您可以确保脚本和配置文件的额外安全层。

PowerShell 命名约定函数

在 PowerShell 中定义函数时，请遵循包含动词-名词对的标准命名约定。这有助于保持清晰度和易用性。请按照以下步骤确保您的函数名称与 PowerShell 实践一致：

使用 PascalCase： 将函数名称中每个单词的第一个字母大写，确保单词之间没有空格。例如：获取进程。

批准的动词：从 PowerShell 批准的动词列表中选择一个动词。通过执行 Get-Verb 检索此列表。

单数名词：始终使用单数名词以避免混淆。如果您的函数处理多个项目，则名称仍应使用单数形式以与 PowerShell cmdlet 保持一致。

前缀：考虑为名词添加前缀，以防止名称冲突并提供有关该函数的附加上下文。

示例：

Function NameVerbNounDescriptionConvert-ToCsvConvertToCsvConverts objects to a comma-separated valueGet-InventoryItemGetInventoryItemRetrieves information on an inventory itemSet-UserPreferenceSetUserPreferenceModifies a user’s preferences

请记住，函数的名称应该清楚地表明该函数的作用，从而有助于自我记录并增强脚本的可读性。遵循这些准则将使您的脚本更加直观，便于您自己和其他人阅读和维护。

PowerShell 命名约定变量

在 PowerShell 中，遵守变量的命名约定可以增强脚本的可读性和可维护性。您的变量名称应清楚地表明其目的和范围。

PowerShell 局部变量命名约定

PowerShell 中的局部变量通常使用驼峰命名法命名。这意味着您以小写字母开头，并将每个后续连接单词的第一个字母大写。例如：

$localAccountDetails = "Details of a local account"
$invoiceNumber = 12345

请记住，变量名称应该具有足够的描述性，以便清楚地说明它们在代码中的用法。

PowerShell 常量变量命名约定

当您声明常量变量（不改变的值）时，请使用PascalCase。此约定以大写字母开头，并将每个新单词的第一个字母大写。最好还包含一个指示变量是常量的前缀。这是一个例子：

$ConstantTaxRate = 0.05
$MaxAllowedConnections = 100

对变量使用清晰一致的命名约定可以使您和其他人更容易访问和理解 PowerShell 脚本。

PowerShell 模块命名约定

创建 PowerShell 模块时，请遵循命名约定，以增强代码的清晰度和可预测性。使用动词-名词对命名您的模块。这种做法可以确保用户能够快速掌握模块的用途。

动词-名词对：

• 动词：使用经过批准的 PowerShell 动词来描述模块执行的操作。
• 名词：选择一个能够清楚地标识所操作的实体或概念的名词。

命名模块的最佳实践：

• 确保名称简洁且具有描述性。
• 避免使用其他人可能不清楚的缩写。
• 按照 PowerShell 指南的建议，坚持使用单数名词。

示例：对于管理系统备份的模块，合适的名称可以是 Save-SystemBackup。

目录和文件命名：

• 使用 .psm1 扩展名保存 PowerShell 脚本，并为脚本和保存脚本的目录使用相同的名称。这种一致性可以防止使用诸如 Import-Module 之类的命令导入模块时出现混淆。

PowerShell 常量命名约定

在 PowerShell 中定义常量时，采用清晰一致的命名约定至关重要。这有助于使您的代码更具可读性和可维护性。

命名常量的推荐方法是使用描述性名称，清楚地表明常量所代表的含义。通常，常量以 PascalCase（也称为 UpperCamelCase）编写，其中每个单词的第一个字母大写，并且单词之间没有下划线。

例子 ：

如果您要为最大尺寸值设置一个常量，您可以这样命名：

Set-Variable MaxSize -Option Constant -Value 1024

最佳实践：

• 描述性名称：选择反映常量用途的名称，如 MaxSize 中表示大小限制。
• PascalCase：使用 PascalCase 编写常量名称以获得更好的可见性。
• 避免缩写：使用完整的单词而不是缩写来使含义清晰。

在脚本中实现常量时，请记住常量一旦设置就无法更改。尝试修改常量将导致错误。 PowerShell 提供 Set-Variable cmdlet 来定义常量，您应将其与 -Option Constant 标志一起使用。

请记住，PowerShell 常量是不可变的。如果您需要一个可以修改但不能删除的变量，请考虑使用-Option ReadOnly。

下表总结了要点：

PropertyRecommendationExampleCasePascalCaseMaxSizeDescriptivenessClear and specific namesDefaultFilePathImmutabilitySet with -Option Constant flagSet-Variable usage

通过遵守这些约定，您可以确保 PowerShell 脚本保持结构化且易于理解。

PowerShell Cmdlet 命名约定

在 PowerShell 中制作 cmdlet 时，必须遵守使用动词-名词对的特定命名约定。这可确保您的 cmdlet 易于识别，并且它们执行的操作一目了然。

动词用法：从 PowerShell 批准的列表中选择一个动词，因为这些动词在命名约定中传达标准化操作。

• 获取：在不更改系统状态的情况下检索数据。
• 设置：修改数据或系统状态。
• 开始：启动流程或任务。

名词用法：名词应该是单数，并且描述 cmdlet 所作用的资源或对象，例如 User、Computer 或 处理。

示例：

Get-Process

Set-Date

Start-Service

最佳实践：

• 一致性：坚持既定的模式，以确保不同脚本和模块的可靠性。
• 清晰度：使用清晰且描述性的名词来准确反映您的 cmdlet 所操作的实体。

通过在 PowerShell 脚本中保持一致且清晰的命名约定，您的 cmdlet 将既专业又易于理解，从而增强脚本的可维护性和用户体验。

常见问题解答

在 PowerShell 中命名函数的最佳实践是什么？

命名函数时，请使用动词-名词格式，每个单词大写，例如 Get-Process。从标准 PowerShell 动词列表中选择动词以保持一致性。

我应该如何在 PowerShell 中构建模块的命名？

使用能够清楚地表明其功能且不带缩写的名词来命名模块，例如 UserManagement。避免使用保留字和不必要的特殊字符。

在 PowerShell 命令名称中使用动词时应该考虑什么？

使用 PowerShell 动词列表中批准的动词作为命令名称。例如，使用 Get 进行检索操作，使用 Set 进行修改操作。坚持使用这些标准化动词以确保兼容性和可预测性。

驼峰命名法如何适应 PowerShell 脚本标准？

对于脚本中的变量名称，请使用驼峰式命名法，其中第一个单词的第一个字母小写，每个后续连接单词的第一个字母大写，例如 $userName。这种做法不是函数名称的规范。

您能解释一下 PowerShell 中 PS1 文件命名约定的重要性吗？

.ps1 是 PowerShell 脚本的文件扩展名。命名这些文件时，请使用概括其功能的描述性短语，并用破折号分隔，例如 backup-database.ps1。此命名有助于快速识别脚本的用途。

PowerShell 脚本中的参数命名有哪些准则？

参数应使用反映其期望内容的描述性名词命名，例如 -FilePath。尽可能保持直观，以使其他用户易于理解脚本。避免在名称中使用保留字和不必要的缩写。

结论

我已在本 PowerShell 教程中解释了有关 PowerShell 命名约定和最佳实践的所有内容。我们涵盖：

• PowerShell 函数命名约定
• PowerShell 变量命名约定
• PowerShell 模块命名约定
• PowerShell 常量命名约定
• PowerShell Cmdlet 命名约定