Skip to content

Best practices

CmdletBinding

Always add this code snippet at the start, or directly after help section. If the script does not have these parameters (or at least 2 positional parameters) PowerShell will not be able to execute the script correctly.

1
2
3
4
5
6
7
    [CmdletBinding()]
    param(
        [Parameter(Mandatory,Position=0)]
        [string]$StringInput,
        [Parameter(Mandatory,Position=1)]
        [string]$Base64StringFromStdIn
    )

EPR will try to start a new PowerShell process for each request it receives with the body from that request as a positional argument to the script. We also send a base64 representation of the JSON body via stdin.

1
    C:\Users\administrator> C:\Program Files\PowerShell\7\pwsh.exe -File [scriptfile.ps1] [requestbody]

Avoid using any of the Write-* cmdlets built in to PowerShell (Ex. Write-Verbose, Write-Error, Write-Warning) as they will produce output written back to EPR. Instead, use the Write-CustomLog function in the Easit.ProcessRunner.GlobalFunctions module.

Begin / Process / End

We strongly recommend that you use this structure for the best flow control and error handling.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    [CmdletBinding()]
    param(
        [Parameter(Mandatory,Position=0)]
        [string]$StringInput,
        [Parameter(Mandatory,Position=1)]
        [string]$Base64StringFromStdIn
    )
    begin {}
    process {}
    end {}

Begin block

To best leverage the built-in function and additional / side loaded modules / scripts we recommend you to add these in the corresponding directory under helpers and add this code snippet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    $envParams = @{
        Modules = 'Easit.GO.Webservice','ActiveDirectory'
        CustomModules = "myCustomModule1"
    }
    try {
        Import-Module 'D:\Easit\EPR-Test\scripts\helpers\modules\Easit.ProcessRunner.GlobalFunctions'
        Set-EPREnvironment @envParams
    } catch {
        Write-Warning $_
        return
    }

The Set-EPREnvironment function will loop over and load any modules specified as Modules or CustomModules.

In the example above we have saved 3 modules to the modules folder in the helpers folders with the command below.

1
2
3
4
5
    C:\Users\administrator> $saveModuleParams = @{
        Name = 'Easit.GO.Webservice'
        Path = 'D:\Easit\EPR-Test\scripts\helpers\modules'
    }
    C:\Users\administrator> Save-Module @saveModuleParams

Process block

If you would like to utilize the function Write-CustomLog and globalSettings.json, the following code should be added first in the process block. Please avoid using throw or any other terminating error technique and instead use the return keyword to correctly execute the end block.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
    Write-CustomLog -Message "Starting script"
    try {
        $settings = Get-SettingsFromFile
        Write-CustomLog -InputObject $settings -Level DEBUG
    } catch {
        Write-CustomLog -Message "$($_.Exception)" -Level ERROR
        return
    }
    if (!([string]::IsNullOrEmpty($settings.LogOutputLevel))) {
        $epr_LoggerSettings.OutputLevel = $settings.LogOutputLevel
    }
    if (!([string]::IsNullOrEmpty("$($settings.LogRotationInterval)"))) {
        $epr_LoggerSettings.RotationInterval = $settings.LogRotationInterval
    }
    Write-CustomLog -InputObject $epr_LoggerSettings -Level DEBUG
    Write-CustomLog -Message "Rotating logs" -Rotate

To access the exported item from Easit GO we recommend you use the following approach.

1
2
3
4
5
6
7
    try {
        Write-CustomLog -Message "Converting StringInput"
        $easitGOItem = Convert-EasitGOExportString -InputString $Base64StringFromStdIn
    } catch {
        Write-CustomLog -Message "$($_.Exception)" -Level ERROR
        return
    }

You can then access the properties for the item like this.

1
    $easitGOItem.propertyName

End block

Use this block for any cleanup, error notification and such.