The function I wrote and decided to use during this post wasn’t an absolute requirement, like a majority of my functions. And like most functions, the first few times it is used won’t provide a return on investment. But as I spend allot of time working with software that likes to use Environment Variables, it made sense to write the function to be called and used many times that would set these values for me!
Now, in the interest having this function used by other people in my team, I thought it best for personal and professional expansion to write some function help to assist others when using my function. I have made it a personal goal moving forward to ensure all of my functions have this data available.
HELP METADATA – about_comment_based_help
Help meta data isn’t required to get a function up and running, but it should be a personal/professional requirement to ensure that when someone else uses your functions that they have the information available to their finger tips. This is where the function METADATA comes in (Or as it is correctly known, about_comment_based_help).
I normally only worry about the ‘Synopsis’, ‘Description’ and a series of ‘Examples’. But here is a list of what is possible as per the above link. You will need to have a read and decide what you think you need:
- .SYNOPSIS
- .DESCRIPTION
- .PARAMETER
- .EXAMPLE
- .INPUTS
- .OUTPUTS
- .NOTES
- .LINK
- .COMPONENT
- .ROLE
- .FUNCTIONALITY
- .FORWARDHELPTARGETNAME
- .FORWARDHELPCATEGORY
- .REMOTEHELPRUNSPACE
- .EXTERNALHELP
Each of these Metadata headings need to be placed in a comment block at the beginning of your function script, be written in capitals and prefixed with a full stop ( . ). Here is the synopsis for my latest function, New-EnvironmentVariable. You will notice all of the info is placed between <# ..... #>
<#
.SYNOPSIS
Function to add System & User based variables
.DESCRIPTION
Function to add permanent System & User based variables where the New-Item command only adds user based environment variables for the current session
.EXAMPLE
CREATES a new user based environment variable called "MYVAR_NAME" with a value of 'ValueOfEnvVar' for the current user context.
New-SVEnvironmentVariable -Name 'MYVAR_NAME' -Value 'ValueOfEnvVar' -Type User
.EXAMPLE
UPDATES a user based environment variable called "MYVAR_NAME" with a new value of 'MyNewValue' for the current user context.
New-SVEnvironmentVariable -Name 'MYVAR_NAME' -Value 'ValueOfEnvVar' -Type User -OverWrite
.NOTES
N/A
#>
Now, this allows me to call some help for the function and have a read about usage, this uses the Get-Help command specifically with the ‘-Examples’ switch – Here it is in action:
C:> Get-Help New-EnvironmentVariable -Examples
NAME
New-EnvironmentVariable
SYNOPSIS
Function to add System & User based variables
-------------------------- EXAMPLE 1 --------------------------
PS C:\>CREATES a new user based environment variable called "MYVAR_NAME" with a value of 'ValueOfEnvVar' for the current user context.
New-SVEnvironmentVariable -Name 'MYVAR_NAME' -Value 'ValueOfEnvVar' -Type User
-------------------------- EXAMPLE 2 --------------------------
PS C:\>UPDATES a user based environment variable called "MYVAR_NAME" with a new value of 'MyNewValue' for the current user context.
New-SVEnvironmentVariable -Name 'MYVAR_NAME' -Value 'ValueOfEnvVar' -Type User -OverWrite
Now, here is the whole function, have a go at loading the function and pulling some help – This will server 2 purposes – have you try giving it a go while also cutting this post nice and short!:
<#
.SYNOPSIS
Function to add System & User based variables
.DESCRIPTION
Function to add permanent System & User based variables where the New-Item comand only adds user based environment variables for the current session
.EXAMPLE
CREATES a new user based environment variable called "MYVAR_NAME" with a value of 'ValueOfEnvVar' for the current user context.
New-SVEnvironmentVariable -Name 'MYVAR_NAME' -Value 'ValueOfEnvVar' -Type User
.EXAMPLE
UPDATES a user based environment variable called "MYVAR_NAME" with a new value of 'MyNewValue' for the current user context.
New-SVEnvironmentVariable -Name 'MYVAR_NAME' -Value 'ValueOfEnvVar' -Type User -OverWrite
.NOTES
N/A
#>
function New-EnvironmentVariable {
[cmdletbinding()]
param(
[parameter(Mandatory=$true, Position='0')][String[]] $Name,
[parameter(Mandatory=$true, position='1')][String[]] $Value,
[parameter(Mandatory=$true, position='2')][ValidateSet('User','Machine')][String[]] $Type,
[parameter(Mandatory=$false, position='3')][Switch] $Overwrite
)
$Overwrite.ToBool | Out-Null
If ($Overwrite -eq $true)
{
Try
{
$ErrorActionPreference = 'stop'
[Environment]::SetEnvironmentVariable("$Name","$Value","$Type")
Write-Host "$Type variable $name has been written with a value of $value"
}
Catch
{
$ErrorMessage = $_.Exception.Message
$FailedItem = $_.Exception.ItemName
$ErrorMessage
$FailedItem
}
Finally
{
# Don't need to say much here
}
}
Elseif ($Overwrite -eq $false)
{
$PathCheck = Test-Path ('Env:\'+$Name)
IF ($PathCheck -eq 'true')
{
$UpperName = $name.ToUpper()
Write-Host "$type variable $upperName already exists, use the overwite switch if you would like to change the value."
}
Elseif ($Overwrite -eq $false)
{
Try
{
$ErrorActionPreference = 'stop'
[Environment]::SetEnvironmentVariable("$Name","$Value","$Type")
Write-Host "$Type variable $name has been written with a value of $value"
}
Catch
{
$ErrorMessage = $_.Exception.Message
$FailedItem = $_.Exception.ItemName
$ErrorMessage
$FailedItem
}
Finally
{
# Don't need to say much here
}
}
}
}
Good luck and happy scripting!
1024-Hobbytes 