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 Environment Variables (set-env-variables)

This task is set to run before the build step on any gulp task. It sets feature flags to enable situationally useful features. These features are added via the command line as parameters when calling your other gulp tasks. Currently we have the following additional features:

Analyze (--analyze)

gulp <TASK> --analyze will run the gulp <TASK> task and enable the analysis features within the webpack. These enable the Bundle Analyzer which outputs a breakdown of the webpacks' components, and the Speed Measure Webpack which gives a time breakdown of the gulp task to identify bottlenecks like below.

 SMP  ⏱
General output time took 48.45 secs

 SMP  ⏱  Plugins
BundleAnalyzerPlugin took 41.8 secs
CopyReleaseAssetsPlugin took 0.099 secs
SetPublicPathPlugin took 0.085 secs
ManifestPlugin took 0.034 secs
AsyncComponentPlugin took 0.002 secs
DefinePlugin took 0 secs
ComponentNamePlugin took 0 secs

 SMP  ⏱  Loaders
modules with no loaders took 5.32 secs
  module count = 3972
css-loader, and
postcss-loader took 3.31 secs
  module count = 29
@microsoft/loader-load-themed-styles, and
css-loader, and
postcss-loader took 0.01 secs
  module count = 29

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