Monthly Archive

Categories

get-computerDN function

Last time I showed a bare bones function for using [adsisearcher] to retrieve the distinguished name of a domain computer.

This is a somewhat expanded version of that function which adds in the sorts of features you’d want for a production ready function.

function get-computerDN {
[CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact="Low")]

param (
[parameter(Position=0,
   Mandatory=$true,
   ValueFromPipeline=$true,
   ValueFromPipelineByPropertyName=$true,
   HelpMessage="Supply computer name" )]
   [Alias("CN", "Computer")] 
   [ValidateNotNullOrEmpty()]
   [string[]]$computername
)
BEGIN{}#begin
PROCESS{

foreach ($computer in $computername) {
if ($psCmdlet.ShouldProcess("$computer", "Retreiving distinguished name")) {
    $filter = “(&(objectCategory=computer)(objectClass=computer)(cn=$computer))”
    ([adsisearcher]$filter).FindOne().Properties.distinguishedname
}
}

}#process
END{}#end

<#
.SYNOPSIS
Returns distinguished name of a computer

.DESCRIPTION
Returns distinguished name of one or more computers in the domain.
Assumes connectivity to domain controller. Domain independent.

.PARAMETER  computername
Name of computer for which distinguished name will be returned

.EXAMPLE
get-computerDN -computername server02

Returns the distinguished name for server02.

Results are of the form:
CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org

.NOTES
[adsisearcher] is a shortcut for System.DirectoryServices.DirectorySearcher

.LINK

#>

}

 

[CmdletBinding()] adds –whatif and other standard parameters. It should be always part of a production script.

 

The param block is expanded to make the parameter mandatory, work with the pipeline and supply a help message if the value isn’t given

 

A couple of aliases for the parameter are defined and the parameter can’t be Null or empty

The parameter also accepts an array of values rather than a single value.

 

The PROCESS block is used for the actual working code. A foreach loop is used to iterate through the computernames and the retrieval of the distinguished name is wrapped in a if statement to allow for –whatif scenarios

 

Finally some help is defined.  I always add help tot he end of function so that its out of the way when I’m working on the code. It spersonal preference. If you want to put your help somewhere else – feel free.

 

Using the function gives you more options:

Simple single computer:£> get-computerDN -computername server02
CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org

 

Whatif:

£> get-computerDN -computername server02 -WhatIf
What if: Performing the operation "Retreiving distinguished name" on target "ser
ver02".

 

multiple machines

£> get-computerDN -computername server02, w12r2sus
CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org
CN=W12R2SUS,OU=Servers,DC=Manticore,DC=org

 

computername as positional parameter

£> get-computerDN server02, w12r2sus
CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org
CN=W12R2SUS,OU=Servers,DC=Manticore,DC=org

 

parameter aliases

£> get-computerDN -computer server02, w12r2sus
CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org
CN=W12R2SUS,OU=Servers,DC=Manticore,DC=org

£> get-computerDN -cn server02, w12r2sus
CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org
CN=W12R2SUS,OU=Servers,DC=Manticore,DC=org

 

Help

£> Get-Help get-computerDN

NAME
    get-computerDN
   
SYNOPSIS
    Returns distinguished name of a computer
   
   
SYNTAX
    get-computerDN [-computername] <String[]> [-WhatIf] [-Confirm]
    [<CommonParameters>]
   
   
DESCRIPTION
    Returns distinguished name of one or more computers in the domain.
    Assumes connectivity to domain controller. Domain independent.
   

RELATED LINKS
   

REMARKS
    To see the examples, type: "get-help get-computerDN -examples".
    For more information, type: "get-help get-computerDN -detailed".
    For technical information, type: "get-help get-computerDN -full".
    For online help, type: "get-help get-computerDN -online"

 

Full help

£> Get-Help get-computerDN -Full

NAME
    get-computerDN
   
SYNOPSIS
    Returns distinguished name of a computer
   
SYNTAX
    get-computerDN [-computername] <String[]> [-WhatIf] [-Confirm]
    [<CommonParameters>]
   
   
DESCRIPTION
    Returns distinguished name of one or more computers in the domain.
    Assumes connectivity to domain controller. Domain independent.
   

PARAMETERS
    -computername <String[]>
        Name of computer for which distinguished name will be returned
       
        Required?                    true
        Position?                    1
        Default value               
        Accept pipeline input?       true (ByValue, ByPropertyName)
        Accept wildcard characters?  false
       
    -WhatIf [<SwitchParameter>]
       
        Required?                    false
        Position?                    named
        Default value               
        Accept pipeline input?       false
        Accept wildcard characters?  false
       
    -Confirm [<SwitchParameter>]
       
        Required?                    false
        Position?                    named
        Default value               
        Accept pipeline input?       false
        Accept wildcard characters?  false
       
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information,
    see
        about_CommonParameters
    (http://go.microsoft.com/fwlink/?LinkID=113216).
   
INPUTS
   
OUTPUTS
   
NOTES
   
   
        [adsisearcher] is a shortcut for
        System.DirectoryServices.DirectorySearcher
   
    -------------------------- EXAMPLE 1 --------------------------
   
    PS C:\>get-computerDN -computername server02
   
   
    Returns the distinguished name for server02.
   
    Results are of the form:
    CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org
   
   
   
   
   
   
RELATED LINKS
   

 

mandatory parameter
£> get-computerDN
cmdlet get-computerDN at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
computername[0]:
get-computerDN : Cannot validate argument on parameter 'computername'. The
argument is null, empty, or an element of the argument collection contains a
null value. Supply a collection that does not contain any null values and then
try the command again.
At line:1 char:1
+ get-computerDN
+ ~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [get-computerDN], ParameterBind
   ingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationError,get-computerDN
 

Help message on mandatory parameter

£> get-computerDN
cmdlet get-computerDN at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
computername[0]: !?
Supply computer name
computername[0]:

 

Pipeline input

£> 'server02', 'w12r2sus' | get-computerDN
CN=SERVER02,OU=Domain Controllers,DC=Manticore,DC=org
CN=W12R2SUS,OU=Servers,DC=Manticore,DC=org

One thing missing is error handling – I’ll cover that next time

Comments are closed.