PowerShell教程
PowerShell笔记 - 8.函数
本系列是一个重新学习PowerShell的笔记，内容引用自PowerShell中文博客
处理函数的参数
Powershell函数可以接受参数，并对参数进行处理。函数的参数有3个特性：
- 任意参数：内部变量\(args 接受函数调用时接受的参数，\)args是一个数组类型。
- 命名参数：函数的每一个参数可以分配一个名称，在调用时通过名称指定对应的参数。
- 预定义参数：函数在定义参数时可以指定默认值，如果调用时没有专门指定参数的值，就会保持默认值。
万能参数$args
\(args 万能参数
给一个函数定义参数最简单的是使用\)args这个内置的参数。
它可以识别任意个参数。尤其适用哪些参数可有可无的函数。
function sayHello
{
if($args.Count -eq 0)
{
"No argument!"
}
else
{
$args | foreach {"Hello,$($_)"}
}
}
Write-Host -ForegroundColor "Red" "无参数调用"
sayHello
Write-Host -ForegroundColor "Red" "一个或多个参数调用"
sayHello hua
sayHello hua hua
PS C:\PowerShell>test.ps1 无参数调用
No argument!
一个或多个参数调用
Hello,hua
Hello,hua
Hello,hua
指定参数名及默认值
function Test($Str1 = "Hua",$str2 = "Hua") {
$Str1 + $str2
}
Test
Test -Str1 "h" -str2 "ua"
PS C:\PowerShell>test.ps1 HuaHua
hua
指定参数类型
function SetDate([DateTime]$Date,[int]$Days = 0,[string]$Description = "无") {
Write-Host -ForegroundColor "Green" $Date.Day
$Date.AddDays($Days)
Write-Host -ForegroundColor "Red" $Date.Day
Write-Host -ForegroundColor "Red" $Description
}
SetDate '2020-01-01'
SetDate '2020-11-01' -Days 6 -Description "HuaHua"
#输入错误的日期
SetDate '2020-15-01' -Days 6 -Description "HuaHua"
PS C:\PowerShell>test.ps1 1
2020年1月1日 0:00:00
1
无
1
2020年11月7日 0:00:00
1
HuaHua
SetDate : Cannot process argument transformation on parameter 'Date'. Cannot convert value "2020-15-01" to type "System.DateTime". Error: "String was not recognized as a valid DateTime."
At test.ps1:11 char:9
Switch 参数
Powershell函数最简单的参数类型为布尔类型，除了使用Bool类型，也可以使用Switch关键字。
下面的函数逆转字符串，但是可以通过\(try 参数进行控制，如果没有指定\)try的值，默认值为$false
function tryReverse( [switch]$try , [string]$source )
{
[string]$target=""
if($try)
{
for( [int]$i = $source.length -1; $i -ge 0 ;$i--)
{
$target += $source[$i]
}
return $target
}
return $source
}
tryReverse -source www.mossfly.com
tryReverse -try $true -source www.mossfly.com
PS C:\PowerShell> test.ps1 www.mossfly.com
moc.ylfssom.www
指定函数的返回值
一个或多个返回值
Powershell不像它编程语言，它的函数可以有多个返回值。如果你直接调用函数，返回值会在控制台输出。当然你也可以将结果存储在一个变量中进一步处理。
下面的例子演示返回一个值：
function GetDate() {
return Get-Date
}
GetDate
$d = GetDate
$d.GetType().FullName
PS C:\PowerShell> test.ps1
2021年9月14日 15:27:28
System.DateTime
下面的例子演示返回多个值
function GetDate() {
$v = Get-Date
$v.Year
$v.Month
$v.Day
}
GetDate
$d = GetDate
$d.GetType().FullName
$d.Count
$d[0]
PS C:\PowerShell> test.ps1 2021
9
14
System.Object[]
3
2021
总结一下，如果一个函数返回一个值，像其它编程语言一样，这个值包括她的类型信息会直接返回。但是如果遇到多个返回值，Powershell会将所有的返回值自动构造成一个Object数组。可以通过索引访问数组。
Return语句
Powershell会将函数中所有的输出作为返回值，但是也可以通过return语句指定具体的我返回值。
Return 语句会将指定的值返回，同时也会中断函数的执行，return后面的语句会被忽略。
function GetDate() {
$v = Get-Date
$v.Year
return $v.Month
$v.Day
}
GetDate
$d = GetDate
$d.GetType().FullName
$d.Count
#return 语句之后的Day没有返回被截断
PS C:\PowerShell> test.ps1 2021
9
System.Object[]
访问返回值
一个函数返回了一个值还是多个值，是可以验证的。下面的例子会产生随机数，如果没有指定个数，默认会返回一个随机数，否则会返回指定个数的随机数。
Function lottery([int]$number=1)
{
$rand = New-Object system.random
For ($i=1; $i -le $number; $i++) {
$rand.next(1,50)
}
}
# 参数为空时，返回值不是数组:
$result = lottery
$result -is [array]
# False
# 如果指定多个随机数是，返回值是数组类型:
$result = lottery 10
$result -is [array]
PS C:\PowerShell> test.ps1 False
True
从函数的返回值中消除输出
函数默认会将函数中的所有输出作为函数的返回值返回，这样很方便。但有时可能会将不必要的输出误以为返回值。写脚本程序时，可能需要自定义一些函数，这个函数可能只需要一个返回值，但是为了提高函数的可读性，可能会在函数增加一些注释输出行。
Function Test()
{
"Try to calculate."
"3.1415926"
"Done."
}
#保存在变量中输出,
$value=Test
$value
# Try to calculate.
# 3.1415926
# Done.
#如果要过滤注释，只输出，不作为返回值，
#可以使用Write-Host命令
Function Test()
{
Write-Host "Try to calculate."
"3.1415926"
Write-Host "Done."
}
# 在变量值中保存返回值，在控制台输出注释行
$value=Test
# Try to calculate.
# Done.
# 测试返回值
$value
# 3.1415926
使用调试信息报告
可能输出这些函数中临时提示信息，给函数的返回值造成干扰。要解决这个问题，除了上述的Write-Host，也可以使用Write-Debug命令。
Function Test()
{
Write-Debug "Try to calculate."
"3.1415926"
Write-Debug "Done."
}
# Debug调试信息只会在调试模式下被输出
$value=Test
# 3.1415926
#如果你想通过显示调试信息调试函数，可以开启调试模式
$DebugPreference="Continue"
$value=Test
# 调试: Try to calculate.
# 调试: Done.
# 测试返回值
$value
# 3.1415926
#如果关闭调试模式，这些调试信息自然不会输出
$DebugPreference="SilentlyContinue"
$value=Test
使用Write-Debug有两个优势，首先调试信息会自动高亮显示，便于分析。其次，这些调试信息只会在调试模式开启时输出，控制起来更加方便。当然最重要的是这些临时信息无论什么时候也不会混淆在返回值。
抑制错误信息
函数中的错误信息，也有可能作为返回值的一部分，因为默认这些错误信息会直接输出。
Function ErrorTest()
{
#该进程不存在
Stop-Process -Name "www.mossfly.com"
}
ErrorTest
Stop-Process : 找不到名为“www.mossfly.com”的进程。请验证该进程名称，然后再次调用 cmdlet。
所在位置 C:UsersbaozhenDesktoptest.ps1:6 字符: 17
+ Stop-Process <<<< -Name "www.mossfly.com"
+ CategoryInfo : ObjectNotFound: (www.mossfly.com:String) [Stop-P
rocess], ProcessCommandException
+ FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.
Commands.StopProcessCommand
很明显，类似这样的错误提示信息，对调试程序很重要，但如果你觉得它不重要，特意要隐藏，可以使用$ErrorActionPreference进行设置。
Function ErrorTest()
{
#从这里开始隐藏所有的错误信息
$ErrorActionPreference="SilentlyContinue"
Stop-Process -Name "www.mossfly.com"
#该进程不存在
}
#错误信息不会输出
ErrorTest
但是上面的做法并不明智，因为这样可能错过其它错误提示。所以最好的方式是处理完后，对$ErrorActionPreference进行复位。
Function ErrorTest()
{
#从这里开始隐藏所有的错误信息
$ErrorActionPreference="SilentlyContinue"
Stop-Process -Name "www.mossfly.com"
#该进程不存在
#恢复$ErrorActionPreference,错误开始输出
$ErrorActionPreference="Continue"
2/0
}
ErrorTest
试图除以零。
所在位置 行:9 字符: 7
+ 2/ <<<< 0
+ CategoryInfo : NotSpecified: (:) [], ParentContainsErrorRecordException
+ FullyQualifiedErrorId : RuntimeException
查看支持的函数
Powershell已经提供了许多用户能够使用的预定义函数，这些函数可以通过Function:PSDrive虚拟驱动器查看。
PS C:\PowerShell> Get-ChildItem function: | Format-Table Name,Definition Name Definition ---- ---------- A: Set-Location $MyInvocation.MyCommand.Name B: Set-Location $MyInvocation.MyCommand.Name C: Set-Location $MyInvocation.MyCommand.Name cd.. Set-Location .. cd\ Set-Location \ Clear-Host ... ConvertFrom-SddlString ... D: Set-Location $MyInvocation.MyCommand.Name E: Set-Location $MyInvocation.MyCommand.Name F: Set-Location $MyInvocation.MyCommand.Name Format-Hex ... G: Set-Location $MyInvocation.MyCommand.Name Get-FileHash ... Get-Verb ... H: Set-Location $MyInvocation.MyCommand.Name help ... I: Set-Location $MyInvocation.MyCommand.Name Import-PowerShellDataFile ... ImportSystemModules J: Set-Location $MyInvocation.MyCommand.Name K: Set-Location $MyInvocation.MyCommand.Name L: Set-Location $MyInvocation.MyCommand.Name M: Set-Location $MyInvocation.MyCommand.Name mkdir ... more ... N: Set-Location $MyInvocation.MyCommand.Name New-Guid ... New-TemporaryFile ... O: Set-Location $MyInvocation.MyCommand.Name oss ... P: Set-Location $MyInvocation.MyCommand.Name Pause $null = Read-Host 'Press Enter to continue...' prompt ... PSConsoleHostReadLine ... Q: Set-Location $MyInvocation.MyCommand.Name R: Set-Location $MyInvocation.MyCommand.Name S: Set-Location $MyInvocation.MyCommand.Name T: Set-Location $MyInvocation.MyCommand.Name TabExpansion2 ... U: Set-Location $MyInvocation.MyCommand.Name V: Set-Location $MyInvocation.MyCommand.Name W: Set-Location $MyInvocation.MyCommand.Name X: Set-Location $MyInvocation.MyCommand.Name Y: Set-Location $MyInvocation.MyCommand.Name Z: Set-Location $MyInvocation.MyCommand.Name
从这些结果不但能够看出函数的名称，还能通过Definition列查看函数的内容。如果你想深入查看函数的内部定义可以直接访问Function:
PS C:\PowerShell> $function:prompt
"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) ";
# .Link
# https://go.microsoft.com/fwlink/?LinkID=225750
# .ExternalHelp System.Management.Automation.dll-help.xml
Powershell中的这些预定义的函数可以做很多重要的工作。
Clear-Host 清除屏幕的缓存
help,man 查看命令的帮助文档
mkdir,md 通过new-Item创建子目录
more 分屏输出管道结果
prompt 返回提示文本
TabExpansion Tab键的自动完成提示
X: 调用Set-Location定位到指定的驱动器根目录
如果你想查看当前Powershell环境中定义了多少个函数可以通过：
PS C:\PowerShell> (Dir function:).Count 45
自定义Prompt
每次成功执行完一条命令，Powershell就会执行Prompt函数，提示用户进行下一步输入。
默认设置中，prompt显示“PS” 和当前的工作目录。
再接着是”>”或”>>”,具体情况要看当前Powershell控制台的的层数。
当然你可以自定义prompt的，那就得覆盖prompt函数：
PS C:\PowerShell> pwd
Path
----
C:\PowerShell
PS C:\PowerShell> Function prompt{"Hua Hua"} Hua Hua Hua Huapwd
Path
----
C:\PowerShell
Hua Hua
这样的覆盖安全吗，显然安全，对预定义函数的重写，只会在当前控制台会话中有效，当你重新启动控制台时，自然会恢复如初。
在控制台的任何位置输出文本（自定义光标的位置）
因为控制台的内容存放在控制台屏幕的缓存中，因此你可以逐个访问内容的每一行或每一个字符。
你甚至可以在控制台的屏幕的任何位置输出你想要输出的信息，接下来的函数会演示这个功能。
要完成这个功能，需要使用$Host.UI.Rawui ,光标的位置通过屏幕的横坐标（X）和纵坐标（Y）确定，下面的函数会首先记住当前光标的位置，然后在横坐标上增加60个占位符，然后重置光标的位置至当前位置，最后通过prompt函数回复光标的原始位置。
Hua H> function prompt
>> {
>> $curPos = $host.ui.rawui.CursorPosition
>> $newPos = $curPos
>> $newPos.X+=60
>> $host.ui.rawui.CursorPosition = $newPos
>> Write-Host ("{0:D} {0:T}" -f (Get-Date)) -foregroundcolor Yellow
>> $host.ui.rawui.CursorPosition = $curPos
>> Write-Host ("PS " + $(get-location) +">") -nonewline -foregroundcolor Green
>> " "
>> } PS C:\PowerShell> 2021年9月14日 16:57:04
使用窗口标题栏
在Windows控制台的标题栏有一部分空间，可以放置一些有用的信息，比如当前哪个用户登录在控制台，可以通过设置$host.UI.RawUI.WindowTitle来自定义控制台标题栏的文本。
下面的例子就会演示设置标题栏文本，通过.NET方法获取当前用户信息，由于该方法会有几秒钟执行时间，为了效率考虑首先将用户信息保存在全局变量中，然后在Prompt函数中调用。
$global:CurrentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent()
function prompt
{
$host.ui.rawui.WindowTitle = "Line: " + $host.UI.RawUI.CursorPosition.Y + " " + $CurrentUser.Name + " " + $Host.Name + " " + $Host.Version
Write-Host ("PS " + $(get-location) +">") -nonewline -foregroundcolor Green
return " "
}
执行以后在标题栏会显示：Line: 72 ComputerNameuser ConsoleHost 2.0
如果你使用管理员权限运行控制台时，Prompt函数还可以给出警告。使用WindowsPrincipal 辨别当前用户是否使用了管理员权限，你不需要了解下面的.NET代码，它会在全局变量中将布尔值赋值给$Admin。
$CurrentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent()
$principal = new-object System.Security.principal.windowsprincipal($CurrentUser)
$global:Admin = $principal.IsInRole( [System.Security.Principal.WindowsBuiltInRole]::Administrator)
Function prompt
{
# 输出标准的提示信息:
Write-Host ("PS " + $(get-location)) -nonewline
# The rest depends on whether you have admin rights or not:
If ($admin)
{
$oldtitle = $host.ui.rawui.WindowTitle
# 将"Administrator: " 显示在标题栏
If (!$oldtitle.StartsWith("Administrator: "))
{
$host.ui.rawui.WindowTitle ="Administrator: " + $oldtitle
}
# Prompt结尾显示红色的尖括号
Write-Host ">" -nonewline -foregroundcolor Red
}
Else
{
Write-Host ">" -nonewline
}
return " "
}
没有管理员权限时，标题栏文本：Windows Powershell
有管理员权限时，标题栏文本:Administrator ：管理员 : Windows Powershell
Clear-Host:删除屏幕缓存
很可能，你已经注意到了，cls可以删除屏幕的缓存。
事实上，cls只是Clear-Host函数的别名，但是却看不到这个函数的内容。
PS C:\PowerShell> $function:Clear-Host
At line:1 char:16
+ $function:Clear-Host
+ ~~~~~
Unexpected token '-Host' in expression or statement.
+ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException
+ FullyQualifiedErrorId : UnexpectedToken
在Powershell中短斜杠是个特殊字符，如果一个函数名中包含了特殊字符就应当把它放在花括号中。
PS C:\PowerShell> ${function:Clear-Host}
$RawUI = $Host.UI.RawUI
$RawUI.CursorPosition = @{X=0;Y=0}
$RawUI.SetBufferContents(
@{Top = -1; Bottom = -1; Right = -1; Left = -1},
@{Character = ' '; ForegroundColor = $rawui.ForegroundColor; BackgroundColor = $rawui.BackgroundColor})
# .Link
# https://go.microsoft.com/fwlink/?LinkID=225747
# .ExternalHelp System.Management.Automation.dll-help.xml
盘符名预定义函数C:,D:,E:
这些盘符名称可以作为单独的一个函数，是怎么做到的呢？
PS C:\PowerShell> $function:C: Set-Location $MyInvocation.MyCommand.Name
函数过滤器、管道
一个函数能够访问和进一步处理另外一条命令的结果吗？答案是肯定的，这被称为管道。管道有两种模式，一种是顺序处理模式，一种是流处理模式。
低效率的顺序模式:$input
在最简单的情况下，你的函数不是真正支持管道。只能对前一个命令执行后的结果处理。前一个命令执行的结果通过被自动保存在$input变量中，$input是一个数组，它可以包含许多元素，一个元素，甚至一个元素都没有，这取决于具体的环境。
下面的例子，是一个函数，仅仅输出$input的内容。
PS C:\PowerShell> function OutPut {
>> $input
>> } PS C:\PowerShell> 1,2,3 | OutPut 1
2
3
PS C:\PowerShell> "222",1 | OutPut 222
1
PS C:\PowerShell> dir | OutPut
Directory: C:\PowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2021/9/14 13:51 58 test.txt
到目前为止，这个函数只是仅仅输出了管道的结果，并没有其它比较强大的功能。
在接下来的例子中，函数将会对管道的结果做进一步处理。函数名MarkEXE,将会检查Dir的结果，并高亮标记后缀名为EXE的文件名为红色。
Function MarkEXE {
# 保存控制台当前的前景色
$oldcolor = $host.ui.rawui.ForegroundColor
# 通过循环逐条检查管道的结果
Foreach ($element in $input) {
# 如果后缀名为.exe,设置为前景色为红色
If ($element.name.toLower().endsWith(".exe")) {
$host.ui.Rawui.ForegroundColor = "red"
}
Else {
# 否则恢复默认的前景色
$host.ui.Rawui.ForegroundColor = $oldcolor
}
# 输出数组元素
$element
}
# 最后，重置控制台的前景色:
$host.ui.Rawui.ForegroundColor = $oldcolor
}
Dir | MarkEXE
PS C:\PowerShell> New-Item test.exe
Directory: C:\PowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2021/9/15 10:46 0 test.exe
PS C:\PowerShell> ls
Directory: C:\PowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2021/9/15 10:46 0 test.exe
-a---- 2021/9/14 13:51 58 test.txt
PS C:\PowerShell> test.ps1
Directory: C:\PowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2021/9/15 10:46 0 test.exe
-a---- 2021/9/14 13:51 58 test.txt
过滤器：高效率 流模式
管道的低效率顺序模式在处理大容量数据时很容易出现问题，其结果是巨大的内存占用和进程等待。
如果你的函数支持高效率的流模式，在处理管道结果时仅占用很小的内存。
事实上，针对之前MarkEXE函数，你只需要替换”function” 关键字 为 “filter”它就会开始流模式处理，这样你再也不用过分的担心忍受程序的无休止的响应和崩溃的危险。
你也可以递归处理全盘目录，甚至处理极其庞大的数据。例如：
PS C:\PowerShell> Dir C:\PowerShell\ -recurse | MarkEXE
当MarkEXE每次被调用时，它只会对当前目录下的每个单独的元素进行处理。
对于过滤器filters来说，$input 一直都是一个独立的元素。
这也就是为什么在过滤器中$input一点用也没有的道理。
此时，最好使用$_ 变量，因为它代表了当前处理的数据。
这样还可以简化MarkExe，因为过滤器自身已经扮演了循环的角色了，你没有必要再写专门的循环处理了。
Filter MarkEXE
{
# 记录当前控制台的背景色
$oldcolor = $host.ui.rawui.ForegroundColor
# 当前的管道元素保存在 $_ 变量中
# 如果后缀名为 ".exe",
# 改变背景色为红色:
If ($_.name.toLower().endsWith(".exe"))
{
$host.ui.Rawui.ForegroundColor = "red"
}
Else
{
# 否则使用之前的背景色
$host.ui.Rawui.ForegroundColor = $oldcolor
}
# 输出当前元素
$_
# 最后恢复控制台颜色:
$host.ui.Rawui.ForegroundColor = $oldcolor
}
Dir | MarkEXE
PS C:\PowerShell> test.ps1
Directory: C:\PowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2021/9/15 10:46 0 test.exe
-a---- 2021/9/14 13:51 58 test.txt
开发真正的管道函数
过滤器在函数中属于高级应用，因为它可以立即处理管道结果的每一个元素。但是过滤器必须每次重复执行预定义命令的结果。
对于MarkEXE 函数，每次执行的过程中要记录和更新控制台的背景颜色，也要花费资源和时间。
事实上,过滤器只是特殊的函数。如果一个函数内部使用了管道，你就可以定义三个基础的任务区了：第一步，完成函数的初始化，完成函数执行的预备步骤;第二步处理递归调用所得的结果;最后进行收尾工作。
这三个任务区分别可以使用begin,process,end 语句块。
function MarkEXE {
begin {
# 记录当前控制台的背景色
$oldcolor = $host.ui.rawui.ForegroundColor
}
process {
# 当前的管道元素保存在 $_ 变量中
# 如果后缀名为 ".exe",
# 改变背景色为红色:
If ($_.name.toLower().endsWith(".exe")) {
$host.ui.Rawui.ForegroundColor = "red"
}
Else {
# 否则使用之前的背景色
$host.ui.Rawui.ForegroundColor = $oldcolor
}
# 输出当前元素
$_
}
end {
# 最后恢复控制台颜色:
$host.ui.Rawui.ForegroundColor = $oldcolor
}
}
Dir | MarkEXE
PS C:\PowerShell> test.ps1
Directory: C:\PowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2021/9/15 10:46 0 test.exe
-a---- 2021/9/14 13:51 58 test.txt
-
SharePoint 2019 用 PowerShell将启用发布功能站点网站集另存为模板09-14
-
PowerShell教程 - 程序性能和BUG分析工具08-30
-
PowerShell教程 - 模块管理（Modules Management）08-30
-
PowerShell教程 - Web requests（Web请求）08-29
-
PowerShell教程 - 日期时间管理（Date & Time Management）08-26
-
PowerShell教程 - 磁盘与硬件管理（Disk & Hardware Management）08-25
-
PowerShell教程 - 系统事件管理（System Event Management）08-25
-
PowerShell教程 - 文件系统管理（File System Management）08-25
-
PowerShell教程 - 网络管理（Network Management）08-24
-
PowerShell08-24
-
PowerShell教程 - 用户和组管理（User && Group）08-23
-
PowerShell教程 - 数值管理（Working With Number）08-23
-
ssh之powershell08-23
-
PowerShell教程 - PowerShell安装与启动（PowerShell Install）08-21
-
PowerShell教程 - PowerShell编辑器（PowerShell editors）08-21
