automatedlab/automatedlab.common

PowerShell module for daily administrative tasks and general helper functions

AutomatedLab.Common

This repository collects helper functions from different areas like DSC, Networking, PKI, ... for use in your infrastructure. Our module AutomatedLab heavily relies on these cmdlets as well.

Starting with version 2, AutomatedLab.Common will support PowerShell Core. Please apply common sense and don't expect Windows-only functionality to work in Linux. Otherwise, all cmdlets have been tested in Windows as well as Linux and should work in general.

Status

Our current build status of master and develop:

AppVeyor (master)	AppVeyor (develop)

Common

Our common cmdlets include adding modules, functions and variables to PowerShell sessions, enabling the ?? operator, synchronizing cmdlet parameters and many more.

• Add-AccountPrivilege: Adds extended privileges like e.g. LogonAsService for one or more accounts
• Add-FunctionToPSSession: Adds one or more functions to PowerShell sessions - never change your scripts again
• Add-StringIncrement: Increments a string like "Adapter 1" to "Adapter 2"
• Add-VariableToPSSession: Adds one or more variables to PowerShell sessions - never change your scripts again
• Get-ConsoleText: returns the currently visible console buffer or script file to e.g. copy everything
• Get-FullMesh: Returns a mesh for a given list of items, e.g. to aid with DNS forwarder creation
• Get-StringSection: Dissects a string into sections of a configurable size
• Get-Type: Returns a generic type
• Install-SoftwarePackage: Installs an EXE, MSI or MSU with support for moving the installation to a scheduled task to work with installers communicating to Windows Update
• Invoke-Ternary: the ?? operator implementation
• Send-ModuleToPSSession: Sends one or more modules to remote sessions
• Sync-Parameter: Sync parameters for cmdlets, e.g. to sync PSBoundParameters with a cmdlet that might not take all PSBoundParameters thus throwing an error
• Test-HashtableKeys: Tests a hashtable for the existence of keys
• Test-IsAdministrator: Tests if the current user is administrator

Dsc

Our DSC cmdlets contain functionality related to DSC.

• Get-DscConfigurationImportedResource: Returns a list of imported resources in a given DSC configuration

Networking

Our networking cmdlets contain everything necessary to make network calculations and so on.

• ConvertTo-BinaryIp: Converts a given IP address to binary notation
• ConvertTo-DecimalIp: Converts a given IP address to decimal notation
• ConvertTo-DottedDecimalIp: Converts a given IP address to Dotted Decimal
• ConvertTo-Mask: Converts an integer (0-32) to a dotted subnet mask, e.g. 255.0.0.0
• ConvertTo-MaskLength: Converts a dotted subnet mask to an integer
• Get-BroadCastAddress: Returns the broadcast address of a given network
• Get-NetworkAddress: Returns the network address of a given network
• Get-NetworkRange: Returns the usable range of addresses of a given network
• Get-NetworkSummary: Combines several cmdlets to return a summarized info object for a given IP and net mask
• Get-PublicIpAddress: Returns the public IP address of the lab host
• Test-Port: Tests a TCP or UDP port with configurable timeouts

Active Directory Certificate Services (PKI)

Our PKI cmdlets make configurations, certificate requests and duplicating templates a lot easier.

• Add-CATemplateStandardPermissions: Permits one or more sam accounts to auto-enroll and enroll for certificates
• Add-Certificate2: Import a certificate into a store
• Enable-AutoEnrollment: Leverages Group Policy to configure auto-enrollment
• Find-CertificateAuthority: Leverages the Active Directory to locate a CA
• Get-CaTemplate: Leverages the Active Directory to locate a template provided by the CA
• Get-Certificate2: Finds a certificate in a store
• Get-NextOid: Returns an incremented OID
• New-CaTemplate: Duplicate a template with custom settings
• Publish-CaTemplate: Publish a template
• Request-Certificate: Request a new certificate from the CA
• Test-CaTemplate: Uses certutil to check if a template exists

