HELP METADATA and New-EnvironmentVariable

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!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s