HowTo: Use Parameter Validation In PowerShell for ProjectWise (2 of 2)

Be sure to check out my Scripting4Crypto initiative. It’s a fun way to get into using cryptocurrencies all while getting your PowerShell needs met.

In this post, I will be covering how to add ProjectWise specific Variable Validation Attributes to PowerShell. These will help you create more efficient PowerShell functions which work with ProjectWise objects.

As stated in my previous post, many of us have developed functions within PowerShell to accomplish different tasks related to ProjectWise. Within our functions we probably have parameters which require some data or values to be passed into them. To ensure these parameters are receiving what we expect as proper values (data type, not null, etc.), we often add some code in our script to test or validate these values. If the value(s) don’t meet certain criteria, we will exit the function. Lets upgrade those functions to use these new ProjectWise specific Variable Validation Attributes.

Class Definitions

Validation Template

In this section, we will look at a template Variable Validation Attribute which you can use to create new ones. There are only two changes required.

1. Enter a name for the new Variable Validation Attribute. It must begin with Validate and end with Attribute. In the following you would replace <NEWVALIDATIONNAME> with the desired name. Example: ValidateProjectWiseFolderExistsAttribute
2. Add the code to determine whether or not the value passed is valid.

<# Description: Validates something.
    If it does not, throws an error. #>
class Validate<NEWVALIDATIONNAME>Attribute : System.Management.Automation.ValidateArgumentsAttribute {

    [void]Validate( [object]$value,[System.Management.Automation.EngineIntrinsics]$engineIntrinsics ) {

        #region VALIDATION CODE
        
            #ENTER VALIDATION CODE HERE

        #endregion VALIDATION CODE

    }
} # end class Validate<NEWVALIDATIONNAME>Attribute

ValidateProjectWiseFolderExists

The first validation attribute we will create will take a provided ProjectWise folder path value and use the Get-PWFolders cmdlet to determine if the folder exists within the current ProjectWise datasource. If you are not logged into a ProjectWise datasource, it will error. If the folder provided in invalid, it will generate an error.

<# Validates if the folder is a valid ProjectWise folder. 
    If it does not, throws an error. #>
class ValidateProjectWiseFolderExistsAttribute : System.Management.Automation.ValidateArgumentsAttribute {

    [void]Validate( [object]$value, [System.Management.Automation.EngineIntrinsics]$engineIntrinsics ) {

        #region VALIDATION CODE

        if( -not (Get-PWFolders -FolderPath $value -JustOne)) {
            throw "Provided ProjectWise folder '$value' was NOT found in current ProjectWise datasource '$(Get-PWCurrentDatasource)'."
        }

        #endregion VALIDATION CODE
    }

} # end class ValidateProjectWiseFolderExistsAttribute...

ValidateProjectWiseFolderNotExists

The ValidateProjectWiseFolderNotExistsAttribute will verify if a ProjectWise folder DOES NOT exist. This can be useful when you want to create a new Work Area or folder. You want to ensure it does not exist prior to continuing into a function. This will take the provided ProjectWise folder path value and use the Get-PWFolders cmdlet to determine if the folder exists within the current ProjectWise datasource. If the folder does exist, it will cause a failure and thus return an error.

<# Validates whether or not a provided ProjectWise folder exists. 
    If it DOES, throws an error. #>
class ValidateProjectWiseFolderNotExistsAttribute : System.Management.Automation.ValidateArgumentsAttribute {

    [void]Validate([object]$value, [System.Management.Automation.EngineIntrinsics]$engineIntrinsics) {

        #region VALIDATION CODE

        if( Get-PWFolders -FolderPath $value -JustOne -WarningAction SilentlyContinue) {
            throw "Provided ProjectWise folder '$value' WAS found in current ProjectWise datasource '$(Get-PWCurrentDatasource)'. The folder must NOT exist."
        }

        #endregion VALIDATION CODE
    }

} #end class ValidateProjectWiseFolderNotExistsAttribute...

ValidateProjectWiseWorkAreaTemplateExists

The ValidateProjectWiseWorkAreaTemplateExistsAttribute will verify if the provided Work Area template exists. This can be useful when you want to create a new Work Area from a template. You want to ensure the template exists prior to continuing into a function. This will take the provided ProjectWise Template Name value and use the Get-PWProjectTemplates cmdlet to determine if the template exists within the current ProjectWise datasource. If the Work Area template does NOT exist, it will cause a failure and thus return an error.

<# Validates whether or not a provided ProjectWise Work Area template exists. 
    If it does not, throws an error. #>
class ValidateProjectWiseWorkAreaTemplateExistsAttribute : System.Management.Automation.ValidateArgumentsAttribute {

    [void]Validate([object]$value, [System.Management.Automation.EngineIntrinsics]$engineIntrinsics) {

        #region VALIDATION CODE

        if( -not (Get-PWProjectTemplates | Where-Object Name -eq $value)) {
            throw "Provided ProjectWise Work Area template '$value' was not found in current ProjectWise datasource '$(Get-PWCurrentDatasource)'."
        }
        
        #endregion VALIDATION CODE
    }

} #end class ValidateProjectWiseWorkAreaTemplateExistsAttribute...