CI/CD (Team Foundation Server, Azure DevOps (Server))

Our CI/CD cmdlets make interaction with Team Foundation Server starting with 2015 a breeze. Just be sure to select the API version matching your edition of TFS or Azure DevOps.

• Get-TfsAccessTokenString: Get the Authorization header string for your PAT
• Get-TfsAgentPool: Retrieve TFS/Azure DevOps agent pools for an instance
• Get-TfsAgentQueue: Retrieve a TFS/Azure DevOps Project's agent queue
• Get-TfsBuildDefinition: Retrieve a build definition
• Get-TfsBuildDefinitionTemplate: Retrieve the available build templates of a project
• Get-TfsBuildStep: List all possible build steps to use in a build definition
• Get-TfsGitRepository: Get the GIT repo of a project
• Get-TfsProcessTemplate: Get all possible process templates
• Get-TfsProject: Get a list of Projects or an individual project
• Get-TfsReleaseDefinition: Retrieve a release definition
• Get-TfsReleaseStep: Get a list of possible release steps
• New-TfsAgentQueue: Create a new agent queue from a pool of agents
• New-TfsBuildDefinition: Create a new build pipeline
• New-TfsProject: Create a new team project
• New-TfsReleaseDefinition: Create a new release pipeline
• Set-TfsProject: Modify a project configuration

automatedlab.common's Issues

Core build: Output does not contain ApplicationInsights library

Similar to AutomatedLab, the build process will be updated to publish the library project instead of building it in order to package all dependencies contained in Deps.json.

Get-DotNetFrameworkVersion.ps1 script returns incorrect result for build 528040

I believe build 528040 corresponds to .NET Framework 4.8, not 4.7.2 as indicated by this script.
See my comment on this commit.

Send-ModuleToPSSession does not work when target PS version < 5

Send-ModuleToPSSession simply assumes that the module should be stored in a versioned folder in ProgramFiles, which does not work in any PowerShell version < 5. Also, the cmdlet is currently not Linux-compatible.

New-CATemplate EnrollmentFlag NoRevocationInformation missing

Without NoRevocationInformation EnrollmentFlag the cmdlet runs well.
Is it possible to add EnrollmentFlag NoRevocationInformation ?

New-CATemplate : Cannot process argument transformation on parameter 'EnrollmentFlags'. Cannot convert value "IncludeOcspRevNoCheck,NoRevocationInformation,Autoenrollment" to type "Pki.CATemplate.EnrollmentFlags". Error: "Unable to match the identifier
name IncludeOcspRevNoCheck,NoRevocationInformation,Autoenrollment to a valid enumerator name. Specify one of the following enumerator names and try again:
None, IncludeSymmetricAlgorithms, CAManagerApproval, KraPublish, DsPublish, AutoenrollmentCheckDsCert, Autoenrollment, ReenrollExistingCert, RequireUserInteraction, RemoveInvalidFromStore, AllowEnrollOnBehalfOf, IncludeOcspRevNoCheck, ReuseKeyTokenFull,
BasicConstraintsInEndEntityCerts, IgnoreEnrollOnReenrollment, IssuancePoliciesFromRequest"
At line:1 char:204

• ... KeyFlags "$PrivateKeyFlags" -EnrollmentFlags $EnrollmentFlags -ErrorA ...

•                                              ~~~~~~~~~~~~~~~~
  

  • CategoryInfo : InvalidData: (:) [New-CATemplate], ParameterBindingArgumentTransformationException
  • FullyQualifiedErrorId : ParameterArgumentTransformationError,New-CATemplate

Unable to add AutomatedLab.Common.dll

Importing the module does not work. Due to the missing types, deployments are failing when accessing the type [GPO.Helper].

PS C:\> ipmo AutomatedLab.Common
WARNING: Unable to add AutomatedLab.Common.dll - GPO and PKI functionality might be impaired.
Exception was: Cannot bind parameter 'Path' to the target. Exception setting "Path": "Cannot find path 'C:\Program Files\WindowsPowerShell\Modules\AutomatedLab.Common\2.0.129\lib\full\AutomatedLab.Common.dll' becaus
e it does not exist.", 

