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.
To install elektron-boson
, run the following command
npm i elektron-boson --save-dev
- latest current version of NodeJs
- We recommend using Visual Studio Code as a lot of settings are pre-configured for it.
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/*/*
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);
The method above will add the following gulp tasks:
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:
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
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}
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.
The configureSPFxBuild()
method also extends the default webpack configuration by adding the Webpack Bundle Analyzer plugin and enabling source maps generation.
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.
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.
Some files in this project may be unclear on how to utilize them and are outlined in Deploy.ps1 Sample
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:
-
[String] $UserName
and[String] $Password
: Used to define the login method used to the SPFx Site- Requires
[Switch] $IsConnected
to be$false
or$null
- Requires
[String] $AuthType
to beUserLogin
- Requires
-
[String] $Thumbprint
and[String] $ClientID
: Used to define the login method used to the SPFx Site- Requires
[Switch] $IsConnected
to be$false
or$null
- Requires
[String] $AuthType
to beAppCertThumbprintClientID
- Requires
-
[String] $SiteType
: Used to define the style of site based on 2toLead site templates, who's values are defined by relative folder names- Equates to a param set like
[ValidateSet('SiteType1',''SiteType2')][String] $SiteType
- Requires
[Switch] $SiteInit
to be enabled - To get a ValidateSet values of
SiteType1
andSiteType2
, you need a folder structure like below:./Sites/SiteType1
./Sites/SiteType2
- Equates to a param set like
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.
[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
}
Please refer to the following documentation
repo url
- Latest current version of NodeJs
- We recommend using Visual Studio Code
git clone https://2tolead.visualstudio.com/Elektron/_git/Elektron-Boson
npm install
npm run build
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