如何在 PowerShell 中添加评论

用任何语言编写代码时，添加注释都很重要。这也适用于您的 PowerShell 脚本。尽管有时可能很短，但在 PowerShell 中添加注释仍然很重要。

注释不仅可以帮助别人理解您的代码，而且在您阅读代码时也是对自己的一个很好的提醒。它们可用于解释函数，或者在测试脚本时注释掉脚本的某些部分。

在本文中，我们将了解如何在 PowerShell 中添加注释以及如何使用注释块。

在 PowerShell 中发表评论

就像大多数编程语言一样，我们可以在 PowerShell 中使用 # 添加注释。在向脚本添加注释时，请务必尝试解释您的想法或推理。或者简要描述函数的作用。

原因是编写良好的 PowerShell 脚本通常非常明显。如果您查看下面的示例，您会发现注释并没有真正为代码添加任何价值。

# Get Admins
$admins = Get-Admins

在这种情况下，更好的选择可能是解释我们得到的结果：

# Get all users that have an admin role
$admins = Get-Admins

注释还可以用于注释掉代码或函数的一部分。当您测试脚本并且想要跳过其中的一部分时，这通常很方便。只需在要跳过的函数前面添加 #，PowerShell 就会忽略该函数。

例如，在下面的小脚本中，我们创建 10 个测试文件。要测试脚本而不实际创建文件，您可以注释掉 New-Item cmdlet。这样只有 Write-Host 函数被执行。

# Path for the test files
$path = "C:\temp"

# Create 10 test files in the given path
1..10 | % {
    $newFile = "$path\test_file_$_.txt";
    # New-Item $newFile  # This cmdlet is skipped due to # infront of it
    Write-Host $newFile
}

PowerShell 块注释

一般来说，建议您的评论简短扼要。但在某些情况下，您需要多行来解释函数的作用。对于最多两行的注释，可以在每行前面使用 #。

但当您需要更多时，在 PowerShell 中使用块注释会更容易、更好。块注释的优点是您可以轻松编辑注释，将其折叠在 IDE（例如 Visual Studio）中，并且更易于阅读。

正如您在下面的示例中看到的，当您只需要两行注释时，# 可以正常工作：

# Storing the path of the log file for easy modification
# Changing this variable updates the log file location throughout the script.
$LogFile = "C:\Logs\output.log"

但当注释较长时，注释块会更有用且更易于阅读。要创建块注释，请以 结束注释块：

<#
    Get all the permissions of each mailbox
    
    Permission are spread into 4 parts.
    - Read and Manage permission
    - Send as Permission
    - Send on behalf of permission
    - Folder permissions (inbox and calendar set by the user self)
#>

基于注释的函数帮助

您的脚本，实际上还有您的函数，应该始终以注释块开头。该注释块以特定格式编写，这使得它更易于阅读，并且还允许我们使用 help cmdlet 显示信息。

这种格式称为基于注释的帮助。它写在 PowerShell 注释块内，并使用帮助关键字来格式化注释块。基于注释的帮助分为几个部分。您不需要全部包含它们，但建议提供概要和至少一个如何使用该函数的示例。

function Get-UserInfo {
    <#
    .SYNOPSIS
        Get the Microsoft 365 user information
    .EXAMPLE
        Get-UserInfo -Username '[email protected]'

        This will get the M365 information of the given user
    #>
    [CmdletBinding()]
    param(
        # Microsoft 365 username
        [Parameter(Mandatory = $true)]
        [string]$Username
    )
    # Rest of the function code
}

最佳实践是将基于注释的帮助部分放置在函数内部而不是之上。这样，当您对函数进行更改时，就很难忘记更新注释。

如果您的函数使用参数，请确保为每个参数添加注释，解释您期望的信息。

在脚本的开头，您通常会添加更多信息。比如对脚本用途的详细描述，一些关于如何使用脚本的示例，以及注释部分，您可以在其中添加最后更改日期、作者等信息。

<#
.SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
.DESCRIPTION
    A longer description of the function, its purpose, common use cases, etc.
.NOTES
    Information or caveats about the function e.g. 'This function is not supported in Linux'
.LINK
    Specify a URI to a help page, this will show when Get-Help -Online is used.
.EXAMPLE
    Test-MyTestFunction -Verbose
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
#>

使用基于注释的帮助

将基于注释的帮助块添加到脚本或函数后，您可以使用 PowerShell 中的 get-help cmdlet 查看此信息。如果运行不带任何参数的命令，则它将仅显示函数的概要、描述和语法。

但我们可以使用参数来显示基于注释的帮助部分的附加信息：

• -Detailed 提供有关命令的更多详细信息，包括示例。
• -Examples 显示命令的使用示例。
• -Full 显示完整的帮助内容，包括详细说明和示例。
• -Online 在默认 Web 浏览器中打开该命令的在线文档。

例如，如果我们想通过示例查看我的 MFA 状态脚本的详细信息，那么我们可以这样做：

Get-Help .\Get-MgMFAStatus.ps1 -Detailed

总结

当您编写脚本时，在 PowerShell 中添加注释非常重要。当你编写函数时，它们可能看起来很合乎逻辑，但如果你需要在 6 个月后更新脚本，注释确实可以帮助你理解自己的代码和想法 ?

我希望本文能让您更好地了解如何在 PowerShell 中使用注释。如果您有任何疑问，请在下面发表评论。