Update 2024-07-27-PowerShell-Generate-Unique-Upn.md

Author: PsCustomObject

_posts/2024-07-27-PowerShell-Generate-Unique-Upn.md

@@ -111,116 +111,173 @@ This function generates a unique UPN based on given name components and ensures
 ```powershell
 function Get-UniqueUPN
 {
-    [CmdletBinding()]
-    param (
-        [Parameter(Mandatory = $true, ParameterSetName = "ADObject")]
-        [object]$ADObject,
+<#
+    .SYNOPSIS
+        Cmdlet will generate a forest wide unique UPN.
+    
+    .DESCRIPTION
+        Cmdlet will generate a forest wide unique UPN according to generation rules
+        defined by the user.
         
-        [Parameter(Mandatory = $true, ParameterSetName = "Strings")]
-        [string]$FirstName,
+        Cmdlet accept different types of objects to generate the UPN to allow greater flexibility
         
-        [Parameter(Mandatory = $true, ParameterSetName = "Strings")]
+        ADObject - For example and object from Get-AdUser cmdlet
+        Strings - Representing First Name, Last Name etc.
+        DirectoryService Objects - For example when using native .Net methods to retrieve the identity
+    
+    .PARAMETER ADObject
+        An ADObject for example output of the Get-ADUser cmdlet
+    
+    .PARAMETER FirstName
+        A string representing the First Name of the user
+    
+    .PARAMETER LastName
+        A string representing the Last Name of the user
+    
+    .PARAMETER MiddleName
+        A string representing the Middle Name of the user, parameter is optional.
+    
+    .PARAMETER UPNSuffix
+        A string representing the UPN suffix to be used.
+    
+    .PARAMETER FirstNameFormat
+        A string representing the format to be for the First Name part of the UPN.
+    
+    .PARAMETER LastNameFormat
+        A string representing the format to be for the Last Name part of the UPN.
+    
+    .PARAMETER IncludeMiddleName
+        When paramenter is specified user Middle Name, if present, will be included in the UPN generation process.
+    
+    .PARAMETER ADServer
+        A string representing the name of the AD Domain Controller that will be used to query Active Directory.
+    
+        If no server is specified the closest Global Catalog will be automatically selected.
+    
+    .PARAMETER Separator
+        A string representing the separator to be used between UPN parts, defaults to a '.'.
+#>
+    
+    [CmdletBinding(DefaultParameterSetName = 'Strings')]
+    param
+    (
+        [Parameter(ParameterSetName = 'ADObject',
+                   Mandatory = $true)]
+        [object]$ADObject,
+        [Parameter(ParameterSetName = 'Strings',
+                   Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [string]$FirstName,
+        [Parameter(ParameterSetName = 'Strings',
+                   Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [string]$LastName,
-        
-        [Parameter(ParameterSetName = "Strings")]
+        [Parameter(ParameterSetName = 'Strings')]
+        [ValidateNotNullOrEmpty()]
         [string]$MiddleName,
-        
         [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [string]$UPNSuffix,
-        
-        [string]$FirstNameFormat = "Full",
+        [ValidateSet('FullName', 'FirstLetter', IgnoreCase = $true)]
+        [ValidateNotNullOrEmpty()]
+        [string]$FirstNameFormat = 'Full',
+        [ValidateSet('FullName', 'FirstLetter', IgnoreCase = $true)]
+        [ValidateNotNullOrEmpty()]
+        [string]$LastNameFormat = 'FullName',
         [switch]$IncludeMiddleName,
-        [string]$DuplicateSuffix = "Numeric",
-        [string]$CustomDuplicateSuffix,
-        [string]$Server,
-        [string]$Separator = "."
+        [ValidateNotNullOrEmpty()]
+        [string]$ADServer,
+        [ValidateNotNullOrEmpty()]
+        [string]$Separator = '.'
     )
-
-    try
+    
+    if ($PSCmdlet.ParameterSetName -eq 'ADObject')
     {
-        if ($PSCmdlet.ParameterSetName -eq "ADObject")
+        switch ($ADObject.GetType().FullName)
         {
-            Write-Verbose "Processing AD Object"
-            switch ($ADObject.GetType().FullName)
+            'Microsoft.ActiveDirectory.Management.ADUser'
+            {
+                [string]$firstName = $ADObject.GivenName
+                [string]$lastName = $ADObject.Surname
+                [string]$middleName = $ADObject.MiddleName
+                
+                break
+            }
+            'System.DirectoryServices.DirectoryEntry'
+            {
+                [string]$firstName = $ADObject.Properties['givenName'][0]
+                [string]$lastName = $ADObject.Properties['sn'][0]
+                [string]$middleName = $ADObject.Properties['middleName'][0]
+                
+                break
+            }
+            'System.DirectoryServices.SearchResult'
             {
-                "Microsoft.ActiveDirectory.Management.ADUser"
-                {
-                    $firstName = $ADObject.GivenName
-                    $lastName = $ADObject.Surname
-                    $middleName = $ADObject.MiddleName
-                    break
-                }
-                "System.DirectoryServices.DirectoryEntry"
-                {
-                    $firstName = $ADObject.Properties["givenName"][0]
-                    $lastName = $ADObject.Properties["sn"][0]
-                    $middleName = $ADObject.Properties["middleName"][0]
-                    break
-                }
-                "System.DirectoryServices.SearchResult"
-                {
-                    $firstName = $ADObject.Properties["givenName"][0]
-                    $lastName = $ADObject.Properties["sn"][0]
-                    $middleName = $ADObject.Properties["middleName"][0]
-                    break
-                }
-                default
-                {
-                    throw "Unsupported AD object type: $($ADObject.GetType().FullName)"
-                }
+                [string]$firstName = $ADObject.Properties['givenName'][0]
+                [string]$lastName = $ADObject.Properties['sn'][0]
+                [string]$middleName = $ADObject.Properties['middleName'][0]
+                
+                break
+            }
+            default
+            {
+                throw "Unsupported AD object type: $($ADObject.GetType().FullName)"
             }
         }
-        else
+    }
+    else
+    {
+        [string]$firstName = $FirstName
+        [string]$lastName = $LastName
+        [string]$middleName = $MiddleName
+    }
+    
+    # Format first name
+    $firstName = switch ($FirstNameFormat)
+    {
+        'FullName'
         {
-            Write-Verbose "Processing string inputs"
-            $firstName = $FirstName
-            $lastName = $LastName
-            $middleName = $MiddleName
+            $firstName
         }
-
-        Write-Verbose "First Name: $firstName, Last Name: $lastName, Middle Name: $middleName"
-
-        $firstName = switch ($FirstNameFormat)
+        'FirstLetter'
         {
-            "Full" { $firstName }
-            "FirstLetter" { $firstName.Substring(0, 1) }
-            default { $firstName }
+            $firstName.Substring(0, 1)
         }
-
-        $middleNamePart = if ($IncludeMiddleName -and $middleName)
+    }
+    
+    # Format last name
+    $LastName = switch ($FirstNameFormat)
+    {
+        'FullName'
         {
-            "$Separator$middleName"
+            $LastName
         }
-        else { "" }
-
-        $baseUPN = "$firstName$middleNamePart$Separator$lastName@$UPNSuffix".ToLower()
-        Write-Verbose "Base UPN: $baseUPN"
-
-        $uniqueUPN = $baseUPN
-        $counter = 1
-
-        while (Test-UPNExist -UPN $uniqueUPN -Server $Server)
+        'FirstLetter'
         {
-            Write-Verbose "UPN $uniqueUPN already exists, generating alternative"
-            if ($DuplicateSuffix -eq "Numeric")
-            {
-                $uniqueUPN = "{0}{1}@{2}" -f ($baseUPN.Split('@')[0]), $counter, $UPNSuffix
-            }
-            else
-            {
-                $uniqueUPN = "{0}{1}@{2}" -f ($baseUPN.Split('@')[0]), $CustomDuplicateSuffix, $UPNSuffix
-            }
-            $counter++
+            $LastName.Substring(0, 1)
         }
-
-        Write-Verbose "Final Unique UPN: $uniqueUPN"
-        return $uniqueUPN
     }
-    catch
+    
+    # Use middle name
+    [string]$middleNamePart = if ($IncludeMiddleName -and $MiddleName)
+    {
+        '{0}{1}' -f $Separator, $MiddleName
+    }
+    
+    # Setup required attributes
+    [string]$baseUPN = ('{0}{1}{2}{3}@{4}' -f $FirstName, $middleNamePart, $Separator, $LastName, $UPNSuffix).ToLower()
+    [string]$uniqueUPN = $baseUPN
+    [int]$counter = 1
+    
+    while (Test-UPNExist -UPN $uniqueUPN -Server $ADServer)
     {
-        Write-Error "Error generating UPN: $_"
-        throw
+        
+        $uniqueUPN = '{0}{1}@{2}' -f ($baseUPN.Split('@')[0]), $counter, $UPNSuffix
+        
+        $counter++
     }
+    
+    return $uniqueUPN
 }
 ```