New-CATemplate

I had an issue with duplicating a template. The solution was to set the parameter EnrollmentFlags to 0.

The suggested values of the parameter EnrollmentFlags are "IncludeSymmetricAlgorithms, CAManagerApproval, KraPublish, DsPublish, AutoenrollmentCheckDsCert, Autoenrollment, ReenrollExistingCert, RequireUserInter
action, RemoveInvalidFromStore, AllowEnrollOnBehalfOf, IncludeOcspRevNoCheck, ReuseKeyTokenFull, BasicConstraintsInEndEntityCerts, IgnoreEnrollOnReenro
llment, IssuancePoliciesFromRequest" but does not include "None".

When the parameter is not set, the command fails.
So maybe for future releases, I suggest to set the EnrollmentFlags to 0 by default.

New-CATemplate -SourceTemplateName "EnrollmentAgentOffline" -TemplateName "BCOEnrollmentAgentOffline2" -DisplayName "BCO Exchange Enrollment Agent (Offline Request)2" -Version 2 -ApplicationPolicy ENROLLMENT_AGENT -PrivateKeyFlags None -EnrollmentFlags 0

I appreciate your module very much btw!

Find-CertificateAuthority does not work in a multi-domain forest

Find-CertificateAuthority looks for the configuration partition using the domain name instead of the forest name.

$cdpContainer = [ADSI]"LDAP://CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainName"

Using the RootDSE object should solve that.

Install-LabSoftwarePackage and an MSI file

Following a successful run of Install-Lab with a single Windows 7 Machine I am getting the following error when trying to install an MSI file:

PS C:\Users\adams\Documents> Install-LabSoftwarePackage -ComputerName OMS -Path $labSources\SoftwarePackages\OemMgmtSetu
p.msi -CommandLine '/qn' -Verbose
VERBOSE: Install-LabSoftwarePackage Entering...
(ComputerName=OMS,Path=D:\LabSources\SoftwarePackages\OemMgmtSetup.msi,CommandLine=/qn,Verbose=True)
VERBOSE: Get-LabVM Entering... (ComputerName=OMS)
13:22:22|22:54:57|00:00:00.000| Installing software package 'D:\LabSources\SoftwarePackages\OemMgmtSetup.msi' on machine
s 'OMS'
VERBOSE: Get-LabVM Entering... (ComputerName=OMS,IncludeLinux=True)
VERBOSE: Get-LabVMStatus...leaving...(Time elapsed: 00:00:00:053)
VERBOSE: Starting background job for 'Installation of 'C:\OemMgmtSetup.msi''
13:22:22|22:54:57|00:00:00.083| - Copying files and initiating setup on 'OMS' and waiting for completionVERBOSE: Invoke-
LabCommand Entering...
(ComputerName=OMS,DependencyFolderPath=D:\LabSources\SoftwarePackages\OemMgmtSetup.msi,DoNotUseCredSsp=<null>,PassThru=
True,ScriptBlock=
        Install-SoftwarePackage @installParams
  ,NoDisplay=True,AsJob=True,ActivityName=Installation of
'C:\OemMgmtSetup.msi',Variable=System.Management.Automation.PSVariable[](1),Function=System.Management.Automation.Funct
ionInfo[](1))
VERBOSE: Executing lab command activity 'Installation of 'C:\OemMgmtSetup.msi'' on machines 'OMS'
VERBOSE: Get-LabVM Entering... (IncludeLinux=True)
VERBOSE: Get-LabVM Entering... (ComputerName=OMS,IncludeLinux=True)
VERBOSE: Get-LabVM Entering... (ComputerName=OMS,IncludeLinux=True)
VERBOSE: Get-LabVMStatus...leaving...(Time elapsed: 00:00:00:031)
VERBOSE: Creating session to computer(s) 'OMS'
VERBOSE: New-LabPSSession Entering...
(ComputerName=OMS,DoNotUseCredSsp=<null>,UseLocalCredential=<null>,Credential=<null>)
VERBOSE: Get-LabVM Entering... (ComputerName=OMS,IncludeLinux=True)
VERBOSE: Connecting to machine 'OMS' using the DNS name 'OMS'
VERBOSE: Creating a new PSSession to machine 'OMS:5985' (UserName='OMS\Administrator', Password='Somepass1',
DoNotUseCredSsp='False')
VERBOSE: Get-LabVM Entering... (ComputerName=OMS)
VERBOSE: Session OMS_535d5d45-da02-43b0-8d2c-3fd94db2b30f is available and will be reused
VERBOSE: New-LabPSSession...leaving - return value is 'Session IDs: 6'...(Time elapsed: 00:00:00:015)
VERBOSE: Adding functions 'Install-SoftwarePackage' to session
You must provide a value expression on the right-hand side of the '-' operator.
    + CategoryInfo          : ParserError: (:) [Set-Item], ParseException
    + FullyQualifiedErrorId : ExpectedValueExpression,Microsoft.PowerShell.Commands.SetItemCommand
    + PSComputerName        : OMS

