Sharepoint 2010 : Windows PowerShell Scripts (part 3) - Writing Comment-Based Help Topics in Scripts,Using Functions in Scripts , Customizing Windows PowerShell with Profile Scripts

Writing Comment-Based Help Topics in Scripts

Cmdlets in Windows PowerShell include a help topic that describes how to use the cmdlets in Windows PowerShell. When writing scripts, you can add a custom comment-based help topic using a comment block (enclosed with <# and #> ) containing at least one keyword. Some of the valid keywords are synopsis, description, parameter (followed by the parameter name), example, inputs, outputs, notes, links, component, role, and functionality. Here is an example that demonstrates how to add a comment-based help topic to a script in Windows PowerShell:

<#
.SYNOPSIS
Displays firstname and lastname

.DESCRIPTION
The myScript.ps1 script displays the firstname and lastname.

.PARAMETER firstname
Specifies the users firstname

.PARAMETER lastname
specifies the users lastname

.OUTPUTS
System.String. myScript.ps1 returns a string with the users firstname and lastname

.EXAMPLE
PS > .\myScript.ps1 Niklas Goude
FirstName: Niklas
LastName: Goude

#>

param([string]$firstname, [string]$lastname)
"FirstName: $firstname"
"LastName: $lastName"


					  

When a comment-based help topic is added to a script, you can use the Get-Help cmdlet to display the help topic in the session. Here is how we could display the help topics added to the previous script:

PS > Get-Help .\myScript.ps1 -Examples

NAME
    C:\Scripts\myScript.ps1

SYNOPSIS
    Displays firstname and lastname

    -------------------------- EXAMPLE 1 --------------------------

    PS >.\myScript.ps1 Niklas Goude

    FirstName: Niklas
    LastName: Goude

Using Functions in Scripts

You can add functions in a script by placing them at the top of the script. (This might seem strange if you are used to VBScript.) Since Windows PowerShell reads the script from top to bottom, an error will occur if a function is called before it has been read into memory.

Here is an example of a Windows PowerShell script that includes a function:

param([string]$Identity)

function Check-Url([uri]$url) {
  if($url.AbsoluteUri -ne $Null -and $url.Scheme -match 'http|https') {
    $true
  } else {
    $false
  }
}

if(Check-Url -url $Identity) {
  Get-SPWeb -Identity $Identity
} else {
  Write-Host "Invalid URL"
}

This script starts with a param statement, where we define the script parameters. Here, we use the type System.String for the input parameter. Next, we add our function to the script. At the bottom of the script, we add our code that executes when the script is run. We start off by validating the URL passed to the script. If the URL is valid, the script attempts to run the Get-SPWeb cmdlet. If not, the script returns Invalid URL.

Customizing Windows PowerShell with Profile Scripts

Profile scripts run automatically when Windows PowerShell starts. Using profile scripts, you can customize the Windows PowerShell environment and add commands, aliases, functions, variables, snap-ins, and drives to every Windows PowerShell session that you start. Windows PowerShell supports the four basic profile scripts shown Table 1.

Table 1 shows how different profile scripts affect different users and shells. For instance, a profile script named profile.ps1 placed in the Windows PowerShell root folder affects all users. A profile script with the same name placed in the user’s home folder affects only that user.

For example, if we wanted all Windows PowerShell sessions to start by displaying “Hello” followed by the current user’s name, we would create a new profile script in the Windows PowerShell root folder and place the following code in that profile script:

PS > '"Hello $env:USERNAME"' | Out-File $PSHOME\profile.ps1