In this post I will show you a very simple example of how advanced functions in PowerShell 2.0 can be used to declared your own cmdlets. If you want to run these script samples you will need to run PowerShell as an Administrator when executing set-name and join-workgroup.
Joining a workgroup:
$sysInfo = Get-WmiObject -Class Win32_ComputerSystem
$sysInfo.JoinDomainOrWorkgroup( "Bradley" )
Changing the computer name
Another useful example is changing the name of the computer, to do this issue the following command, but remember you must execute this command while in a PowerShell session that has Administrative privileges and you will be required to reboot the computer before these changes take effect (Restart-Computer can do this for you):
$sysInfo = Get-WmiObject -Class Win32_ComputerSystem
$sysInfo.Rename("FORSETI")
For completeness and fun I'll now show you how you can take these simple lines of script and create your own cmdlets so that you will have the cmdlets Get-ComputerName, Set-ComputerName, Get-Workgroup and Join-Workgroup at your disposal.
Get-ComputerName
This cmdlet just returns the value held in the environment variable COMPUTERNAME, I'm providing this cmdlet just to have consistency in getting and setting the name of a computer. If you wish to run this script on PowerShell 1.0 simply remove the block comment, this has been included to illustrate how you may document you cmdlets.
function Get-ComputerName
{
<#
.SYNOPSIS
Gets the name of the computer
.DESCRIPTION
Returns a string containing the name of the computer
.NOTES
File Name: ComputerName.psm1
Aurthor: Alan Bradley
Requires: PowerShell 2.0
.LINK
http://www.gangleri.net
.EXAMPLE
Get-ComputerName
#>
process
{
$Env:COMPUTERNAME
}
}
Set-ComputerName
Not much more complicated than the Get-ComputerName cmdlet but this one accepts a parameter that will be the new name of the computer, if ts successfully changes the name of the computer it will prompt the user to reboot the machine so that the change can be applied. I have provided a switch parameter called 'AutoReboot' that when provided will automatically reboot the machine when the name has successfully been changed.
function Set-ComputerName
{
<#
.SYNOPSIS
Sets the name of the computer
.DESCRIPTION
Uses WMI to set the name of the computer, if the name is successfully changed the user will be prompted to reboot and apply the changes
.NOTES
File Name: ComputerName.psm1
Aurthor: Alan Bradley
Requires: PowerShell 2.0
.LINK
http://www.gangleri.net
.EXAMPLE
Set-ComputerName -Name "{New name for computer}"
.EXAMPLE
Set-ComputerName "{New name for computer}"
.EXAMPLE
Set-ComputerName -Name "{New name for computer}" -AutoReboot
.EXAMPLE
Set-ComputerName "{New name for computer}" -AutoReboot
.PARAMETER Name
The new name that the computer will be known by
#>
param(
[Parameter(Position=0, Mandatory=$true,ParameterSetName="Name")]
[string]$Name,
[Switch]$AutoReboot
)
process
{
$sysInfo = Get-WmiObject -Class Win32_ComputerSystem
$result = $sysInfo.Rename($Name)
switch($result.ReturnValue)
{
0
{
Write-Host -ForegroundColor Green "Success"
if($AutoReboot -eq $false)
{
$yes = New-Object System.Management.Automation.Host.ChoiceDescription "&Yes", `
"Reboots the machine."
$no = New-Object System.Management.Automation.Host.ChoiceDescription "&No", `
"Does not reboot the machine, you will manually have to reboot this machine for changes to take effect."
$options = [System.Management.Automation.Host.ChoiceDescription[]]($yes, $no)
$ShouldReboot = $Host.UI.PromptForChoice("Reboot machine", `
"You must reboot for change to take effect. Do you want to reboot now?", $options, 0)
}
if($ShouldReboot -eq 0 -or $AutoReboot -eq $true)
{
Restart-Computer
}
}
5 { Write-Host -ForegroundColor Red "This cmdlet must be execute with administrative privileges" }
default { Write-Host -ForegroundColor Red "Error" }
}
}
}
Get-Workgroup
Similarly cmdlets can be created for changing the workgroup and domain settings. Here is the cmdlet that can be used to get the workgroup name. Again this can be adapted for PowerShell 1.0 by removing the block comments.
function Get-Workgroup
{
<#
.SYNOPSIS
Get the Workgroup name that the computer currently belongs to
.DESCRIPTION
This cmdlet returns the name of the Workgroup that the computer
currently belongs to.
.LINK
http://www.gangleri.net
.Example
Get-Workgroup
#>
process
{
(Get-WmiObject -Class Win32_ComputerSystem).Workgroup
}
}
Join-Workgroup
Joining a Workgroup can be achieved with the following cmdlet. This cmdlet uses some of the new advanced binding abilities added to PowerShell 2.0 for parameters.
function Join-Workgroup
{
<#
.SYNOPSIS
Joins the specified Windows work group
.DESCRIPTION
This cmdlet allows you to specify the name of a Windows Workgroup
that you would like to join the computer to. You will need to reboot
for these changes to take effect so the cmdlet will prompt you to do
this, alternatively you can use the -AutoReboot switch as this will
automatically reboot the machine so that the changes are applied.
.LINK
http://www.gangleri.net
.Example
Join-Workgroup "WorkgroupName"
.Example
Join-Workgroup "WorkgroupName" -AutoReboot
.EXAMPLE
Join-Workgroup -Workgroup "WorkgroupName"
.EXAMPLE
Join-Workgroup -Workgroup "WorkgroupName" -AutoReboot
.PARAMETER Workgroup
The name of the Windows Workgroup you wish to join
.PARAMETER AutoReboot
If supplied this instructs the cmdlet to automatically
reboot the computer so that the changes can take effect
#>
param(
[Parameter(Position=0, Mandatory=$true,ParameterSetName="Workgroup")]
[string]$Workgroup,
[Switch]$AutoReboot
)
process
{
$sysInfo = Get-WmiObject -Class Win32_ComputerSystem
$result = $sysInfo.JoinDomainOrWorkgroup( $Workgroup )
switch($result.ReturnValue)
{
0
{
Write-Host -ForegroundColor Green "Success"
if($AutoReboot -eq $false)
{
$yes = New-Object System.Management.Automation.Host.ChoiceDescription "&Yes", `
"Reboots the machine."
$no = New-Object System.Management.Automation.Host.ChoiceDescription "&No", `
"Does not reboot the machine, you will manually have to reboot this machine for changes to take effect."
$options = [System.Management.Automation.Host.ChoiceDescription[]]($yes, $no)
$ShouldReboot = $Host.UI.PromptForChoice("Reboot machine", `
"You must reboot for change to take effect. Do you want to reboot now?", $options, 0)
}
if($ShouldReboot -eq 0 -or $AutoReboot -eq $true)
{
Restart-Computer
}
}
5 { Write-Host -ForegroundColor Red "This cmdlet must be execute with administrative privileges" }
default { Write-Host -ForegroundColor Red "Error" }
}
}
}
Changing the Domain
Working with domains is similar to working with workgroups, you will use the JoinDomainOrWorkgroup method only you need to specify additional arguments for the user name and password. The values one and two are important. One means join the domain and two means create the account.
$sysInfo = Get-WmiObject -Class Win32_ComputerSystem
$sysInfo.JoinDomainOrWorkgroup( "Bradley", "password", "Bradley\Admin", 1, 2 )
If you fancy a small challenge you could try writing your own cmdlet 'Join-Domain' give me a shout if you need any help. Also how the return codes are processed could be wrapped up in a function I've just duplicated code here to make it easy for people to copy/paste these examples and play with them. I'll be posting a sort example of turning these scripts into PowerShell 2.0 modules that you can easily distribute to others.
Although the add-computer cmdlet in PowerShell 2.0 can achieve this same functionality I still think these are good examples of developing your own cmdlets using PowerShell 2.0 advanced functions as they are not complicated and allow you to focus on the nuts and bolts of advanced functions. Next I'll walk you through packaging these as modules so that you will then be in a position to easily redistribute your cmdlets to others.