Powershell continues to be an important part of the Microsoft ecosystem. Most of this learning is based on Microsoft documentation, a few blogs, and google and stack overflow searches. Please note that the focus of this article is on building complex packages and tools rather than single file scripts. Modules Modules are one of the fundamental blocks of packaging in PowerShell. Most of the teams would probably end up creating a module to collect a set of common utility functions or share the finished component with larger teams through . Alternatively, modules can also be imported locally (see bootstrap below) and used as part of scripts. PowerShell Gallery Powershell Modules typically should follow a standard structure and configuration to ensure consistent outcomes and reduce potential issues. The following directory structure ensures that you can have the right place for each component involved. The recommended module directory structure aligns with standard guidance for writing the module. The root directory should be named to uniquely identify module and match the module name. The file is pretty standard files generated and then updated to align with specific module. The “ ” and “ ” in PSD1 file points to “ ” file that contains basic module reference. available PSD1 RootModule ModuleList <module name>.psm1 The folder contains scripts files that contain functions, class that should be exported. The folder should be used to store helper functions. folder can be used to store dll or other components that is used by module. public private bin The file below contains some additions to reference available . psm1 here #Get public and private function definition files.
$Public  = @( Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue )
$Private = @( Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue )

#Dot source the files
Foreach($import in @($Public + $Private))
{
    Try
    {
        . $import.fullname
    }
    Catch
    {
        Write-Error -Message "Failed to import function $($import.fullname): $_"
    }
}

 Set-Variable -Name SCRIPT_PATH -Value (Split-Path (Resolve-Path $myInvocation.MyCommand.Path)) -Scope local
 Set-Variable -Name FULL_SCRIPT_PATH -Value (Resolve-Path $myInvocation.MyCommand.Path) -Scope local
 Set-Variable -Name CURRENT_PATH -Value ((Get-Location).Path) -Scope local
 Set-Variable -Name LOGGER -Value $null -Scope global
 
 # Export functions
 Export-ModuleMember -Function <Function name> Export function in the modules instead of class where possible to avoid reload issues associated with class. All the functions defined in scripts should contain basic documentation tags like , , (s), , . The following sample can be used as a guide for creating functions. .SYNOPSIS .DESCRIPTION .PARAMETER .OUTPUTS .EXAMPLE <#
  .SYNOPSIS
    This contain all the sample utility functions
  .DESCRIPTION
    Sample utility functions should be used across all sample applications
#>

<#
  .SYNOPSIS
    Quick function description
  .DESCRIPTION
    This is a very long description about the function below
  .PARAMETER  OneParameter
    Description of parameter including allowed values.
  .PARAMETER TwoParameter
    Another description
  .OUTPUTS
    Exit codes:
    0 : Success
    1 : Unkown error
    2 : More specific error code
  .Example
    Run-SampleFunction -OneParameter "some value"
 #>
