另一个 PowerShell ToDo 工具

最近，一位读者 Matt Penny 在我的一篇文章的评论中分享了一个技巧。他有一个简短的 PowerShell 函数，用于将 ToDo 命令插入到他的 Pester 测试脚本中。尽管您可以轻松地将它用于其他 PowerShell 工作。当然，我总是在寻找灵感，所以我接受了马特的想法，并对其进行了过度的研究。

Matt 最初的功能非常简单，这总是一件好事。

function todo {
param ([string]$TodoText)
write-host -foregroundcolor DarkYellow ” [o] Todo: $TodoText”
}

然后，在脚本或函数中，他所要做的就是添加调用该函数的行。假设此 ToDo 函数已加载，可能作为配置文件脚本的一部分。这是一个插入了几个 ToDo 命令的演示函数。这些表示需要编码的其他部分。

Function Demo {
[cmdletbinding()]
Param(

[Parameter(ValueFromPipeline)]
[int]$X = 1
)

Begin {
    Write-Verbose "[BEGIN  ] Starting: $($MyInvocation.Mycommand)"  
    ToDo "verbose PSBoundparameter data goes here"
} #begin

Process {
    Write-Verbose "[PROCESS] Processing $X"
    ToDo "calculate square root of X" 
    ToDo "calculate X^X" 
   
    #write a custom object to the pipeline
    [pscustomobject]@{
        Value = $X
        Square = $X*$X
        SquareRoot = 0
        Power = 0
    }

    ToDo "add option to save output" 
} #process

End {
    ToDo "Display runtime"
    ToDo "Clean up environment" 

    Write-Verbose "[END    ] Ending: $($MyInvocation.Mycommand)"
} #end
}

当我运行该命令时，我会看到 ToDo 语句。

我喜欢。但我很好奇我还能用它做什么。当然，即使您不需要我版本的功能，我也希望您能学到新的东西。

我决定给每个待办事项编号。我认为对待办事项条目进行颜色编码也可能会很好，以帮助我确定首先要做什么的优先顺序。最后，当前的实现在管道表达式中运行某些内容时效果不佳。我的演示函数采用管道输入，因此如果我用 3 个数字对其进行测试，我将获得 3 个待办事项的副本，而我真正需要的只是一个。

保持计数相对简单。我可以初始化一个变量，然后使用 ++ 运算符来递增它。但挑战在于范围。当我调用我的 ToDo 函数版本时，我得到一个新的作用域，该作用域在函数退出时消失。而且我不想让我的主要剧本变得更难写。因此，我将在全局范围内创建一个变量并递增它。请注意，最佳实践是避免引用超出范围的项目，但总有例外。这是其中之一。通过使用 $global: 前缀，我告诉 PowerShell 我知道我在做什么。

另一个挑战是跟踪已显示的消息，因此我在管道操作期间减少了重复消息。我再次使用全局变量来跟踪消息历史记录。如果消息已经显示，则不要执行任何操作，否则显示它并将其添加到历史变量中。

if (-Not ($global:ToDoHistory -contains $ToDo)) {
        $global:ToDoCounter++
        #format the counter with 2 leading zeros.
        $msg = "[$($global:ToDoCounter.ToString("00#"))] TO-DO: $ToDo"

        Write-Host $msg -ForegroundColor $ForegroundColor
        $global:TodoHistory+=$ToDo
    }

这里演示的是我的演示函数的修改版本，它调用我的 ToDo 函数版本。我的版本采用消息参数和消息颜色的可选参数。默认为青色。

Function Demo {
[cmdletbinding()]
Param(

[Parameter(ValueFromPipeline)]
[int]$X = 1
)

Begin {
    Write-Verbose "[BEGIN  ] Starting: $($MyInvocation.Mycommand)"  
    ToDo "verbose PSBoundparameter data goes here" yellow
} #begin

Process {
    Write-Verbose "[PROCESS] Processing $X"
    ToDo "calculate square root of X" red
    ToDo "calculate X^X" 
   
    #write a custom object to the pipeline
    [pscustomobject]@{
        Value = $X
        Square = $X*$X
        SquareRoot = 0
        Power = 0
    }

    ToDo "add option to save output" green
} #process

End {
    ToDo "Display runtime"
    ToDo "Clean up environment" red

    <#
    force ToDo cleanup
    This is optional. If you don't, you'll manually need to clear
    $ToDoHistory and $ToDoCounter from the global scope before 
    running another script that uses ToDo.
    #>
    Remove-ToDoVariable

    Write-Verbose "[END    ] Ending: $($MyInvocation.Mycommand)"
} #end
}

当我完成待办事项时，我可以从函数中删除该行。我唯一添加的额外功能是在 End 块中添加一个附加函数，Remove-ToDoVariable，用于清理全局变量。否则，下次运行该函数时，全局变量将被重新使用，这没有什么帮助。您不必执行此步骤，您始终可以在再次测试之前手动重置变量。但现在我（也许）收到了一条更有用的待办事项消息。

流水线测试不会重复任何事情。

ToDo.ps1:

Function Write-ToDo {
[cmdletbinding()]

Param(
[Parameter(
Position=0,
Mandatory,
HelpMessage = "Enter a ToDo item")]
[string]$ToDo,
[Parameter(
Position = 1
)]
[ValidateNotNullorEmpty()]
#the default ToDo color
[consolecolor]$ForegroundColor = "Cyan"
)

Begin {
    If (-Not $ToDoHistory) {
        $global:ToDoHistory = @()
    }
 } #begin

Process {
    #check ToDoHistory to make sure we haven't already displayed the item
    #useful if the new function accepts pipeline input or when looping
    if (-Not ($global:ToDoHistory -contains $ToDo)) {
        $global:ToDoCounter++
        #format the counter with 2 leading zeros
        $msg = "[$($global:ToDoCounter.ToString("00#"))] TO-DO: $ToDo"

        Write-Host $msg -ForegroundColor $ForegroundColor
        $global:TodoHistory+=$ToDo
    }
    
 } #process

End {
    #not used
 } #end

} #Write-ToDo

Set-Alias -Name ToDo -Value Write-ToDo

Function Remove-ToDoVariable {
[cmdletbinding(SupportsShouldProcess)]
Param()

"ToDoCounter","ToDoHistory" | foreach {
  #remove these variables from the global scope and ignore any errors
  #for variables that don't exist
  Remove-Variable -Name $_ -Scope global -ErrorAction SilentlyContinue
}

} #Remove-ToDoVariable