ValidateProjectWiseStorageAreaExists

The ValidateProjectWiseStorageAreaExistsAttribute will verify if the provided Storage Area exists. This can be useful when you want to create a new Folder or Work Area. You want to ensure the Storage Area exists prior to continuing into a function. This will take the provided ProjectWise Storage Area Name value and use the Get-PWStorageAreaList cmdlet to determine if the storage area exists within the current ProjectWise datasource. If the Storage Area does NOT exist, it will cause a failure and thus return an error.

<# Validates whether or not a provided ProjectWise storage area exists. 
    If it does not, throws an error. #>
class ValidateProjectWiseStorageAreaExistsAttribute : System.Management.Automation.ValidateArgumentsAttribute {

    [void]Validate([object]$value, [System.Management.Automation.EngineIntrinsics]$engineIntrinsics) {

        #region VALIDATION CODE

        if( -not (Get-PWStorageAreaList -StorageAreaNames $value)) {
            throw "Provided ProjectWise Storage Area '$value' was not found in current ProjectWise datasource '$(Get-PWCurrentDatasource)'."
        }

        #endregion VALIDATION CODE
    }

} #end class ValidateProjectWiseStorageAreaExistsAttribute...

ValidateProjectWiseEnvironmentExists

The ValidateProjectWiseEnvironmentExistsAttribute will verify if the provided Environment exists. This can be useful with many cmdlets. You want to ensure the Environment exists prior to continuing into a function. This will take the provided ProjectWise Environment Name value and use the Get-PWEnvironments cmdlet to determine if the Environment exists within the current ProjectWise datasource. If the Environment does NOT exist, it will cause a failure and thus return an error.

<# Validates whether or not a provided ProjectWise Environment exists. 
    If it does not, throws an error. #>
class ValidateProjectWiseEnvironmentExistsAttribute : System.Management.Automation.ValidateArgumentsAttribute {

    [void]Validate([object]$value, [System.Management.Automation.EngineIntrinsics]$engineIntrinsics) {

        #region VALIDATION CODE

        $result = (Get-PWEnvironments).GetEnumerator() | Where-Object Name -eq $value 
        if( -not ($result)) {
            throw "Provided ProjectWise Environment '$value' was not found in current ProjectWise datasource '$(Get-PWCurrentDatasource)'."
        }

        #endregion VALIDATION CODE
    }

} #end class ValidateProjectWiseEnvironmentExistsAttribute...

Using the ProjectWise Variable Validation Attributes

Now that we have all of the classes created, the classes need to be imported into the current PowerShell session in order to be used. I have added them to my PowerShell profile to ensure they are always available.

I have created a function to demonstrate using the new ProjectWise Variable Validation Attributes.  The function will accept multiple parameter values, each corresponding to one of the new Variable Validation Attributes.

FUNCTION Test-PWWorkArea {
    [CmdletBinding()]
    param (
        #region param

        [ValidateProjectWiseFolderExists()]
        [ValidateNotNullOrEmpty()]
        [Parameter(Mandatory = $true)]
        [string]$ParentFolderPathName,

        [ValidateProjectWiseFolderNotExists()]
        [ValidateNotNullOrEmpty()]
        [Parameter(Mandatory = $true)]
        [string]$NewFolderPathName,

        [ValidateProjectWiseWorkAreaTemplateExists()]
        [ValidateNotNullOrEmpty()]
        [Parameter(Mandatory = $true)]
        [string]$TemplateName,

        [ValidateProjectWiseStorageAreaExists()]
        [ValidateNotNullOrEmpty()]
        [Parameter(Mandatory = $true)]
        [string]$StorageArea,

        [ValidateProjectWiseEnvironmentExists()]
        [ValidateNotNullOrEmpty()]
        [Parameter(Mandatory = $true)]
        [string]$Environment

        #endregion param 
    ) # end param...

    BEGIN { } # end BEGIN...

    PROCESS {

        Write-Host "New Work Area Name: $($ParentFolderPathName)$NewFolderPathName" -ForegroundColor Green
        Write-Host " - $ParentFolderPathName (Parent Folder)" -ForegroundColor Green
        Write-Host " - $TemplateName (Template)" -ForegroundColor Green
        Write-Host " - $StorageArea (Storage)" -ForegroundColor Green
        Write-Host " - $Environment (Environment)" -ForegroundColor Green

    } # end PROCESS...

    END { } # end END...
} # end FUNCTION Test-PWWorkArea...

Invalid NewFolderPathName parameter value provided:

Invalid ParentFolderPathName parameter value provided:

Invalid TemplateName parameter value provided:

Invalid StorageArea parameter value provided:

Invalid Environment parameter value provided:

All parameter values were valid, therefore we have Success:

Summary

So lets recap what we have done. First, we defined five new ProjectWise specific Variable Validation Attribute classes. Each of these can be used to validate a variable or a parameter value passed to a function. Then, we created a new function to test each of the five Validation Attributes. Finally, we demonstrated the behavior for each upon failure.

---

Experiment with it and have fun.

Hopefully, you find this useful. Please let me know if you have any questions or comments.  If you like this post, please click the Like button at the bottom of the page.