Public/Set-PowerSetting.ps1
|
<#
.SYNOPSIS This function sets a power settings for local or remote computer(s) to a new value. .DESCRIPTION This function sets a power settings for local or remote computer(s) to a new value, it always activates the power plan to ensure this setting takes effect. All settings values are Index Values that map to human readable values or an integer value that indicate seconds, charge, etc. In order to best know what values are availabe for a specific setting I strongly recommend using CTRL+Space to see all possible Index values and their human readable names. .PARAMETER ComputerName This parameter specifies the ComputerName for the computer you want to set power setting for. Default value is $ENV:COMPUTERNAME. .PARAMETER PlanName This parameter specifies the plan name of the plan you want to set a power settings for, use tab completion or pipe a power setting object for ease of use. .PARAMETER SettingName This parameter specifies the name of the power setting you want to set, tab completion is available. .PARAMETER SettingType This parameter specifies the power type for the setting, options include DC (on battery) or AC (wall power) power. .PARAMETER IndexValue This is the value you want to set the power setting to. I highly recommend using CTRL+Space to see all availabe options and to see friendly names for index values. .EXAMPLE PS C:\> Get-PowerSetting -ComputerName TEST-LAPTOP02-L -ActivePlanOnly -SettingType AC -SettingName "Console lock display off timeout" Plan Name: Balanced ComputerName Active Type SettingName SettingValue Range ------------ ------ ---- ----------- ------------ ----- TEST-LAPTOP02-L True AC Console lock display off timeout 60 Seconds {0, 4294967295} PS C:\> Get-PowerSetting -ComputerName TEST-LAPTOP02-L -ActivePlanOnly -SettingType AC -SettingName "Console lock display off timeout" | Set-PowerSetting -IndexValue 1800 PS C:\> Get-PowerSetting -ComputerName TEST-LAPTOP02-L -ActivePlanOnly -SettingType AC -SettingName "Console lock display off timeout" Plan Name: Balanced ComputerName Active Type SettingName SettingValue Range ------------ ------ ---- ----------- ------------ ----- TEST-LAPTOP02-L True AC Console lock display off timeout 1800 Seconds {0, 4294967295} The first command gets the "Console lock display off timeout" power setting for TEST-LAPTOP02-L and outputs it to the console. We se it is set to 60 seconds. The second command runs the same command but then pipes it to Set-PowerSetting and provides the value 1800 to the parameter IndexValue. This will set that setting to 1800 seconds (30 minutes). The last command run the first command again to confirm that the setting was udpated to the new vale, and here we can see that it was. This particular setting's default value of 60 seconds is pretty low. It will put the computer asleep after 60 seconds a user locking their computer. If the user is just getting up to for a minutes it can frustrating to come back and have to wake the computer. .EXAMPLE PS C:\> Set-PowerSetting -SettingName "Lid close action" -SettingType AC -IndexValue 0 -PlanName "HP Optimized (recommended)" PS C:\> Get-PowerSetting -SettingName "Lid close action" -SettingType AC -PlanName "HP Optimized (recommended)" Plan Name: HP Optimized (recommended) ComputerName Active Type SettingName SettingValue Range ------------ ------ ---- ----------- ------------ ----- Test-COMPUTER-L True AC Lid close action Do nothing {Do nothing, Sleep, Hibernate, Shut down} The first command set the "Lid close action" setting to the IndexValue of 0 (do nothing). We used ctrl+space tab complettion to see all the options for index values. The second command confirms the setting was changed to what we want and we can see that it was. .INPUTS Inputs (if any) .OUTPUTS None .NOTES Requires Admin #> function Set-PowerSetting { [CmdletBinding()] param( [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [Alias("PlanId")] [ArgumentCompleter({ param ($commandName,$parameterName,$wordToComplete,$commandAst,$fakeBoundParameters) $param = @{ Query = "select ElementName,IsActive from Win32_PowerPlan WHERE ElementName LIKE '%$wordToComplete%'" ComputerName = $fakeBoundParameters.ComputerName Namespace = "root\cimv2\power" } Get-CimInstance @param | Foreach-Object { $Active = "InActive" if ($_.IsActive){ $Active = "Active" } [System.Management.Automation.CompletionResult]::new("`"$($_.ElementName)`"","$($_.ElementName) - $Active","ParameterValue","$($_.ElementName)") } })] [string]$PlanName, [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [Alias("SettingId")] [ArgumentCompleter({ param ($commandName,$parameterName,$wordToComplete,$commandAst,$fakeBoundParameters) $param = @{ Query = "select ElementName from Win32_PowerSetting WHERE ElementName LIKE '%$wordToComplete%'" ComputerName = $fakeBoundParameters.ComputerName Namespace = "root\cimv2\power" } Get-CimInstance @param | Foreach-Object { [System.Management.Automation.CompletionResult]::new("`"$($_.ElementName)`"","$($_.ElementName)","ParameterValue","$($_.ElementName)") } })] [string]$SettingName, [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [ValidateSet("AC","DC")] [string]$SettingType, [Parameter()] [ArgumentCompleter({ param ($commandName,$parameterName,$wordToComplete,$commandAst,$fakeBoundParameters) $param = @{ PlanName = $fakeBoundParameters.PlanName SettingName = $fakeBoundParameters.SettingName SettingType = $fakeBoundParameters.SettingType } Get-PowerSetting @param | Foreach-Object { if ($_.SettingValueType -eq "Range"){ $ToolTip = "The value can be any number between $($_.SettingValueRange -join " - ")" $_.SettingValueRange | foreach { [System.Management.Automation.CompletionResult]::new("`"$($_)`"","$_","ParameterValue",$ToolTip) } } else{ $_.SettingValueRangeObjects | foreach { $ToolTip = "Name: $($_.ElementName)`nIndexValue: $($_.SettingIndex)" [System.Management.Automation.CompletionResult]::new("$($_.SettingIndex)","$($_.ElementName)","ParameterValue",$ToolTip) } } } })] $IndexValue, [Parameter(ValueFromPipelineByPropertyName)] [string]$ComputerName = $env:COMPUTERNAME ) Process { try{ $Session = New-CimConnection -ComputerName $ComputerName $CimParameters = @{ CimSession = $Session Namespace = "root\cimv2\power" ErrorAction = "Stop" } $PlanQuery = "select InstanceID,ElementName from Win32_Powerplan WHERE ElementName='$PlanName' OR InstanceID LIKE '%$PlanName'" # Get the Active Power Plan Write-Information "Querying win32_PowerPlan - $PlanQuery" $CimParameters["Query"] = $PlanQuery $PowerPlan = Get-CimInstance @CimParameters $PowerPlanId = $PowerPlan | Select-Object -ExpandProperty InstanceId | Split-Path -Leaf if ($null -eq $PowerPlanId){ throw "Power Plan [$PlanName] was not found on computer [$ComputerName]!" } Write-Information "Found power plan [$PlanName] on computer [$ComputerName]" #Get Setting Name / ID $CimParameters["Query"] = "select ElementName,InstanceID from Win32_PowerSetting WHERE ElementName = '$SettingName' OR InstanceId LIKE '%$SettingName'" $SettingId = Get-CimInstance @CimParameters | Select-Object -ExpandProperty InstanceId | Split-Path -Leaf if ([string]::IsNullOrEmpty($SettingId)){ throw "Setting [$SettingName] was not found on computer [$ComputerName]!" } Write-Information "Matched setting name [$SettingName] with setting ID [$SettingId]" $CimParameters["Query"] = "select * from Win32_PowerSettingDataIndex WHERE InstanceID LIKE '%$PowerPlanId\\$SettingType\\$SettingId'" $Setting = Get-CimInstance @CimParameters if ($null -eq $Setting){ throw "Unable to find setting with supplied parameters on computer [$ComputerName]!" } #$Setting Invoke-Command -ComputerName $ComputerName -ScriptBlock { Set-CimInstance -Namespace "root\cimv2\power" -Query $args[0] -Property @{SettingIndexValue = $args[1]} powercfg /setactive $args[2].Replace('{',"").Replace('}',"") } -ArgumentList $CimParameters["Query"],$IndexValue,$PowerPlanId $Session | Remove-CimSession -ErrorAction SilentlyContinue } catch{ $Session | Remove-CimSession -ErrorAction SilentlyContinue $PSCmdlet.WriteError($_) } #try / catch } #Process } |