Elektron Boson

Welcome to the Elektron Boson repository.

This module contains generic powershell scripts and functions to ease out the deployment of 2toLead solutions.

It also includes a set of utilities for configuring the SPFx build rig.

Installation

To install elektron-boson, run the following command

npm i elektron-boson --save-dev

Getting Started

Tools

• latest current version of NodeJs
• We recommend using Visual Studio Code as a lot of settings are pre-configured for it.

Deployment Framework

Pipeline templates

You may update the azure-pipelines.yml file of the source repository to include below reference to the build pipeline file along with required parameters.
Below shows an example for the change:

For SPFx project

stages:
    - stage: build
      displayName: Build
      jobs:
        - template: node_modules/elektron-boson/pipelines/spfx-build-template.yml
          parameters:
            nodeversion: '12.x'
            npmtest: 'true'
            sonarcloudconn: '2toLead SonarCloud'
            psmodules: 'true'
            vmimage: 'windows-latest'

For Intranet Release project

stages:
    - stage: build
      displayName: Build
      jobs:
        - template: node_modules/elektron-boson/pipelines/intranet-build-template.yml
          parameters:
            psmodules: 'false'
            vmimage: 'windows-2022'

For Utilizing AZ CLI and Azure PowerShell in a single deployment PS1 without conflict

# Important: See documentation within YML for full implementation guidance
- template: node_modules/elektron-boson/pipelines/utility/azure-cli.yml
  parameters:
    azureSubscription: 'LAB00X'
- task: AzurePowerShell@5
displayName: 'Azure Deployment'
inputs:
    azureSubscription: 'LAB00X'
    scriptType: 'FilePath'
    scriptPath: '$(Agent.BuildDirectory)/drop/Deployment/Deploy.ps1'
    scriptArguments: '-CICD_servicePrincipalId "$(ARM_CLIENT_ID)" -CICD_servicePrincipalKey "$(ARM_CLIENT_SECRET)" -CICD_tenantId "$(ARM_TENANT_ID)"'
    azurePowerShellVersion: OtherVersion
    preferredAzurePowerShellVersion: 9.4.0

.gitignore
Include following lines of code in the project .gitignore file

# Dependency directories
node_modules/*
!node_modules/elektron-boson/
node_modules/elektron-boson/*
!node_modules/elektron-boson/pipelines/
deploy/PSModules/*/*

SPFx Build

This module contains a utility function to ease out the configuration of the SPFx build pipeline.

To use it, edit the gulpfile.js file at the root of any SPFx project and add the following lines before calling the initialize() method:

const boson = require('elektron-boson');
boson.configureSPFxBuild(build);
...
build.initialize(gulp);

Gulp tasks

The method above will add the following gulp tasks:

Set Manifest Version (set-manifest-version)

This task updates the version property in the config/package-solution.json file based on build inputs.

Format: {Major Version (User Driven)}.YYYY.MMDD.{Todays Build Iteration}

Example

gulp set-manifest-version --buildnum 'Labs_EFx-CI_master_20190227.2'
# [Package-Solution.json] -> "version": "1.2019.0227.2"

Note: SharePoint trims leading zeros. I.e. the above example would be shown as 1.2019.227.2. Always assume a leading zero whenever three digits are seen for MMDD portion. For example, 111 in SharePoint would always be January 11th. 1110 would be November 10th. Later dates with trimmed zeros still functions correctly/always seen as a later version regardless.

Webpack

The configureSPFxBuild() method also extends the default webpack configuration by adding the Webpack Bundle Analyzer plugin and enabling source maps generation.

Webpack Bundle Analyzer

The Webpack Bundle Analyzer plugin allow you to visualize the size of webpack output files with an interactive zoomable treemap.

After building the SPFx solution, the analysis files will be stored under the /temp/stats folder.

Usage Tips

Import-PSModule

• This module will intentionally throw exceptions if conflicts are found when using Import-PSModule to prevent the installation from going further when confirmed version mismatch exists. This behavior can be overridden by setting $env:elektron_ignore_module_conflicts to $true prior to running the script.

Usage

Some files in this project may be unclear on how to utilize them and are outlined in Deploy.ps1 Sample

DynamicParams.ps1

Dynamic parameters are used to aid clients with knowing which parameters they will need depending on their system configuration.

The return type from this function, and all functions under the .\params folder is [System.Management.Automation.RuntimeDefinedParameterDictionary].

This return value must be returned in the DynamicParam script block as seen in Deploy.ps1 Sample.

NOTE: Due to a bug, returned values have to be re-added to the proper RuntimeDefinedParameterDictionary type as PowerShell appears to be returning the wrong type in the DynamicParam context. If resolved, please push an update.

The variables, and in which states they are returned, are outlined below:

1. [String] $UserName and [String] $Password: Used to define the login method used to the SPFx Site
   1. Requires [Switch] $IsConnected to be $false or $null
   2. Requires [String] $AuthType to be UserLogin
2. [String] $Thumbprint and [String] $ClientID: Used to define the login method used to the SPFx Site
   1. Requires [Switch] $IsConnected to be $false or $null
   2. Requires [String] $AuthType to be AppCertThumbprintClientID
3. [String] $SiteType: Used to define the style of site based on 2toLead site templates, who's values are defined by relative folder names
   1. Equates to a param set like [ValidateSet('SiteType1',''SiteType2')][String] $SiteType
   2. Requires [Switch] $SiteInit to be enabled
   3. To get a ValidateSet values of SiteType1 and SiteType2, you need a folder structure like below:
      • ./Sites/SiteType1
      • ./Sites/SiteType2

Start-Boson.ps1

Initiates all core Elektron-Boson configurations such as:

• Loading the framework (.\LoadFramework.ps1)
• Initiate logging
• Clear the error log
• Enable PauseOnError
• Run UseModules.ps1
• Load dependencies (Currently only Themes utility)

Run this function by splatting or passing the parameters for you scripts needs as seen in Deploy.ps1 Sample.

Deploy.ps1 Example

[CmdletBinding()]
Param(
    # COMMON DEPLOY SETTINGS
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [String]$Url,

    # DEPLOYMENT PROCESSES
    [Parameter(ParameterSetName = 'TenantInit', Mandatory)]
    [switch] $TenantInit,
    [Parameter(ParameterSetName = 'SiteInit', Mandatory)]
    [switch] $SiteInit,

    # AUTHENTICATION
    [Parameter(ParameterSetName = 'TenantInit')]
    [Parameter(ParameterSetName = 'SiteInit')]
    [ValidateSet('UserLogin', 'AppCertThumbprintClientID', 'Interactive')]
    [string] $AuthType,

    # SCRIPT SETTINGS
    [switch] $PauseOnError,
    [switch] $IsConnected
)
DynamicParam {
    # Collect parameter HashTable
    $runtimeParameterAggregate = (. "$PSScriptRoot\..\node_modules\Elektron-boson\DynamicParams.ps1" -SiteInit:$SiteInit -IsConnected:$IsConnected -AuthType $AuthType)
    # Map to RuntimeDefinedParameterDictionary
    $runtimeParameterDictionary = New-Object System.Management.Automation.RuntimeDefinedParameterDictionary
    $runtimeParameterAggregate.getenumerator() | ForEach-Object { $runtimeParameterDictionary.add($_.Key, $_.Value) }
    return $runtimeParameterDictionary
}
process {
    # Sets the Current Location to the executing Script folder
    Push-Location (Split-Path -Path $MyInvocation.MyCommand.Definition -Parent)

    $SolutionName = "Product Release n"

    $BosonParams = @{
        "InitLogging"  = $true
        "AppName"      = "Deploying $SolutionName"
        "ModulePath"   = "./PSModules/UseModules.ps1"
        "IsConnected"  = $IsConnected
        "PauseOnError" = $PauseOnError
    }
    . "..\node_modules\elektron-boson\Start-Boson.ps1" @BosonParams

    if (!$IsConnected) {
        $ConnectionParams = @{
            "WebUrl"                = $Url
            "AuthenticationType"    = $AuthType
            "ClientId"              = $PSBoundParameters.ClientID
            "Thumbprint"            = $PSBoundParameters.Thumbprint
            "Account"               = $PSBoundParameters.Account
            "Password"              = $PSBoundParameters.Password
            "ReturnAdminConnection" = $true
        }
        $AdminConnection = Connect-Site @ConnectionParams
    }

    End-Script -SolutionName $SolutionName -DisconnectPnP -ErrorCode 0
}

Contributing

Please refer to the following documentation
repo url

Getting Started

Tools

• Latest current version of NodeJs
• We recommend using Visual Studio Code

Clone/Initialize the Repo

git clone https://2tolead.visualstudio.com/Elektron/_git/Elektron-Boson

Install dependencies

npm install

Build

npm run build

Debugging

To debug this module, run this command from this repo:

npm link

Then run this command from the debugging repo:

npm link elektron-boson

To revert from debugging mode, run the following from this repo:

npm unlink

Then run this command from the debugging repo:

npm unlink elektron-boson

Note: This command will uninstall the elektron-boson dependency from the package.json file