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

Elektron-Boson supports two build toolchains in parallel:

| Toolchain | SPFx version | Entry point | | --------- | ------------ | ------------------ | | Gulp | ≤ 1.21 | gulpfile.js | | Heft | 1.22+ | config/heft.json |

Both toolchains apply the same webpack optimisations (cache, parallelism, source maps, Bundle Analyzer) and expose the same custom flags.

Gulp setup

In gulpfile.js, before build.initialize(gulp):

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

Heft setup

Create two files in the consuming project:

config/heft.json

{
    "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
    "extends": "elektron-boson/config/heft.json"
}

config/webpack-patch.json

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/spfx-build/webpack-patch.schema.json",
    "patchFiles": ["./node_modules/elektron-boson/config/webpack-patch/boson-webpack.js"]
}

Custom flags

--analyze

Enables the Webpack Bundle Analyzer and Speed Measure Plugin. Analysis files are written to /temp/stats.

# Gulp
gulp bundle --analyze

# Heft
heft build --analyze

Output example:

 SMP  ⏱
General output time took 48.45 secs

 SMP  ⏱  Plugins
BundleAnalyzerPlugin took 41.8 secs

 SMP  ⏱  Loaders
modules with no loaders took 5.32 secs
  module count = 3972

--buildnum / set-manifest-version

Stamps a version into config/package-solution.json derived from the CI build number.

Format: {Major}.YYYY.MMDD.{build iteration}

# Gulp
gulp set-manifest-version --buildnum 'CI_master_20190227.2'
# → "version": "1.2019.0227.2"

# Heft (run independently, does not require full build)
heft run --only set-manifest-version -- --buildnum '20190227.2'
# → "version": "1.2019.0227.2"

Note: SharePoint trims leading zeros in the MMDD segment. 0227 displays as 227. A three-digit MMDD is always interpreted as M + DD (e.g. 111 = January 11th).

Optional flags for both toolchains:

| Flag | Description | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | --buildnum VALUE | Required. The CI build number to parse. | | --regexMask VALUE (Gulp) / --regex-mask VALUE (Heft) | Custom regex to extract version segments. Default: ([0-9]{4})([0-9]{2})([0-9]{2}).([0-9]+) | | --format VALUE | Custom version format string. Default: 1.{0}.{1}{2}.{3} |

Webpack optimisations

Applied automatically by both toolchains:

| Setting | Value | | ----------------- | ----------------------------------------------------------- | | cache | true | | parallelism | 100 | | devtool | eval-cheap-module-source-map (dev) / false (production) | | source-map-loader | Scoped to lib/ only | | Bundle Analyzer | Injected when --analyze is passed |

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