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

Advertisements
This entry was posted in PowerShell and Active Directory. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s