Function Run-Samplefunction {
  [CmdletBinding()]
  [OutputType([int])]
  param (
    [Parameter(Mandatory = $True, Position = 0)]
    [PSCustomObject]$OneParameter,
    [Parameter(Mandatory = $True, Position = 1)]
    [PSCustomObject]$TwoParameter,
   )
  Process {
    $LASTEXITCODE = 1
    # Write-LogDebug "Entering function Run-Samplefunction"
    try {
       # ....do something.... 
    } catch [System.Exception] {
      $ErrorMessage = $_.Exception.Message
      # Write-LogError "Message: $ErrorMessage"
    }
    # Write-LogDebug "Leaving function Run-Samplefunction"
    return $LASTEXITCODE
  }
 } Note the use of that provides some advanced like binding predefined arguments to the function. In addition to that well-defined s and can reduce the boilerplate validation code. Using ( , , ) ensures that your functions are prepared for . Use of and return exit code is recommended approach but should be evaluated in line with internal coding guidelines. CmdletBinding() capabilities parameter output input processing methods Begin Process End pipelines try…catch Common Utility Most of the big developments should evaluate the use and need of the following components. Logging A simple level-based logging mechanism can be created using log4net and/or Write-Host function with function signatures like , to ensure that logging at different levels can be enabled and or disabled through a common mechanism (see bootstrap below). Write-LogDebug ($Text) Write-LogInfo ($Text) Configuration Develop a JSON or equivalent model of config that has the ability to load configuration from a file using equivalent to the following command $configData = New-Object -TypeName PSCustomObject -argumentlist (Get-Content -Raw -Path $ConfigFile | ConvertFrom-Json) It may be helpful to have a standard naming convention while designing the configuration file to ensure that you have a common configuration ( ) along with component-specific configuration ( ). In addition to that develop helper functions that can return config associated with the key name specified in dot-separated format can ensure that each component can have its own format for configuration and know how to handle it without bothering about the rest of the configuration structure. See the section on bootstrap below on how the configuration loading can be performed. config.common config.component Credential/Security It is important to develop a helper security function at the start of the project and use it consistently in the code to ensure that over time the code can use updates being made from a security perspective. Such helper functions should create for reading passwords using config (either by decrypting from config or retrieving from the vault with a simple configuration change) and return object to be used. Another important helper function can be a common authentication mechanism when multiple authentications can be performed (for example Azure can support multiple authentication mechanisms like id/password, service principal/password, certificate), it may be helpful to have a single authentication function that chooses actual authentication process based on configuration. PSCredential Scripts In a large development, multiple scripts across different use-cases would typically be developed. Such a development if it follows standard structure can significantly simplify the overall process. At the very basic it is recommended, that a standard directory structure is developed to package these development components. The root directory should contain with specific details about how the packaging has been done, various scripts available and specific examples to run the script. The directory contains the various scripts along with a common which provides a standard mechanism to handle configuration, load common modules, initialize logging, handle common parameters (see below for more details). The directory contains the configuration file with default values and the folder contains various templates and other files needed to run the script. Additional directory like , may be created as needed by script as part of the execution process. Readme.md bin bootStrap.ps1 config data logs tmp Bootstrap The can contain typical operations that can not be handled in a module due to dependency on specific parameters. It is recommended, that the bootstrap should have a function like the one below that can be called by any script. bootstrap.ps1 Function BootStrap { [CmdletBinding()] [OutputType([PSCustomObject])] Param([string[]] $ModulesToLoad, [string] $ConfigFile, [string] $ConfigToLoad, [string] $LogLevel, [string] $LogType) This function should perform the following functions Identify the root location of deployment (parent of the shown above) <Root Directory> Add the root location to (if not already set) to ensure that all the modules that are part of the package can be imported without dependency on external repository like . $env:PSModulePath PSGallery Import basic modules provided If (!(Get-Module Sample.Common-Utils)) {     Import-Module Sample.Common-Utils -Force -ErrorAction Stop } Initialize logger and any other common system needed. Load all the modules passed as after checking if the module is available. If not, then it tries to install using $ModulesToLoad Install-Module $ModuleName -AllowClobber -Force -ErrorAction Stop -Scope CurrentUser Tries to locate the config file by resolving it as it is and then trying to locate it in directory and then in directory using the variable (see above). bin config $SCRIPT_PATH Load the configuration data and return the same. All the scripts should be defined with well-defined Parameter list and run the bootstrap as follows $LASTEXITCODE = 1
$SCRIPT_PATH= Split-Path (Resolve-Path $myInvocation.MyCommand.Path)
./$SCRIPT_PATH\bootStrap.ps1
# This line allows passing all command line parameters to bootstrap function
$BootstrapParameters =$PSBoundParameters
$loadModuleList = “Sample.Common-Utils”,”Sample.Az-Utils”
$BootstrapParameters.Add(‘ModulesToLoad’, $loadModuleList)
$ConfigData = BootStrap @BootStrapParameters
# continued code for script Powershell continues to play an important part of automation within the Microsoft ecosystem. Leveraging the recommendations described above can significantly improve the developer experience and reduce the overall time of development for large projects. First published here

Google

Microsoft

Enterprise Cloud Security Guide: Secure Application Development

Read My Stories

Nominated for 2022 - HackerNoon Contributor of the Year - Cybersecurity

Too Long; Didn't Read

Make resilience your competitive advantage

Getting Started with Microsoft's PowerShell

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Enterprise Cloud Security Guide: Secure Application Development

10 Indications That You Should Invest in Automation Via APIs

10 Commandments for AI-Assisted Social Media Marketers

11 Best Automation Testing Tools to Try in 2021

12 Use Cases of AI and Machine Learning In Finance

Enterprise Cloud Security Guide: Secure Application Development

10 Indications That You Should Invest in Automation Via APIs

10 Commandments for AI-Assisted Social Media Marketers

11 Best Automation Testing Tools to Try in 2021

12 Use Cases of AI and Machine Learning In Finance

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps