Add -PerUser support to Register-ADTDll, Unregister-ADTDll and Invoke-ADTRegSvr32.

Adds a -PerUser switch that performs per-user DLL registration via
regsvr32.exe /n /i:user, calling the DLL's DllInstall entry point so
registration data is written to HKCU instead of HKLM. When invoked
under the SYSTEM account, regsvr32.exe is executed in the context of
the currently logged on user via Start-ADTProcessAsUser so the
registration lands in the correct user hive.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: pl4nty

src/PSAppDeployToolkit/Public/Invoke-ADTRegSvr32.ps1

@@ -19,6 +19,9 @@ function Invoke-ADTRegSvr32
     .PARAMETER Action
         Specify whether to register or unregister the DLL.
 
+    .PARAMETER PerUser
+        Specifies that the DLL should be registered for the current user only by calling its DllInstall entry point with the 'user' argument (regsvr32.exe /n /i:user). If this function is running under the SYSTEM account, regsvr32.exe is executed in the context of the currently logged on user. Note that the DLL must support per-user registration via a DllInstall export for this to work.
+
     .INPUTS
         None
 
@@ -39,6 +42,11 @@ function Invoke-ADTRegSvr32
 
         Unregisters the specified DLL file.
 
+    .EXAMPLE
+        Invoke-ADTRegSvr32 -FilePath "C:\Test\DcTLSFileToDMSComp.dll" -Action 'Register' -PerUser
+
+        Registers the specified DLL file for the currently logged on user only.
+
     .NOTES
         An active ADT session is NOT required to use this function.
 
@@ -72,7 +80,10 @@ function Invoke-ADTRegSvr32
 
         [Parameter(Mandatory = $true)]
         [ValidateSet('Register', 'Unregister')]
-        [System.String]$Action
+        [System.String]$Action,
+
+        [Parameter(Mandatory = $false)]
+        [System.Management.Automation.SwitchParameter]$PerUser
     )
 
     begin
@@ -83,12 +94,12 @@ function Invoke-ADTRegSvr32
         {
             Register
             {
-                "/s `"$FilePath`""
+                "/s$(if ($PerUser) { ' /n /i:user' }) `"$FilePath`""
                 break
             }
             Unregister
             {
-                "/s /u `"$FilePath`""
+                "/s /u$(if ($PerUser) { ' /n /i:user' }) `"$FilePath`""
                 break
             }
         }
@@ -153,8 +164,27 @@ function Invoke-ADTRegSvr32
                     throw (New-ADTErrorRecord @naerParams)
                 }
 
-                # Register the DLL file and measure the success.
-                Start-ADTProcess -FilePath $RegSvr32Path -ArgumentList $ActionParameters -CreateNoWindow -SuccessExitCodes 0
+                # Register the DLL file and measure the success. Per-user registration writes to the
+                # user's HKCU hive, so when running as SYSTEM, execute as the logged on user instead.
+                if ($PerUser -and [PSADT.AccountManagement.AccountUtilities]::CallerSid.IsWellKnown([System.Security.Principal.WellKnownSidType]::LocalSystemSid))
+                {
+                    if (!(Get-ADTClientServerUser))
+                    {
+                        $naerParams = @{
+                            Exception = [System.InvalidOperationException]::new("The DLL file [$FilePath] cannot be $($Action.ToLowerInvariant() + 'ed') per-user as there is no logged on user to process the request against.")
+                            Category = [System.Management.Automation.ErrorCategory]::InvalidOperation
+                            ErrorId = 'NoActiveUserError'
+                            TargetObject = $FilePath
+                            RecommendedAction = "Please ensure a user is logged onto the system and try again."
+                        }
+                        throw (New-ADTErrorRecord @naerParams)
+                    }
+                    Start-ADTProcessAsUser -FilePath $RegSvr32Path -ArgumentList $ActionParameters -CreateNoWindow -SuccessExitCodes 0
+                }
+                else
+                {
+                    Start-ADTProcess -FilePath $RegSvr32Path -ArgumentList $ActionParameters -CreateNoWindow -SuccessExitCodes 0
+                }
             }
             catch
             {

src/PSAppDeployToolkit/Public/Register-ADTDll.ps1

@@ -16,6 +16,9 @@ function Register-ADTDll
     .PARAMETER FilePath
         Path to the DLL file.
 
+    .PARAMETER PerUser
+        Specifies that the DLL should be registered for the current user only by calling its DllInstall entry point with the 'user' argument (regsvr32.exe /n /i:user). If this function is running under the SYSTEM account, regsvr32.exe is executed in the context of the currently logged on user. Note that the DLL must support per-user registration via a DllInstall export for this to work.
+
     .INPUTS
         None
 
@@ -31,6 +34,11 @@ function Register-ADTDll
 
         Registers the specified DLL file.
 
+    .EXAMPLE
+        Register-ADTDll -FilePath "C:\Test\DcTLSFileToDMSComp.dll" -PerUser
+
+        Registers the specified DLL file for the currently logged on user only.
+
     .NOTES
         An active ADT session is NOT required to use this function.
 
@@ -59,7 +67,10 @@ function Register-ADTDll
                 }
                 return ![System.String]::IsNullOrWhiteSpace($_)
             })]
-        [System.String]$FilePath
+        [System.String]$FilePath,
+
+        [Parameter(Mandatory = $false)]
+        [System.Management.Automation.SwitchParameter]$PerUser
     )
 
     begin

src/PSAppDeployToolkit/Public/Unregister-ADTDll.ps1

@@ -16,6 +16,9 @@ function Unregister-ADTDll
     .PARAMETER FilePath
         Path to the DLL file.
 
+    .PARAMETER PerUser
+        Specifies that the DLL should be unregistered for the current user only by calling its DllInstall entry point with the 'user' argument (regsvr32.exe /u /n /i:user). If this function is running under the SYSTEM account, regsvr32.exe is executed in the context of the currently logged on user. Note that the DLL must support per-user registration via a DllInstall export for this to work.
+
     .INPUTS
         None
 
@@ -31,6 +34,11 @@ function Unregister-ADTDll
 
         Unregisters the specified DLL file.
 
+    .EXAMPLE
+        Unregister-ADTDll -FilePath "C:\Test\DcTLSFileToDMSComp.dll" -PerUser
+
+        Unregisters the specified DLL file for the currently logged on user only.
+
     .NOTES
         An active ADT session is NOT required to use this function.
 
@@ -59,7 +67,10 @@ function Unregister-ADTDll
                 }
                 return ![System.String]::IsNullOrWhiteSpace($_)
             })]
-        [System.String]$FilePath
+        [System.String]$FilePath,
+
+        [Parameter(Mandatory = $false)]
+        [System.Management.Automation.SwitchParameter]$PerUser
     )
 
     begin