Centralized Remoting Handling

.gitignore

@@ -1,6 +1,5 @@
 
 # ignore the settings folder and files for VSCode and PSS
-.vscode/*
 *.psproj
 *TempPoint*
 

.vscode/admf.code-snippets

@@ -0,0 +1,14 @@
+{
+	"Help_ServerCredential": {
+		"scope": "powershell",
+		"prefix": "helpsc",
+		"body": [
+			".PARAMETER Server",
+			"\tThe server / domain to work with.",
+			"",
+			".PARAMETER Credential",
+			"\tThe credentials to use for this operation."
+		],
+		"description": "[ADMF] Default help for server & credentials"
+	}
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+	"editor.formatOnSave": true
+}

ADMF.Core/ADMF.Core.psd1

@@ -1,32 +1,32 @@
 @{
 	# Script module or binary module file associated with this manifest
-	RootModule = 'ADMF.Core.psm1'
+	RootModule        = 'ADMF.Core.psm1'
 
 	# Version number of this module.
-	ModuleVersion = '1.1.9'
+	ModuleVersion     = '1.2.12'
 
 	# ID used to uniquely identify this module
-	GUID = '11e2d894-33d7-4020-a65e-f13c2f1893aa'
+	GUID              = '11e2d894-33d7-4020-a65e-f13c2f1893aa'
 
 	# Author of this module
-	Author = 'Friedrich Weinmann'
+	Author            = 'Friedrich Weinmann'
 
 	# Company or vendor of this module
-	CompanyName = 'Microsoft'
+	CompanyName       = 'Microsoft'
 
 	# Copyright statement for this module
-	Copyright = 'Copyright (c) 2020 Friedrich Weinmann'
+	Copyright         = 'Copyright (c) 2020 Friedrich Weinmann'
 
 	# Description of the functionality provided by this module
-	Description = 'Central Tooling used across available across all ADMF Project modules'
+	Description       = 'Central Tooling used across available across all ADMF Project modules'
 
 	# Minimum version of the Windows PowerShell engine required by this module
 	PowerShellVersion = '5.0'
 
 	# Modules that must be imported into the global environment prior to importing
 	# this module
-	RequiredModules = @(
-		@{ ModuleName = 'PSFramework'; ModuleVersion = '1.7.270' }
+	RequiredModules   = @(
+		@{ ModuleName = 'PSFramework'; ModuleVersion = '1.13.416' }
 
 		# @{ ModuleName = 'ResolveString'; ModuleVersion = '1.0.0' }
 	)
@@ -38,14 +38,18 @@
 	# TypesToProcess = @('xml\ADMF.Core.Types.ps1xml')
 
 	# Format files (.ps1xml) to be loaded when importing this module
-	FormatsToProcess = @('xml\ADMF.Core.Format.ps1xml')
+	FormatsToProcess  = @('xml\ADMF.Core.Format.ps1xml')
 
 	# Functions to export from this module
 	FunctionsToExport = @(
 		'Clear-AdcConfiguration'
 		'Compare-AdcProperty'
 		'Get-AdcExchangeVersion'
+		'Get-AdcRemotingConfig'
 		'New-AdcChange'
+		'New-AdcPSSession'
+		'Remove-AdcRemotingConfig'
+		'Set-AdcRemotingConfig'
 		'Sync-AdcObject'
 		'Write-AdcChangeLog'
 	)
@@ -66,19 +70,19 @@
 	# FileList = @()
 
 	# Private data to pass to the module specified in ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
-	PrivateData = @{
+	PrivateData       = @{
 
 		#Support for PowerShellGet galleries.
 		PSData = @{
 
 			# Tags applied to this module. These help with module discovery in online galleries.
-			Tags = @('activedirectory', 'configuration', 'admf', 'management')
+			Tags         = @('activedirectory', 'configuration', 'admf', 'management')
 
 			# A URL to the license for this module.
-			LicenseUri = 'https://github.com/ActiveDirectoryManagementFramework/ADMF.Core/blob/master/LICENSE'
+			LicenseUri   = 'https://github.com/ActiveDirectoryManagementFramework/ADMF.Core/blob/master/LICENSE'
 
 			# A URL to the main website for this project.
-			ProjectUri = 'https://admf.one'
+			ProjectUri   = 'https://admf.one'
 
 			# A URL to an icon representing this module.
 			# IconUri = ''

ADMF.Core/changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.2.12 (2025-10-31)
+
+- New: Remoting config handling, to allow specifying the settings used during invocation.
+
 ## 1.1.9 (2023-05-16)
 
 - New: Command Write-AdcChangeLog - Writes a log entry for change objects.
@@ -23,6 +27,4 @@
 
 ## 1.0.0 (2020-09-10)
 
-- New: Some Stuff
-- Upd: Moar Stuff
-- Fix: Much Stuff
+- Initial Release

ADMF.Core/en-us/strings.psd1

@@ -4,6 +4,9 @@
 	'Get-LdapObject.SearchError'             = 'Failed to execute ldap request.' # 
 	'Get-LdapObject.Searchfilter'            = 'Searching with filter: {0}' # $LdapFilter
 	'Get-LdapObject.SearchRoot'              = 'Searching {0} in {1}' # $SearchScope, $searcher.SearchRoot.Path
+
+	'New-AdcPSSession.Connecting'            = 'Connecting via PS Remoting to {0}' # $ComputerName
+	'New-AdcPSSession.Connecting.Config'     = 'Remoting Config used for {0} | Target: {1} | Options: {2} | SSH: {3} | Parameters: {4}' # $ComputerName, $config.Target, $config.HasOptions, $config.UseSSH, @($config.Parameters).Count
 
 	'Sync-AdcObject.ConnectError'            = 'Failed to connect to {0}' # $errorObject.TargetObject
 

ADMF.Core/functions/Remoting/Get-AdcRemotingConfig.ps1

@@ -0,0 +1,31 @@
+function Get-AdcRemotingConfig {
+	<#
+	.SYNOPSIS
+		Retrieve the list of remoting configurations.
+
+	.DESCRIPTION
+		Retrieve the list of remoting configurations.
+		Remoting configurations apply to all remote connections via WinRM or - optionally - SSH.
+		They can be defined for specific servers or all machines in a domain.
+
+		For more details, see Set-AdcRemotingConfig.
+
+	.PARAMETER Target
+		The target the settings apply to.
+		Defaults to: *
+
+	.EXAMPLE
+		PS C:\> Get-AdcRemotingConfig
+
+		Retrieve the list of all remoting configurations.
+	#>
+	[CmdletBinding()]
+	param (
+		[PsfArgumentCompleter('ADMF.Core.RemotingTarget')]
+		[string]
+		$Target = '*'
+	)
+	process {
+		($script:PSRemotingConfig.Values | Where-Object Target -Like $Target)
+	}
+}

ADMF.Core/functions/Remoting/New-AdcPSSession.ps1

@@ -0,0 +1,71 @@
+function New-AdcPSSession {
+	<#
+	.SYNOPSIS
+		Establish a new PowerShell remoting session to the target computer.
+
+	.DESCRIPTION
+		Establish a new PowerShell remoting session to the target computer.
+		Respects the configuration provided via Set-AdcRemotingConfig.
+
+	.PARAMETER ComputerName
+		The computer to connect to.
+		Specify thhe full FQDN.
+
+	.PARAMETER Credential
+		The credentials to use for the connection.
+
+	.EXAMPLE
+		PS C:\> New-AdcPSSession -ComputerName dc1.contoso.com
+
+		Establish a session to dc1.contoso.com using the settings for either dc1.contoso.com or contoso.com
+	#>
+	[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
+	[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSPossibleIncorrectUsageOfAssignmentOperator", "")]
+	[CmdletBinding()]
+	param (
+		[PSFComputer]
+		$ComputerName,
+
+		[PSCredential]
+		$Credential
+	)
+	process {
+		$credParam = @{}
+		if ($Credential) { $credParam.Credential = $Credential }
+
+		$target = "$ComputerName"
+		$config = $null
+		do {
+			if ($config = $script:PSRemotingConfig[$target]) { break }
+			$null, $target = $target -split "\.", 2
+		}
+		while ($target -match '\.')
+
+		if (-not $config) {
+			Invoke-PSFProtectedCommand -ActionString 'New-AdcPSSession.Connecting' -ActionStringValues $ComputerName -ScriptBlock {
+				New-PSSession @credParam -ComputerName $ComputerName -ErrorAction Stop
+			} -Target $ComputerName -EnableException $true -PSCmdlet $PSCmdlet
+			return
+		}
+
+		$param = $config.Parameters | ConvertTo-PSFHashtable -ReferenceCommand New-PSSession
+		if ($config.Options) { $param.SessionOption = $config.Options }
+		if (-not $config.UseSSH) {
+			$param.ComputerName = $ComputerName
+			if ($Credential) { $param.Credential = $Credential }
+		}
+		else {
+			$param.HostName = $ComputerName
+			if ($config.Ssh.UserName) { $param.UserName = $config.Ssh.UserName }
+			if ($config.Ssh.KeyFilePath) { $param.KeyFilePath = $config.Ssh.KeyFilePath }
+			if ($config.Ssh.Subsystem) { $param.Subsystem = $config.Ssh.Subsystem }
+			if ($config.Ssh.Transport) { $param.SSHTransport = $config.Ssh.Transport }
+			if ($config.Ssh.Options.Count -gt 0) { $param.Options = $config.Ssh.Options }
+		}
+
+		Write-PSFMessage -Level Debug -String 'New-AdcPSSession.Connecting.Config' -StringValues $ComputerName, $config.Target, $config.HasOptions, $config.UseSSH, $config.Parameters.Count -Target $ComputerName -Data @{ Config = $config }
+		Invoke-PSFProtectedCommand -ActionString 'New-AdcPSSession.Connecting' -ActionStringValues $ComputerName -ScriptBlock {
+			New-PSSession @param -ErrorAction Stop
+		} -Target $ComputerName -EnableException $true -PSCmdlet $PSCmdlet
+	}
+}

ADMF.Core/functions/Remoting/Remove-AdcRemotingConfig.ps1

@@ -0,0 +1,29 @@
+function Remove-AdcRemotingConfig {
+	<#
+	.SYNOPSIS
+		Removes a powershell remoting configuration.
+
+	.DESCRIPTION
+		Removes a powershell remoting configuration.
+		Use Set-AdcRemotingConfig to define how connections to a target are established when calling New-AdcPSSession.
+
+	.PARAMETER Target
+		The target the configuration applies to.
+
+	.EXAMPLE
+		PS C:\> Remove-AdcRemotingConfig -Target contoso.com
+
+		Removes a powershell remoting configuration targeting contoso.com.
+	#>
+	[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
+	[CmdletBinding()]
+	param (
+		[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
+		[PsfArgumentCompleter('ADMF.Core.RemotingTarget')]
+		[string]
+		$Target
+	)
+	process {
+		$null = $script:PSRemotingConfig.Remove($Target)
+	}
+}