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.