VERBOSE: Adding variables 'System.Management.Automation.LocalVariable' to session
VERBOSE: Invoke-LWCommand Entering...
(AsJob=True,DependencyFolderPath=D:\LabSources\SoftwarePackages\OemMgmtSetup.msi,ComputerName=OMS,Retries=3,PassThru=Tr
ue,ScriptBlock=
        Install-SoftwarePackage @installParams

,Verbose=True,Session=System.Management.Automation.Runspaces.PSSession[](1),RetryIntervalInSeconds=10,ActivityName=Inst
allation of 'C:\OemMgmtSetup.msi')
VERBOSE: Starting Activity 'Installation of 'C:\OemMgmtSetup.msi''
VERBOSE: Copying files from 'D:\LabSources\SoftwarePackages\OemMgmtSetup.msi' to OMS...
VERBOSE: Finished Installation Activity 'Installation of 'C:\OemMgmtSetup.msi''
VERBOSE: Invoke-LWCommand...leaving...(Time elapsed: 00:00:00:195)
VERBOSE: Invoke-LabCommand...leaving...(Time elapsed: 00:00:00:207)
VERBOSE: Waiting on job ID '332' with name 'Installation of 'C:\OemMgmtSetup.msi''
..
Write-Error : The term 'Install-SoftwarePackage' is not recognized as the name of a cmdlet, function, script file, or
operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try
again.
At C:\Program Files\WindowsPowerShell\Modules\AutomatedLabWorker\5.1.0.115\AutomatedLabWorker.psm1:895 char:17
+                 Write-Error -ErrorRecord $jobError
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Install-SoftwarePackage:String) [Write-Error], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

VERBOSE: Job ID '' with name '' finished
13:22:36|22:55:11|00:00:14.326| - Installation done
VERBOSE: Install-LabSoftwarePackage...leaving...(Time elapsed: 00:00:00:060)

The host is Windows 10 Pro, 1803 PowerShell 5.1.17134.228, AutomatedLab 5.1.0.115

Lab details:

PS C:\Users\adams\Documents> Show-LabDeploymentSummary -Detailed
14:58:32|00:31:07|00:13:04.138| ---------------------------------------------------------------------------
14:58:32|00:31:07|00:13:04.147| Setting up the lab took 0 hour, 31 minutes and 7 seconds
14:58:32|00:31:07|00:13:04.154| Lab name is 'OmsInstallation' and is hosted on 'HyperV'. There are 1 machine(s) and 1 ne
twork(s) defined.
14:58:32|00:31:07|00:13:04.161|
14:58:32|00:31:07|00:13:04.169| ----------------------------- Network Summary -----------------------------
14:58:32|00:31:07|00:13:04.197|
14:58:32|00:31:07|00:13:04.205| Name            AddressSpace    SwitchType AdapterName IssuedIpAddresses
14:58:32|00:31:07|00:13:04.213| ----            ------------    ---------- ----------- -----------------
14:58:32|00:31:07|00:13:04.220| OmsInstallation 192.168.11.0/24   Internal                             1
14:58:32|00:31:07|00:13:04.228|
14:58:32|00:31:07|00:13:04.235|
14:58:32|00:31:07|00:13:04.242| ----------------------------- Domain Summary ------------------------------
14:58:32|00:31:07|00:13:04.253| ------------------------- Virtual Machine Summary -------------------------
14:58:32|00:31:07|00:13:04.285|
14:58:32|00:31:07|00:13:04.292| Name DomainName IpAddress         Roles OperatingSystem        Local Admin   Password
14:58:32|00:31:07|00:13:04.298| ---- ---------- ---------         ----- ---------------        -----------   --------
14:58:32|00:31:07|00:13:04.309| OMS             {192.168.11.0/24} {}    Windows 7 Professional Administrator Somepass1
14:58:32|00:31:07|00:13:04.315|
14:58:32|00:31:07|00:13:04.323|
14:58:32|00:31:07|00:13:04.329| ---------------------------------------------------------------------------
14:58:32|00:31:07|00:13:04.336| Please use the following cmdlets to interact with the machines:
14:58:33|00:31:07|00:13:04.344| - Get-LabVMStatus, Get, Start, Restart, Stop, Wait, Connect, Save-LabVM and Wait-LabVMRe
start (some of them provide a Wait switch)
14:58:33|00:31:07|00:13:04.351| - Invoke-LabCommand, Enter-LabPSSession, Install-LabSoftwarePackage and Install-LabWindo
wsFeature (do not require credentials and
14:58:33|00:31:07|00:13:04.357|   work the same way with Hyper-V and Azure)
14:58:33|00:31:07|00:13:04.363| - Checkpoint-LabVM, Restore-LabVMSnapshot and Get-LabVMSnapshot (only for Hyper-V)
14:58:33|00:31:07|00:13:04.369| - Get-LabInternetFile downloads files from the internet and places them on LabSources (l
ocally or on Azure)
14:58:33|00:31:07|00:13:04.377| ---------------------------------------------------------------------------

Variable name correct?

Is the variable name $requestParameters correct here?

AutomatedLab.Common/AutomatedLab.Common/TeamFoundation/Public/Projects/Get-TfsProcessTemplate.ps1

Line 53 in 962e0aa

$requestParameters.Headers = @{ Authorization = Get-TfsAccessTokenString -PersonalAccessToken $PersonalAccessToken }

WARNING: Module AutomatedLab.Common requires PS Version 5.1

I checked the psd1 - File. It says:
PowerShellVersion = '5.1'
but
CompatiblePSEditions = @('Desktop','Core')

Is it PowerShell 7 compatible?

Remove-RunspacePool sometimes doesn't care

Runspace pool reporting and management needs an update.

Can you support PSRemoting as well as remote registry access in Get-DotNetFrameworkVersion.ps1?

If not, I do it myself here: https://github.com/EliteLoser/DotNetVersionLister ...

Problem when MSI-files have spaces in filename and -CommandLine is used

When using Install-Softwarepackage along with -CommandLine and a space in the filename the script waits forever because the path isnt contained inside ":

AutomatedLab.Common/AutomatedLab.Common/Common/Public/Install-SoftwarePackage.ps1

Line 88 in 3b21eb0

'/I {0} {1}' -f $Path, $CommandLine # Install this MSI

but if -CommandLine is skipped it works as expected:

AutomatedLab.Common/AutomatedLab.Common/Common/Public/Install-SoftwarePackage.ps1

Line 81 in 3b21eb0

"/I `"$Path`"", # Install this MSI

I believe that '/I {0} {1}' should change to '/I "{0}" {1}' but I just started using AutomatedLab and I might have missed something obvious.