Ivor Bright's blog : PowerShell

Create a custom PowerShell cmdlet – End to End

IvorB — Tue, 01 Nov 2011 12:06:20 GMT

This article is focussed on how to create a custom PowerShell cmdlet – the entire process from deciding that you need a new cmdlet, implementing the cmdlet and providing documentation for that cmdlet.

The steps that we will focus on are:

Why you might want to create a cmdlet
Creating the cmdlet
Registering the cmdlet with PowerShell
Additional helpful notes
Documenting the cmdlet.

Why you might want to create a cmdlet

Some of the reasons why you might want to create a custom PowerShell cmdlet include:

No cmdlet currently exists that provides the functionality you require. While there are a wide range of existing cmdlets – they are finite and it would not be unusual if you needed to perform some functionality for which cmdlets did not exist.
cmdlets do exist to perform the functionality that you require, but they are not easy to use or require you to make multiple calls to various cmdlets in sequence. e.g. to add a new user to a domain, you might want to create the user, add them to several default groups, setup their exchange accounts etc. A custom cmdlet could aggregate several existing cmdlets into one easy to use cmdlet like New-Employee.
You want to provide maintenance support to a custom application.

For me, the desire to provide functionality that support people can use to maintain an application is strong. Traditionally this was done by providing a maintenance web application, but there are a few issues with this approach:

Maintenance applications are relative slow to build. You can spend as long on UI elements as providing the functionality, so it is not necessarily a good “fit” when you need to provide maintenance functionality that will only be used by support people.
Maintenance applications are tedious to build. The “CRUD” screens can be very repetitive to build, and are typically left until the end of the project as no one wants to do them.
Support staff frequently want to script this type of work, rather than using UI screens. e.g. if a support person wanted to create 100 employees, they would rather write a batch script to perform the operation, than using a particular UI page 100 times.

Creating the cmdlet

Visual Studio is our friend in this regard and the majority of this article will focus on creating a custom cmdlet. For this example, we are doing to create some cmdlets which perform simple mathematics. We will use Visual Studio 2010 and for the moment – we will use .Net Framework 3.5 rather than .Net Framework 4 (we’ll explain why later). As my VM is 32 bit – I will only be building a 32 bit cmdlet but you need to be aware that you can build either 32 bit or 64 bit. If you build a 64 bit cmdlet – then you need to launch the 64 bit version of PowerShell to use it and similar for the 32 bit.

Initialising the environment

I’m going to assume you have Visual Studio 2010 installed, but there are some initialisation steps that must be performed before you can make a start.

Install Microsoft Windows SDK which can be installed from here.
Ensure PowerShell is set to at least RemoteSigned. By default, Powershell will run with an execution policy of Restricted which means that your scripts won’t execute. Determine your current execution policy by executing Get-ExecutionPolicy in a PowerShell command window. To change your execution policy, use Set-ExecutionPolicy RemoteSigned. There are a number of execution policy options, but RemoteSigned suits our requirements nicely.

Cutting the code

Now that we have our environment setup, we can start cutting some cut.

Create a new Class Library called CustomPowershellCmdlets
1. In project properties, on the application tab – set its target framework to .Net Framework 3.5 (we’ll come back to this in a bit)
2. Add a new class called New_Addition.
3. Add a reference to System.Management.Automation by adding a reference to “C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0\System.Management.Automation.dll.
4. Make this new class inherit from PSCmdlet
5. Add a “using System.Management.Automation” for it to be recognised by Visual Studio.
6. Perform a quick compile to make sure everything is ok.
Add an attribute to the class as follows: [Cmdlet(VerbsCommon.New, “Addition”)]. Our example is a little contrived but this means that the the noun of the operation is “Addition” and the action is “New”. It’s not an exact fit and another good choice would have been “Get”.
Add 2 public properties to the class
1. FirstParameter is of type int
2. SecondParameter is of type int
As our property names are a bit verbose and as it is more usual to deal with X and Y – add an Alas attribute to each and Alias FirstParameter as “X” and Alias SecondParameter as “Y” e.g. “[Alias(“X”)]”
Use the parameter attributes to declare that both properties are mandatory and that the value can be retrieve from the pipeline by property name. e.g. “[Parameter(Mandatory=true, ValueFromPipelineByPropertyName=true)]”
Implement ProcessRecord to perform the addition operation and write the output to the console. e.g. “WriteObject(string.Format("{0} + {1} = {2}", this.FirstParameter, this.SecondParameter, this.FirstParameter + this.SecondParameter));”

Your code should now look like the following:

            1: // -----------------------------------------------------------------------

           2: // <copyright file="New_Addition.cs" company="Charteris">

           3: // Charteris

           4: // </copyright>

           5: // -----------------------------------------------------------------------

           6: namespace CustomPowershellCmdlets

           7: {

           8:     using System;

           9:     using System.Collections.Generic;

          10:     using System.Linq;

          11:     using System.Management.Automation;

          12:     using System.Text;

          13:  

          14:     /// <summary>

          15:     /// Cmdlet which performs an addition

          16:     /// </summary>

          17:     [Cmdlet(VerbsCommon.New, "Addition")]

          18:     public class New_Addition : PSCmdlet

          19:     {

          20:         /// <summary>

          21:         /// Gets or sets the first parameter.

          22:         /// </summary>

          23:         /// <value>

          24:         /// The first parameter.

          25:         /// </value>

          26:         [Alias("X")]

          27:         [Parameter(Mandatory = true, ValueFromPipelineByPropertyName = true)]

          28:         public int FirstParameter { get; set; }

          29:  

          30:         /// <summary>

          31:         /// Gets or sets the second parameter.

          32:         /// </summary>

          33:         /// <value>

          34:         /// The second parameter.

          35:         /// </value>

          36:         [Alias("Y")]

          37:         [Parameter(Mandatory = true, ValueFromPipelineByPropertyName = true)]

          38:         public int SecondParameter { get; set; }

          39:  

          40:         /// <summary>

          41:         /// Processes the record.

          42:         /// </summary>

          43:         protected override void ProcessRecord()

          44:         {

          45:             WriteObject(string.Format(

          46:                 "{0} + {1} = {2}", 

          47:                 this.FirstParameter, 

          48:                 this.SecondParameter, 

          49:                 this.FirstParameter + this.SecondParameter));

          50:         }

          51:     }

          52: }

While this example is quite trivial, you should catch any exceptions and throw a terminating error – this makes sure that PowerShell will stop processing immediately which is probably the desired behaviour.

           1: /// <summary>

           2: /// Processes the record.

           3: /// </summary>

           4: protected override void ProcessRecord()

           5: {

           6:     try

           7:     {

           8:         WriteObject(string.Format(

           9:             "{0} + {1} = {2}",

          10:             this.FirstParameter,

          11:             this.SecondParameter,

          12:             this.FirstParameter + this.SecondParameter));

          13:     }

          14:     catch (Exception ex)

          15:     {

          16:         ErrorRecord errorRecord = new ErrorRecord(ex, string.Empty, ErrorCategory.NotSpecified, this);

          17:         ThrowTerminatingError(errorRecord);

          18:     }

          19: }

Implement similar classes for New_Subtraction, New_Multiplication, New_Division etc.

Registering the cmdlet with PowerShell

Now that we have our basic PowerShell cmdlets, we need to build a snapin so that they can be installed on our system.

Add a class called CustomPowerShellCmdletsInstaller to our project.
Add a reference to System.Configuration.Install.
Make CustomPowerShellCmdletsInstaller inherit from PSSnapIn and add an implementation for the following properties: Description, Name and Vendor
Attribute CustomPowerShellCmdletsInstaller with “[RunInstaller(true)]”.

Your code should now look like the following:

           1: // -----------------------------------------------------------------------

           2: // <copyright file="CustomPowerShellCmdletsInstaller.cs" company="Charteris">

           3: // Charteris.

           4: // </copyright>

           5: // -----------------------------------------------------------------------

           6:  

           7: namespace CustomPowershellCmdlets

           8: {

           9:     using System;

          10:     using System.Collections.Generic;

          11:     using System.ComponentModel;

          12:     using System.Linq;

          13:     using System.Management.Automation;

          14:     using System.Text;

          15:     

          16:     /// <summary>

          17:     /// Installer for Custom Powershell Cmdlets

          18:     /// </summary>

          19:     [RunInstaller(true)]

          20:     public class CustomPowerShellCmdletsInstaller : PSSnapIn

          21:     {

          22:         /// <summary>

          23:         /// Gets the description.

          24:         /// </summary>

          25:         public override string Description

          26:         {

          27:             get 

          28:             { 

          29:                 return "CustomPowerShellCmdlets"; 

          30:             }

          31:         }

          32:  

          33:         /// <summary>

          34:         /// Gets the name.

          35:         /// </summary>

          36:         public override string Name

          37:         {

          38:             get 

          39:             {

          40:                 return "CustomPowerShellCmdlets";

          41:             }

          42:         }

          43:  

          44:         /// <summary>

          45:         /// Gets the vendor.

          46:         /// </summary>

          47:         public override string Vendor

          48:         {

          49:             get 

          50:             {

          51:                 return "Charteris"; 

          52:             }

          53:         }

          54:     }

          55: }

Another quick build to make sure everything works.
Open a Visual Studio 2010 command prompt, browse to your projects bin folder and run InstallUtil on your new dll. e.g. “InstallUtil CustomPowerShellCmdlets.dll” If the first attempt goes wrong and you need to rebuild and reinstall – you should use InstallUtil /u CustomPowerShellCmdlets to uninstall the old version first.
Open a Powershell command window and execute get-pssnapin –registered. This returns a list of all registered but not activated snapins on your machine which should include our new snapin. If you don’t see your new snapin, then the first place to look is the output from your installutil command
To make our new snapin available to use – we need to add it using the following in the PowerShell command window: “Add-PSSnapIn CustomPowerShellCmdlets”
We can now execute out new cmdlets in the same way that we would execute any standard PowerShell cmdlet.
1. As our parameters are set to Mandatory – we can execute New-Addition and we will be prompted for our property values
2. We can also use our aliases and execute “New-Addition –X 5 –Y 7”

Additional Helpful Notes

The Add-PSSnapIn adds the snapin to your current PowerShell session, but if you close and reopen your powershell command window – you need to remember to re-add the snapin. This gets a bit tedious after a while, so it’s useful to make the snapin available to all future PowerShell windows.This can be done by creating a PowerShell profile. In your PowerShell window – find your $Home directory by issuing the command $Home. It’s probably something like C:\Documents and Settings\[user name]. Using that folder as your starting point – create a file called Profile.ps1 under C:\Documents and Settings\[user name]\My Documents\WindowsPowerShell” – you may need to create part of the folder structure and you may have to create the file. Make the contents of the file “Add-PSSnapIn CustomPowerShellCmdlets”. The contents of Profile.ps1 are executed every time a new Powershell command window is open so you can put your initialisation code here.

At the beginning of this tutorial, we set the Target Framework to .Net 3.5. The reason for doing this is that Powershell is expecting us to use this version of the framework and this was the easiest way for us to get up and running. However – it’s always nice to use the latest Framework so edit the following file $pshome\powershell.exe.config (C:\WINDOWS\system32\WindowsPowerShell\v1.0\powershell.exe.config or similar) so that it contains the following:

       1: <?xml version="1.0"?> 

       2: <configuration> 

       3:     <startup useLegacyV2RuntimeActivationPolicy="true"> 

       4:         <supportedRuntime version="v4.0.30319"/> 

       5:         <supportedRuntime version="v2.0.50727"/> 

       6:     </startup> 

       7: </configuration>

See here for more information.

Remember that to switch to using the new version of the snapin, you’ll need to uninstall the old version – rebuild and re-install the new version.

Documenting the Cmdlet

One of the first ever cmdlets you will have ever used is Get-Help. If you try running Get-Help for your new cmdlets – you might be a bit disappointed with the results. It would be nice if we could provide help information which was at least as good as the built in cmdlets and it is possible to do so. In you want to do it by hand – you have to build an xml file to a specific format – but why build something by hand when someone has built an excellent utility for you.

The Cmdlet Help editor can be found here. I won’t provide any details here as its fairly self explanatory, but 1 hint is to deploy the help file to the same folder as your assembly. Calls to Get-Help for your cmdlets should now be a lot more user friendly.

Downloading the code

Hopefully you found this walkthrough useful. The key point is that despite this example being trivial – you can create a cmdlet using anything that is available in the .Net Framework. The code used in this tutorial (targeting .Net Framework 3.5) can be found here.

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Use PowerShell to synchronise Active Directory users to a contact list – Using Contact Photos

IvorB — Thu, 06 Jan 2011 14:55:10 GMT

This is the fifth article in a series of posts looking at using PowerShell to synchronise Active Directory users with Exchange contacts. Previous articles looked at why we might do this, how we can access active directory, how we might access Exchange contacts and how we can use Checksums to detect changes in Active Directory.

This article will focus on storing photos against our Exchange contacts. Before we begin with any implementation details, its useful to consider why we might want to store contact photos:

Better experience when receiving phone calls. Most modern phones will display the photo for incoming calls so you get a better experience when receiving calls. You might recognise the person’s face but not their name, so its helps in the decision about accepting/rejecting an incoming call.
Better experience making a phone call. As above – you might not know the name of the person you want to call but you might recognise their face. Storing the photos helps the user choose the correct person to phone.
The photos are often stored in Active Directory anyway in the thumbnail photo attribute (see here for details). Since we may already have the photo, it makes sense to reuse it.

The implementation details are based upon the scripts in previous article in this series but will be reproduced with the various tweaks here.

To get a specific user from active directory, we can use the following function:

        1: # Get User Details

       2: Function Get-ActiveDirectoryUser

       3: {    

       4:     param ([string]$firstName, [string]$lastName) 

       5:     

       6:     $root = [ADSI]''

       7:     $searcher = new-object     System.DirectoryServices.DirectorySearcher($root)

       8:     $searcher.filter = "(&(objectClass=user)(givenName=$firstName)(sn=$lastName))"

       9:     

    $users = $searcher.Findall()

    

    if ($users.Count -eq 1)

    {

        $user = $users[0]

        $properties = $user.Properties

        $thumbnailPhoto = $user.Properties["thumbnailphoto"]

        

        if ($thumbnailPhoto -eq $null)

        {

            Write-Host "User has no photo"

        }

        else

        {

            Write-Host "User has photo"

        }

        

        return $user

    }

    else

    {

        Write-Host "failed to find match"

        return $null

    }   

}

To connect to Exchange EWS and to check to see if the contact already exists are identical to previous function implementations used:

       1: # Connect to Exchange EWS

       2: function Connect-ExchangeEWS

       3: { 

       4:     $EwsApi = "C:\Program Files\Microsoft\Exchange\Web Services\1.0\" + 

       5:         "Microsoft.Exchange.WebServices.dll"

       6:     [void][Reflection.Assembly]::LoadFile($EwsApi) 

       7:     

       8:     # Avoid hardcoding email address

       9:     $windowsIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent()

    $windowsQuery = "LDAP://<SID=" + $windowsIdentity.user.Value.ToString() + ">"

    $windowsUser = [ADSI]$windowsQuery

        

    # Use the discovered email address to discover the exchange url    

    $exchangeService = new-object Microsoft.Exchange.WebServices.Data.ExchangeService(

        [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1)

    $exchangeService.AutodiscoverUrl($windowsUser.mail.ToString())

    

    return $exchangeService

}

  

  

# Check if an exchange contact exists.

function Check-ExchangeContactExists

{ 

    param ($exchangeService, [string]$firstName, [string]$lastName) 

    

    # Used to return the contact Id if the contract exists.

    $Id = $null

    

    $viewer =  New-Object Microsoft.Exchange.WebServices.Data.ItemView(300)    

    $ContactsFolder=[Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService, 

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts)

  

    $searchFilterFirstName = New-Object `

        Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(

        [Microsoft.Exchange.WebServices.Data.ContactSchema]::GivenName,$firstName)

    $searchFilterLastName = New-Object `

        Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(

        [Microsoft.Exchange.WebServices.Data.ContactSchema]::Surname,$lastName)

    $searchFilters = New-Object `

        Microsoft.Exchange.WebServices.Data.SearchFilter+SearchFilterCollection(

        [Microsoft.Exchange.WebServices.Data.LogicalOperator]::And);

    $searchFilters.add($searchFilterFirstName)

    $searchFilters.add($searchFilterLastName)

  

    # Search for matching contacts.

    $searchResults = $exchangeService.FindItems(

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts, 

        $searchFilters, $viewer)

    

    # If we have results - then the contact already exists

    foreach($searchResult in $searchResults)

    {

        # Remember the Id as this makes deleting easier

        $Id = $searchResult.Id

    }

    

    return $Id

}

Creating a contact is very similar to a previous implementation, but it has an additional thumbnailPhoto parameter and needs an additional call to SetContactPicture():

       1: # Create an Exchange contact

       2: function Create-ExchangeContact

       3: { 

       4:     param ($exchangeService, [string]$firstName, [string]$lastName, 

       5:         [string]$mobileNumber, $thumbnailPhoto) 

       6:  

       7:     $enumPhoneMobileValue = 

       8:         [Microsoft.Exchange.WebServices.Data.PhoneNumberKey]::MobilePhone

       9:  

      10:     # Create the new contact and populate properties

      11:     $newContact = 

      12:         New-Object Microsoft.Exchange.WebServices.Data.Contact($exchangeService) 

      13:     $newContact.GivenName = $firstName

      14:     $newContact.Surname = $lastName

      15:     $newContact.PhoneNumbers[$enumPhoneMobileValue] = $mobileNumber

      16:     

      17:     $newContact.SetContactPicture($thumbnailPhoto)

      18:     

      19:     [void]$newContact.Save()

      20: }

Updating a contact is very similar to a previous implementation but it has an additional thumbnailPhoto parameter, and needs to manage updating the photo by removing the old one and adding the new one.

       1: # Updates an Exchange contact

       2: function Update-ExchangeContact

       3: { 

       4:     param ($exchangeService, $Id, [string]$mobileNumber, $thumbnailPhoto) 

       5:  

       6:     $enumPhoneMobileValue = 

       7:         [Microsoft.Exchange.WebServices.Data.PhoneNumberKey]::MobilePhone

       8:     $enumAlwaysOverWrite = 

       9:         [Microsoft.Exchange.WebServices.Data.ConflictResolutionMode]::AlwaysOverWrite

    # http://msdn.microsoft.com/en-us/library/gg274394(v=exchg.80).aspx        

    $extendedPropertyMobileTelephoneNumber = 14876

     

    # load the current contact

    $contactToUpdate = 

        [Microsoft.Exchange.WebServices.Data.Contact]::Bind($exchangeService,$Id)

    

    # Set the phone number

    $contactToUpdate.PhoneNumbers[$enumPhoneMobileValue] = $mobileNumber

    [Void]$contactToUpdate.SetExtendedProperty( 

        (new-object Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(

            $extendedPropertyMobileTelephoneNumber,

            [Microsoft.Exchange.WebServices.Data.MapiPropertyType]::String) ), 

            $mobileNumber )

    

    # Need to remove the old photo if it has one, before setting the new one.        

    if ($contactToUpdate.HasPicture)

    {

        $contactToUpdate.RemoveContactPicture()

        [void]$contactToUpdate.Update($enumAlwaysOverWrite)

    }

  

    $contactToUpdate.SetContactPicture($thumbnailPhoto)

    

    [void]$contactToUpdate.Update($enumAlwaysOverWrite)

}

The main bootstrap function is as follows:

       1: # Main bootstrap

       2: Function Run-Main

       3: {    

       4:     $firstName = "Donald"

       5:     $lastName = "Duck"

       6:         

       7:     Clear-Host

       8:     $user = Get-ActiveDirectoryUser $firstName $lastName

       9:     $mobile = $user.Properties["mobile"]

    $thumbnailPhoto = $user.Properties["thumbnailphoto"][0]

    

    $exchangeService = Connect-ExchangeEWS

    $Id = Check-ExchangeContactExists $exchangeService $firstName $lastName

    

    if ($Id -eq $null)

    {

        Write-Host "Creating Exchange Contact"

                       

        Create-ExchangeContact `

            $exchangeService $firstName $lastName $mobile $thumbnailPhoto

        

        Write-Host "Exchange Contact created"

    }

    else

    {

        Write-Host "Updating Exchange Contact"

        

        Update-ExchangeContact $exchangeService $Id $mobile $thumbnailPhoto

        

        Write-Host "Exchange Contact updated"

    }

    

    Write-Host "Finished"

}

Adding the photo functionality doesn’t require much additional coding, but your end users will really appreciate the extra effort.

This ends this series of articles on using PowerShell to synchronise Active Directory with Exchange contacts – hopefully you found it interesting and informative!

Technorati Tags: PowerShell,EWS,Active Directory

Del.icio.us Digg It Share on Facebook Stumble It!

Use PowerShell to synchronise Active Directory users to a contact list – Using Checksums

IvorB — Wed, 05 Jan 2011 17:14:02 GMT

This is the fourth article in a series of posts looking at using PowerShell to synchronise Active Directory users with Exchange contacts. Previous articles looked at why we might do this, how we can access active directory and how we might access Exchange contacts. This article will focus on detecting changes to Active Directory users so that we can detect which Exchange contacts need to be updated.

When looking at a method of detecting changes in Active Directory, I initially looked at the “When-Changed” Active Directory attribute. This appeared to satisfy my requirement with the description of the attribute being:

“The date when this object was last changed. This value is not replicated and exists in the global catalog”.

However – I got a large number of false positives and I believe the cause is related to another attribute called “Last-Logon”:

“(The last time the user logged on. This value is stored as a large integer that represents the number of 100 nanosecond intervals since January 1, 1601 (UTC). A value of zero means that the last logon time is unknown).”

It seems that each time a user logs into the domain – it is considered a change to their account which alters the “When-Changed” attribute and as a result – the attribute is of limited use to detecting “real” active directory changes. To be honest – we probably need something more granular as we are only interested in a small subset of Active Directory fields and we only want to consider updating a contact when one of these fields change.

A better approach seems to be to generate a checksum when the initial exchange contact is created and store with the contact (in an unused field for example). Then – on subsequent passes the logic can be something like the following:

The process of generating a checksum using PowerShell is relatively painless as it is easy to generate both SHA1 and MD5 hashes. In this example – I am going to generate a MD5 hash for the firstName, lastName and mobile phone number combination. This example is slightly trivial as for such a small subset of fields – we could simply compare all the field values. However – for a real implementation, we are likely to be concerned with many more fields and the hash/checksum seems an appropriate solution:

        1: # Generates a checksum for the passed parameters

       2: function Generate-CheckSum([string[]]$fields)

       3: {

       4:     [string]$totalSource = ""

       5:     [string]$checksum = ""

       6:     

       7:     # Join all the parameters, ready for hashing

       8:     foreach($field in $fields)

       9:     {

        $totalSource += $field

    }

    

    # Generate an MD5 hash

    $cryptoServiceProvider = [System.Security.Cryptography.MD5CryptoServiceProvider];

    $hashAlgorithm = new-object $cryptoServiceProvider

    $hashByteArray = $hashAlgorithm.ComputeHash([Char[]]$totalSource);

  

    # Convert the hash to something easy to read

    foreach ($byte in $hashByteArray) 

    { 

        $checkSum += “{0:X2}” -f $byte

    }

  

    return $checkSum

}

  

# Main bootstrap function

function Run-Main

{

    $firstName = "Donald"

    $lastName = "Duck"

    $mobileNumber = "12345"

    

    $reverseMobileNumber = "54321"

    $firstNameLowerCase = "donald"

    

    Clear-Host

    

    $checksum = Generate-CheckSum($firstName, $lastName, $mobileNumber)

    Write-Host "Checksum for" $firstName $lastName $mobileNumber : $checksum

    

    $checksum = Generate-CheckSum($firstName, $lastName, $reverseMobileNumber)

    Write-Host "Checksum for" $firstName $lastName $reverseMobileNumber : $checksum

    

    $checksum = Generate-CheckSum($firstNameLowerCase, $lastName, $mobileNumber)

    Write-Host "Checksum for" $firstNameLowerCase $lastName $mobileNumber : $checksum   

}

  

Run-Main

The output from this is:

This demonstrates that the hash is dependent on the content provided to it and is case sensitive. As content is changed in Active Directory, the checksum generated will vary and can be detected by stashing the previous checksum with the contact in Exchange. This allows a simple mechanism for detecting changes in Active Directory so only users with changed values need to be synchronised to contacts in Exchange.

A future article in this series will look at storing photos with the contact in Exchange.

Technorati Tags: PowerShell,Active Directory

Del.icio.us Digg It Share on Facebook Stumble It!

Use PowerShell to synchronise Active Directory users to a contact list – Accessing Exchange Contacts

IvorB — Wed, 05 Jan 2011 14:04:52 GMT

This is the third article in a series of posts looking at using PowerShell to synchronise Active Directory users with exchange contacts. Previous articles looked at why we might want to do this, and how we can access active directory. This article will focus on using PowerShell to access and create/update exchange contacts.

I am going to focus on accessing Exchange using Exchange Web Services (EWS) and documentation can be found here. My main goal is to be able to access contact lists for all users in the organisation rather than just my own, so EWS provides an ideal approach. You need the following on your client before we begin our PowerShell development:

The latest EWS Managed API from here
.Net 3.5 installed

The first step is to simply search for contacts for the active user. Some basic results can be found as follows:

        1: # Use EWS to list all exchange contacts

       2: function List-ExchangeContacts

       3: { 

       4:     $EwsApi = "C:\Program Files\Microsoft\Exchange\Web Services\1.0\" + 

       5:         "Microsoft.Exchange.WebServices.dll"

       6:     [void][Reflection.Assembly]::LoadFile($EwsApi) 

       7:     

       8:     # Avoid hardcoding email address

       9:     $windowsIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent()

    $windowsQuery = "LDAP://<SID=" + $windowsIdentity.user.Value.ToString() + ">"

    $windowsUser = [ADSI]$windowsQuery

        

    # Use the discovered email address to discover the exchange url    

    $exchangeService = new-object Microsoft.Exchange.WebServices.Data.ExchangeService(

        [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1)

    $exchangeService.AutodiscoverUrl($windowsUser.mail.ToString())

  

    # Create a view for browsing the results.

    $viewer =  New-Object Microsoft.Exchange.WebServices.Data.ItemView(1000)    

  

    # Access the contacts folder

    [void][Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService, 

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts)

    $exchangeContacts = $exchangeService.FindItems(

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts, $viewer)

  

    # Iterate over the contacts and write to output

    foreach($exchangeContact in $exchangeContacts)

    { 

        Write-Host ($exchangeContact.GivenName + " " + $exchangeContact.Surname)

    }

}

  

Clear-Host

List-ExchangeContacts

As our main goal is related to phone numbers, we should display them as well. The phone numbers are contained in a dictionary and for this example – we will look at the mobile number. The List-ExchangeContacts function becomes:

       1: # Use EWS to list all exchange contacts

       2: function List-ExchangeContacts

       3: { 

       4:     $enumPhoneMobileValue = 

       5:         [Microsoft.Exchange.WebServices.Data.PhoneNumberKey]::MobilePhone

       6:  

       7:     $EwsApi = "C:\Program Files\Microsoft\Exchange\Web Services\1.0\" + 

       8:         "Microsoft.Exchange.WebServices.dll"

       9:     [void][Reflection.Assembly]::LoadFile($EwsApi) 

    

    # Avoid hardcoding email address

    $windowsIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent()

    $windowsQuery = "LDAP://<SID=" + $windowsIdentity.user.Value.ToString() + ">"

    $windowsUser = [ADSI]$windowsQuery

        

    # Use the discovered email address to discover the exchange url    

    $exchangeService = new-object Microsoft.Exchange.WebServices.Data.ExchangeService(

        [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1)

    $exchangeService.AutodiscoverUrl($windowsUser.mail.ToString())

  

    # Create a view for browsing the results.

    $viewer =  New-Object Microsoft.Exchange.WebServices.Data.ItemView(1000)    

  

    # Access the contacts folder

    [void][Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService, 

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts)

    $exchangeContacts = $exchangeService.FindItems(

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts, $viewer)

  

    # Iterate over the contacts and write to output

    foreach($exchangeContact in $exchangeContacts)

    { 

        Write-Host ($exchangeContact.GivenName + " " + $exchangeContact.Surname)

        Write-Host (" - Mobile: " + $exchangeContact.PhoneNumbers[$enumPhoneMobileValue])

    }

}

  

Clear-Host

List-ExchangeContacts

Details about other properties in the contact object can be found here.

Now that we can retrieve our exchange contacts, it’s time to create new ones:

       1: # Create an Exchange contact

       2: function Create-ExchangeContact

       3: { 

       4:     param ([string]$firstName, [string]$lastName, [string]$mobileNumber) 

       5:  

       6:     $enumPhoneMobileValue = 

       7:         [Microsoft.Exchange.WebServices.Data.PhoneNumberKey]::MobilePhone

       8:  

       9:     $EwsApi = "C:\Program Files\Microsoft\Exchange\Web Services\1.0\" + 

        "Microsoft.Exchange.WebServices.dll"

    [void][Reflection.Assembly]::LoadFile($EwsApi) 

    

    # Avoid hardcoding email address

    $windowsIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent()

    $windowsQuery = "LDAP://<SID=" + $windowsIdentity.user.Value.ToString() + ">"

    $windowsUser = [ADSI]$windowsQuery

        

    # Use the discovered email address to discover the exchange url    

    $exchangeService = new-object Microsoft.Exchange.WebServices.Data.ExchangeService(

        [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1)

    $exchangeService.AutodiscoverUrl($windowsUser.mail.ToString())

  

    # Create the new contact and populate properties

    $newContact = 

        New-Object Microsoft.Exchange.WebServices.Data.Contact($exchangeService) 

    $newContact.GivenName = $firstName

    $newContact.Surname = $lastName

    $newContact.PhoneNumbers[$enumPhoneMobileValue] = $mobileNumber

    

    [void]$newContact.Save()

    

    Write-Host ("Contact '" + $firstName + " " + $lastName + "' created")

}

  

Clear-Host

Create-ExchangeContact "Donald" "Duck" "12345"

Write-Host "Finished"

However – if you run this multiple times, the same contact will be created multiple times. We need a check function to ensure we don’t create duplicate contacts, and we’ll do a bit of refactoring to add structure at the same time:

       1: # Connect to exchange EWS

       2: function Connect-ExchangeEWS

       3: { 

       4:     $EwsApi = "C:\Program Files\Microsoft\Exchange\Web Services\1.0\" + 

       5:         "Microsoft.Exchange.WebServices.dll"

       6:     [void][Reflection.Assembly]::LoadFile($EwsApi) 

       7:     

       8:     # Avoid hardcoding email address

       9:     $windowsIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent()

    $windowsQuery = "LDAP://<SID=" + $windowsIdentity.user.Value.ToString() + ">"

    $windowsUser = [ADSI]$windowsQuery

        

    # Use the discovered email address to discover the exchange url    

    $exchangeService = new-object Microsoft.Exchange.WebServices.Data.ExchangeService(

        [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1)

    $exchangeService.AutodiscoverUrl($windowsUser.mail.ToString())

    

    return $exchangeService

}

  

  

# Check if an exchange contact exists.

function Check-ExchangeContactExists

{ 

    param ($exchangeService, [string]$firstName, [string]$lastName) 

    

    $viewer =  New-Object Microsoft.Exchange.WebServices.Data.ItemView(300)    

    $ContactsFolder=[Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService,

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts)

  

    $searchFilterFirstName = 

        New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(

        [Microsoft.Exchange.WebServices.Data.ContactSchema]::GivenName,$firstName)

    $searchFilterLastName = 

        New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(

        [Microsoft.Exchange.WebServices.Data.ContactSchema]::Surname,$lastName)

    $searchFilters = New-Object `

        Microsoft.Exchange.WebServices.Data.SearchFilter+SearchFilterCollection(

        [Microsoft.Exchange.WebServices.Data.LogicalOperator]::And);

    $searchFilters.add($searchFilterFirstName)

    $searchFilters.add($searchFilterLastName)

  

    # Search for matching contacts.

    $searchResults = $exchangeService.FindItems(

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts,

        $searchFilters, $viewer)

    $match = $false

    

    # If we have results - then the contact already exists

    foreach($searchResult in $searchResults)

    {

        $match = $true

    }

    

    return $match

}

  

# Create an Exchange contact

function Create-ExchangeContact

{ 

    param ($exchangeService, [string]$firstName, [string]$lastName, 

        [string]$mobileNumber) 

 

    $enumPhoneMobileValue = 

        [Microsoft.Exchange.WebServices.Data.PhoneNumberKey]::MobilePhone

 

    # Create the new contact and populate properties

    $newContact = 

        New-Object Microsoft.Exchange.WebServices.Data.Contact($exchangeService) 

    $newContact.GivenName = $firstName

    $newContact.Surname = $lastName

    $newContact.PhoneNumbers[$enumPhoneMobileValue] = $mobileNumber

    

    [void]$newContact.Save()

}

  

# The main boot strap

function Run-Main

{

    $firstName = "Donald"

    $lastName = "Duck"

    $mobileNumber = "12345"

    

    Clear-Host

    

    # Connect to exchange EWS

    $exchangeService = Connect-ExchangeEWS

    

    # Check if the contact already exists

    $result = Check-ExchangeContactExists $exchangeService $firstName $lastName

  

    if ($result -eq $true)

    {

        # Already exists, so don't create

        Write-Host ("Contact '" + $firstName + " " + $lastName  + "' already exists")

    }

    else

    {

        # Does not exist, so create.

        Create-ExchangeContact $exchangeService $firstName $lastName $mobileNumber

        Write-Host ("Contact '" + $firstName + " " + $lastName  + "' created")

    }

  

    Write-Host "Finished"

}

  

Run-Main

Now we can create contacts, the next step is to provide delete functionality. We do a minor tweak to Check-ExchangeContactExists() so it returns the Id of the contact if it exists, and $null if the contact does not exist. This Id can then be used to delete the contact. The changed portions are below:

       1: # Check if an exchange contact exists.

       2: function Check-ExchangeContactExists

       3: { 

       4:     param ($exchangeService, [string]$firstName, [string]$lastName) 

       5:     

       6:     # Used to return the contact Id if the contract exists.

       7:     $Id = $null

       8:     

       9:     $viewer =  New-Object Microsoft.Exchange.WebServices.Data.ItemView(300)    

    $ContactsFolder=[Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService,

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts)

  

    $searchFilterFirstName = New-Object `

        Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(

        [Microsoft.Exchange.WebServices.Data.ContactSchema]::GivenName,$firstName)

    $searchFilterLastName = New-Object `

        Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(

        [Microsoft.Exchange.WebServices.Data.ContactSchema]::Surname,$lastName)

    $searchFilters = New-Object `

        Microsoft.Exchange.WebServices.Data.SearchFilter+SearchFilterCollection(

        [Microsoft.Exchange.WebServices.Data.LogicalOperator]::And);

    $searchFilters.add($searchFilterFirstName)

    $searchFilters.add($searchFilterLastName)

  

    # Search for matching contacts.

    $searchResults = $exchangeService.FindItems(

        [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Contacts, 

        $searchFilters, $viewer)

    

    # If we have results - then the contact already exists

    foreach($searchResult in $searchResults)

    {

        # Remember the Id as this makes deleting easier

        $Id = $searchResult.Id

    }

    

    return $Id

}

  

# Delete an Exchange contact

function Delete-ExchangeContact

{ 

    param ($exchangeService, $Id) 

 

    $enumDeleteMode = 

        [Microsoft.Exchange.WebServices.Data.DeleteMode]::MoveToDeletedItems

        

    $contactToDelete = [Microsoft.Exchange.WebServices.Data.Contact]::Bind(

        $exchangeService,$Id)

    [void]$contactToDelete.Delete($enumDeleteMode)

}

  

# The main boot strap

function Run-Main

{

    $firstName = "Donald"

    $lastName = "Duck"

    

    Clear-Host

    

    # Connect to exchange EWS

    $exchangeService = Connect-ExchangeEWS

    

    # Check if the contact already exists

    $Id = Check-ExchangeContactExists $exchangeService $firstName $lastName

  

    if ($Id -eq $null)

    {

        # Does not exist, so no need to delete

        Write-Host ("Contact '" + $firstName + " " + $lastName  + "' does not exist")

    }

    else

    {

        # Already exists, so delete the contact

        Delete-ExchangeContact $exchangeService $Id

        Write-Host ("Contact '" + $firstName + " " + $lastName  + "' deleted")   

    }

  

    Write-Host "Finished"

}

We may as well provide an update method to complete the CRUD operations. A future article will use a checksum to detect when a contact needs updating, but the implementation here will be as simple as possible:

       1: # Update an Exchange contact

       2: function Update-ExchangeContact

       3: { 

       4:     param ($exchangeService, $Id, [string]$mobileNumber) 

       5:  

       6:     $enumPhoneMobileValue = 

       7:         [Microsoft.Exchange.WebServices.Data.PhoneNumberKey]::MobilePhone

       8:     $enumAlwaysOverWrite = 

       9:         [Microsoft.Exchange.WebServices.Data.ConflictResolutionMode]::AlwaysOverWrite

      10:         

      11:     # http://msdn.microsoft.com/en-us/library/gg274394(v=exchg.80).aspx        

      12:     $extendedPropertyMobileTelephoneNumber = 14876

      13:  

      14:     # load the current contact

      15:     $contactToUpdate = 

      16:         [Microsoft.Exchange.WebServices.Data.Contact]::Bind($exchangeService,$Id)

      17:         

      18:     # set the new values

      19:     $contactToUpdate.PhoneNumbers[$enumPhoneMobileValue] = $mobileNumber

      20:     [Void]$contactToUpdate.SetExtendedProperty( 

      21:         (new-object Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(

      22:             $extendedPropertyMobileTelephoneNumber,

      23:             [Microsoft.Exchange.WebServices.Data.MapiPropertyType]::String) ), 

      24:             $mobileNumber )

      25:     

      26:     [void]$contactToUpdate.Update($enumAlwaysOverWrite)

      27: }

Note: There is a “Gotcha” here related to updating the mobile telephone number. As it is an extended property, you have to make a call to SetExtendedProperty. The list of the Extended Properties and the corresponding ids can be found here.

All the operations so far will be performed for the active user. If you want to adjust contacts for other users in your organisation – you need to “impersonate” them. While this might sound dangerous if anyone was allowed to adjust contact details for others, it is perfectly safe as the ability to “impersonate” is controlled by permissions. You can find further information about Exchange Impersonation here.

The ImpersonatedUserId needs to be set on the ExchangeService before making a call, so a new sample Connect method that supports impersonation looks like:

       1: # Connect to exchange EWS with impersonation

       2: function Connect-ExchangeEWS

       3: { 

       4:     param ([string]$emailAddressToImpersonate) 

       5:     

       6:     $enumSmtpAddress = 

       7:         [Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress   

       8:     

       9:     $EwsApi = "C:\Program Files\Microsoft\Exchange\Web Services\1.0\" + 

      10:         "Microsoft.Exchange.WebServices.dll"

      11:     [void][Reflection.Assembly]::LoadFile($EwsApi) 

      12:     

      13:     # Avoid hardcoding email address

      14:     $windowsIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent()

      15:     $windowsQuery = "LDAP://<SID=" + $windowsIdentity.user.Value.ToString() + ">"

      16:     $windowsUser = [ADSI]$windowsQuery

      17:         

      18:     # Use the discovered email address to discover the exchange url    

      19:     $exchangeService = new-object Microsoft.Exchange.WebServices.Data.ExchangeService(

      20:         [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1)

      21:     $exchangeService.AutodiscoverUrl($windowsUser.mail.ToString())

      22:     

      23:     # Impersonate the desired exchange user

      24:     $exchangeService.ImpersonatedUserId = 

      25:         New-Object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId(

      26:             $enumSmtpAddress,$emailAddressToImpersonate)

      27:     

      28:     return $exchangeService

      29: }

Future article in this series will look at using Checksums to detect when Contacts need to be updated, and storing photos for contacts.

Technorati Tags: PowerShell,EWS

Del.icio.us Digg It Share on Facebook Stumble It!

Use PowerShell to synchronise Active Directory users to a contact list – Accessing Active Directory

IvorB — Thu, 23 Dec 2010 16:38:50 GMT

The first step in performing the synchronisation, is to get user information out of active directory. I am going to assume that there is an Active Directory group that contains all your active users and I’m going to discuss 2 different methods of getting the information out of Active Directory:

Quest Software (http://www.quest.com/)
Raw PowerShell

Quest Software

Quest Software provides a wide range of products, services and solutions, but they also make a number of freeware PowerShell libraries available to download. The available free downloads include “ActiveRoles Management Shell for Active Directory”. This greatly simplifies the process of accessing Active Directory with PowerShell and can be downloaded from http://www.quest.com/powershell/activeroles-server.aspx

A simple example of using Quest ADManagement to list users in an AD Group is:

        1: # Add Quest ActiveRoles ADManagement functions

       2: if ((Get-PSSnapin "Quest.ActiveRoles.ADManagement" -ErrorAction SilentlyContinue) `

       3:     -eq $null) 

       4: {

       5:     Add-PSSnapin "Quest.ActiveRoles.ADManagement"

       6: } 

       7:  

       8: # Use Quest to get Group Members

       9: Function ListAllUsers

      10: {

      11:     $AllStaff = Get-QADGroupMember "Domain Admin"  `

      12:         -IncludedProperties displayName, givenName, sn

      13:     

      14:     foreach($IndexUser in $AllStaff)

      15:     {

      16:         Write-Host $IndexUser.givenName $IndexUser.sn "(" $IndexUser.displayName ")"

      17:     }

      18: }

      19:  

      20: Clear-Host

      21: ListAllUsers

The full syntax for the Get-QADGroupMember can be found here.

I tend to use functions whenever possible with PowerShell as it usually makes it easier to reuse the logic in other scripts.

In this example – we are only concerns about givenName (forename), sn (Surname) and displayName but there is a wealth of information in ActiveDirectory. Some other common properties which might be of interest include:

mail
mobile
otherTelephone
telephoneNumber
facsimileTelephoneNumber
pager
homePhone
Title
Company
thumbnailPhoto

Raw PowerShell

Quest ActiveRoles Management Shell for Active Directory makes it very easy to access Active Directory group member information but sometimes you might be working in an environment where you cannot perform additional installs on a environment. In general – Administrators are very reluctant to perform “optional” installs on a Live environment and they usually get very nervous when you use the word “freeware”! In this situation – we need to fallback on default functionality in PowerShell. The equivalent function to the one above can be rewritten as follows:

       1: # List Group Members

       2: Function ListAllUsers

       3: {    

       4:     [DirectoryServices.DirectorySearcher]$searcher= New-Object `

       5:             DirectoryServices.DirectorySearcher([ADSI]"")

       6:     $searcher.SearchRoot = [adsi]"LDAP://CN=Domain Admins,CN=Users,DC=MyDomain,DC=com"

       7:     $searcher.SearchScope="base"

       8:     

       9:     # Configure the properties you are interested in

      10:     [void]$searcher.PropertiesToLoad.Add("sn")

      11:     [void]$searcher.PropertiesToLoad.Add("givenName")

      12:     [void]$searcher.PropertiesToLoad.Add("displayName")

      13:     

      14:     $searcher.AttributeScopeQuery="Member"

      15:     [DirectoryServices.SearchResultCollection]$AllStaff = $searcher.FindAll()

      16:    

      17:     foreach($IndexUser in $AllStaff)

      18:     {

      19:         # Note: The properties are all lowercase

      20:         $output = $IndexUser.Properties.givenname + $IndexUser.Properties.sn + 

      21:             "(" + $IndexUser.Properties.displayname + ")"

      22:         Write-Host ( $output )

      23:     }   

      24: } 

      25:  

      26: Clear-Host

      27: ListAllUsers

If you want to list the groups that are in ActiveDirectory, you can use:

       1: # Return a list of all the groups

       2: function ListAllGroups() 

       3: { 

       4:     [DirectoryServices.DirectorySearcher]$searcher= New-Object `

       5:             DirectoryServices.DirectorySearcher([ADSI]"")

       6:     $searcher.Filter = "(objectCategory=Group)"

       7:     [DirectoryServices.SearchResultCollection]$AllGroups = $searcher.FindAll() 

       8:  

       9:     foreach($IndexGroup in $AllGroups)

      10:     {

      11:         Write-Host $IndexGroup.Path

      12:     } 

      13: }

      14:  

      15: Clear-Host

      16: ListAllGroups

It should be clear that Quest.ActiveRoles.ADManagement makes it easier to get the information out of Active Directory, but the approach you take will probably be determined by your ability to install the library in your environment.

Now that we can get the information out of ActiveDirectory – the next step in performing the synchronisation is to create exchange contacts with this information. This will be discussed in the next post in this series.

Technorati Tags: PowerShell,Active Directory

Del.icio.us Digg It Share on Facebook Stumble It!

Use PowerShell to synchronise Active Directory users to a contact list – Introduction

IvorB — Thu, 23 Dec 2010 15:28:47 GMT

This article is the start of a short series about using PowerShell to synchronise the users in Active Directory with a person’s contact list – in particular so that they appear on their mobile phone. So, before we jump into any implementation detail, it is worth considering why you might want to synchronise active directory with a person’s phone contact list. Some reasons which spring to mind include:

Easier to make phone calls.
Improved functionality receiving phone calls.
Reduced load on office receptionists.
Reduced telephony costs.

Easier to make phone calls

To be completely honest, it really is not difficult to make phone calls without this functionality. With Windows Mobile, you usually have an option inside the phone functionality called “Company Directory” or similar. You typically type in some search criteria, press the search button and after a few seconds – a list of matching people from the Global Address List is displayed.

While this sounds straightforward, there are a number of minor disadvantages:

A phone will typically make a 3G connection or similar to get the data, so you need to be in an area capable of establishing a decent data connection.
There is a time delay between deciding you want to make a phone call and actually being able to dial (choosing company directory, entering search criteria, waiting for a response). A number of people will often phone an office receptionist and ask to be transferring to the correct number rather than wait for the search results to dial.
A user typically cannot annotate the contents of the company directory. E.g. active directory might record users’ official work phone numbers, but certain people might like a limited numbers of people to know their private numbers. Using the company directory does not allow any customisations by the end user.
You typically have to search some search criteria and perform a search of the company directory but sometimes you just want to list the company users. A scan of the list can “jog” your memory about who you want to phone.

There are also disadvantages to consider when synchronising active directory with users’ contact lists. If you have a large organisation, it can consume a reasonable amount of disk space. E.g. if you have 1024 users and you put all users into everyone’s contact list, and each contact takes 1K, you will consume:

1024 * 1024 * 1K = 1GB on the server and

1024 * 1K = 1MB on each users phone

Another advantage to consider when synchronising active directory users with contact lists comes if we use photos. We can synchronise those photos with the contact information, so users of the phone can see photos of the various people in the organisation. This can be particularly useful for new starters who may recognise a face but not know the various names, or large organisations where it might be difficult to remember everyone's name.

Improved functionality receiving phone calls

How many phone numbers can you remember? I can probably recognise 2 or 3 as I am now completely reliant on my mobile to store the various phone numbers. It is extremely useful to have the person’s name displayed when your mobile rings – at the very least – you can decide if you want to divert the user to voicemail!

Mobiles are currently not smart enough to scan the company directory to match the number – to be honest – the time delay in getting the information from the Company Directory would probably make this impossible.

If we include contact photo information – we can see the photo of the person calling which can help in the decision about accepting/diverting a call.

Storing users as phone contacts can lead to a significant usability improvement as it allows the display of names/photos for incoming company calls.

Reduced load on office receptionists

I briefly referred to user’s impatience with accessing the Company Directory above, and it should not be underestimated. After a few seconds of frustrated waiting, most people will simply cancel the search on Company Directory and phone the office receptionist and ask to be transferred to the appropriate person. Not only is it very tedious for the receptionist to perform this role – it is a distraction from their core role. If we can simplify the process of phoning our colleagues directly – we reduce the load on office receptions/administrators and potentially save money.

Reduced Telephony costs

These days, most companies have corporate agreements with their mobile provider and these typically include various incentives to use the provider. It is not uncommon for a provider to offer free mobile – to – mobile calls for business consumers, so we want to encourage our colleagues to make “free” direct calls to each other, rather than “paid” calls to receptionists who make another “paid” call to transfer them to the appropriate person.

Technical Implementation

Now that we have discussed the reasons why it might be a good idea to synchronise your users in Active Directory with people’s contact list, we will explore how this might be achieved using PowerShell. Rather than provide a complete solution as a download, the focus of this series will be to provide some snippets which others can build upon to provide their own solution. “Give a man fish and you feed him for a day, teach a man to fish and you feed him for a lifetime”. Some future posts in this series will look at the following:

· Accessing user details in Active Directory.

· Storing contacts in Outlook Exchange.

· Detecting changes in Active Directory.

· Storing photos with contact details.

Technorati Tags: PowerShell,Active Directory

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 8 – Working with Variables

IvorB — Tue, 29 Jun 2010 13:49:09 GMT

This is part 8 in a series of posts related to Windows PowerShell, and deals with working with Variables.

Those from a programming background will be very used to dealing with variables – it is something we take for granted when doing development. Without variables – it would be very difficult to write any useful scripts as we wouldn’t have anyplace to remember working values.

Variables in Windows PowerShell are prefixed with the dollar sign ($).Variable names are not case sensitive but you should be consistent to make your life easier. By default – any variables you create will exist only in the current session and will be lost when you end your session. There are 4 types of variable:

Automatic – these are created and maintained by Windows PowerShell and users cannot change their values. e.g. $PSHome stores the path to the Windows PowerShell installation directory.
Preference – these are created by Windows PowerShell with default values which the user can change. e.g. $MaximumVariableCount determines how many variables are permitted in a given session.
Environment – these store information about the operating system environment. To list all environment variables – use Get-ChildItem Env:
or to get details about a particular environment variable – use Get-ChildItem Env:ComputerName
User created – these are variable which are created and maintained by the user. When someone refers to a variable – they usually mean this type of variable. e.g. $Today = (Get-Date).date

Windows PowerShell variables are loosely typed which mean they are not limited to a particular variable type of object. The type of a variable is determined by the value it contains. e.g.

In general – most programming languages (like C#) are strongly typed. There can be a number of advantages that using strong types can bring:

Limit the range of values that a variable can contain. e.g. limiting a variable like $Age to integer values. Compilers and other tools can check that we are putting sensible values into appropriate variables.
Improved clarify. e.g. if a “+” operation is performed on 2 integer variables - then we always need to perform an addition. If a “+” operation is performed on 2 string variables – then we always need to perform a string concatenation. With loose/weak typing – the operation depends on the contents of the variables so isn’t always clear.
Improved Performance – optimisations can often be made when the type is known in advance rather than being determined “on the fly”

Windows PowerShell allows us to use the type attribute and cast syntax to constrain a variable to a particular type. Some examples include:

There are a number of Cmdlets which are designed for manipulating variables. These include:

Clear-Variable – Deletes the value for a variable
Get-Variable – Gets the variables in the current console
New-Variable – Creates a new variable
Remove-Variable – Deletes a variable and its value
Set-Variable – Changes the value of a variable.

Windows PowerShell allows us to create constant and read-only variables. While constants and read-only variables are functionality very similar – one difference is that you can delete a read-only variable while you cannot delete a constant. To create constants and read-only variables, use:

See the following for useful information about PowerShell variables:

Next step – Working with Logic

Previous step – What the heck is a Cmdlet?

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 7 – What the heck is a Cmdlet?

IvorB — Fri, 25 Jun 2010 15:14:42 GMT

This is part 7 in a series of posts related to Windows PowerShell, and deals with cmdlets.

Cmdlets (pronounced command-lets) are the smallest units of functionality in Windows PowerShell. They are named in a very specific verb-noun format that should make it obvious what operation the cmdlet performs.

e.g. Get-Date returns the current date and time while Set-Date allows you to set the current date and time.

A useful cmdlet when starting out with Windows PowerShell is Get-Command which returns a complete list of available cmdlets.

The example above also demonstrates pipelining where the output from the Get-Command cmdlet is piped (or redirected) to Format-Wide

Get-Help is also useful in discovering information about available cmdlets, and its output includes some summary information about each cmdlet.

To get detailed information about a particular cmdlet, use Get-Help “cmdlet name”.

There are 2 other variations of Get-Help which provide different levels of information for a cmdlet:

Get-Help “cmdlet” –detailed
Get-Help “cmdlet” –full

You can pass parameters to a cmdlet by using the a dash (-) notation. e.g. if you want to get the current date, but not include the time aspect, you can use the following:

Some standard cmdlets which I recommend looking at include:

Get-Command – Get information about cmdlets
Get-EventLog – Gets events fro man event log
Write-EventLog – Writes an event to the event log
Get-Host – Gets information about the host application
Get-Location – Gets information about your current working location.
Get-Variable – Gets a particular variable
Ping-Computer – Sends a ping
Read-Host – Reads information from the host window
Write-Host – Writes information to the host window.
Start-Service – starts a particular service

Use Get-Help *-* to discover other useful cmdlets.

Next step – Working with Variables

Previous step – Getting to grips with Scripts

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 6 – Getting to grips with Scripts

IvorB — Tue, 11 May 2010 14:13:09 GMT

This is part 6 in a series of posts related to Windows PowerShell, and deals with getting to grips with scripts..

So far – we have been typing commands into the PowerShell console (or the ISE) but what happens if you want to create some functionality which you can reload at a future session. The answer is to create your PowerShell commands as a PowerShell script.

You can either go hard-core and use something like Notepad (or your text editor of choice) to create the script, or you can use the ISE to create and save your script. When saving the script – give it a “.ps1” file extension so PowerShell knows that it’s a script file and not a text file. The extension comes from PowerShell 1.0 and they didn’t feel the need to change the extension for PowerShell 2.0. As you would expect – PowerShell 2.0 can run PowerShell 1.0 scripts, but the reverse is not guaranteed.

Let’s start with our first script – the typical Hello World script!

Save this as HelloWorld.ps1 (or similar). To make your life easier for the moment – make sure there is no space in the file name or anywhere in the path that contains the file name. We’ll worry about handling spaces in a later post.

The logic for this script is extremely simple:

Clear the output
Prompt the user their name and store in a variable
Say hello and repeat the users name by accessing the variable.

You have a number of choices to run this script:

Run it from inside the ISE by pressing F5
Run it from inside the ISE or PowerShell Console by typing the script name (including path) into the command prompt
Run it from a standard console prompt by using the following: powershell [FilePath]\HelloWorld.ps1 where [FilePath] is your relevant directory structure. In my case – my script is stored on my desktop so I’m executing powershell c:\Users\IvorB\Desktop\HelloWorld.ps1"

There you go – you should now have a working Hello World script!

As mentioned in Part 4 of this blog series – security measures are in place to prevent scripts executing without your permission. You have 2 choices at this stage – to digital sign your script, or to adjust your execution policy to allow execution of unsigned scripts. The easiest (and laziest) way to get this to work is to change the execution policy which you can do with the following command:

Set-ExecutionPolicy RemoteSigned.

Next step – What the heck is a Cmdlet?

Previous step – The Integrated Shell Environment (ISE)

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 5 – The Integrated Shell Environment (ISE)

IvorB — Mon, 10 May 2010 15:52:56 GMT

This is part 5 in a series of posts related to Windows PowerShell, and deals with using the Integrated Shell Environment.

So far we have been using the PowerShell Command Shell to execute PowerShell statements but you also have the option of using the Integrated Shell Environment.This is a more graphical rich interface for using PowerShell.

You can launch it in similar ways to the PowerShell Command Shell:

All Programs > Accessories > Windows PowerShell > Windows PowerShell ISE
From a command line prompt (e.g. cmd), type powershell_ise (note the underscore)
Start menu > Search > type powershell_ise (note the underscore)
[Win] + R (for Run command) > type powershell_ise (note the underscore)

The ISE interface is made up of the following:

Script/Editor pane – this is where you will spend most of your time creating scripts. Tabs across the top of the pane allow you to work on multiple scripts at the same time.
Output pane – this is where the output from executing your script is displayed.
Command pane – you can enter ad-hoc commands in this pane. It effectively behaves as a standard PowerShell Command Shell

This type of interface is a bit more familiar to those who are used to Visual Studio, although perhaps a little basic in direct comparison:

You have a text area where you can enter your script
Your have toolbar buttons to control script execution
You have basic debugging facilities.
Useful context sensitive help – highlight a command in the script window and press F1
Execute part of the scripts without running the whole thing (highlight the text you want to run and choose “Run Selection”
You can customise the environment by changing $psISE.Options including adding new menu options.

The first time I attempt to debug a script in the ISE – I couldn’t figure out how to set a breakpoint. Coming from a Visual Studio background – I am used to creating a breakpoint whenever and where-ever I like. However – the ISE refused to create my breakpoint. I eventually figured out that you simply need to save your script and you then get access to the debugging facilities. You also need to remember that breakpoints are only remembered for your session – once you close the ISE and fire it up again – you’ve lost all your previous breakpoints.

At this stage, its also worthwhile mentioning that Quest provides a free graphical user interface and script editor for Windows PowerShell called PowerGUI. This is definitely worth a look if you are going to be doing a lot with PowerShell.

Next step – Getting to grips with scripts

Previous step – Customise via Commands

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 4 – Customise via Commands

IvorB — Wed, 05 May 2010 10:48:22 GMT

This is part 4 in a series of posts related to Windows PowerShell, and deals with customising the PowerShell console through use of PowerShell commands.

We’re seen previously how you can Customise the appearance of the PowerShell command by tweaking the properties of the console. However, you can also issue PowerShell commands which affect the appearance of the console.

The command Get-Host gives you a reference to ConsoleHost object. This has a UI property which manages a lot of the UI details for the console, and this in turn has a RawUI property which gives access to colour, title etc. e.g. (Get-Host).UI.RawUI gives the following:

We use brackets around Get-Host to ensure this is evaluated first, before we access the UI property of the return object.

If you want to save a bit of typing, you can use $Host.UI.RawUI to return the same information. $Host is a special variable that is a reference to the current console object.

The property values can be changed, so you can do something like the following to get a console that looks like a standard command console:

If you change some of the properties like background-color, you might want to use the command Clear-Host to “refresh” the entire console window.

Changing the Window Size or Position is slightly more complicated as these are “complex” objects rather than simple properties. The easiest way to change these types of properties is to store the current value in a variable, and then adjust property values on the variable. e.g:

Here we store the current WindowSize in a variable called $WindowSize, adjust its Width property and then set the WindowSize back to the Console.

It would be quite tedious if you had to issue the same commands to setup your Console environment every time you wanted to use PowerShell, so the solution is to adjust your profile. You can find out where your current/active profile is stored by viewing the special variable $profile. You should find that your default profile is stored in a file called something like Microsoft.PowerShell_profile.ps1. You can now put whatever commands you like in this file (by using Notepad or similar) and these commands will be executed every time you start a PowerShell console. If the folder or file don’t already exist – just create them and everything should just work fine.

You might find that the first time you try this, that you get an error like “Microsoft.PowerShell_profile.ps1 is not digitally signed”. This is deliberate by Microsoft to prevent scripts executing without your permission. We’ll discuss signing of scripts and execution policies in a later article, but for the moment – the fastest (and laziest) way to get this to work is to change PowerShell to allow execution of local scripts which are unsigned. You can do this by issuing the following PowerShell command:

Set-ExecutionPolicy RemoteSigned

You can find loads of information about customising the PowerShell console at the following location: Customise the PowerShell Console

Next step – The Integrated Shell Environment (ISE)

Previous step – Customise the Console

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 3 – Customise the Console

IvorB — Tue, 04 May 2010 16:08:20 GMT

This is part 3 in a series of posts related to Windows PowerShell, and deals with customising the PowerShell console.

If you use the PowerShell console frequently, it is probably worth spending a bit of time to customise it to your exact tastes. You are going to be looking at the console quite a bit, so you may as well have it exactly the way you want it!

To begin customising your console, fire up the PowerShell console and right click the title bar and choose properties. From the properties menu, you then have the choice of 4 tabs:

Options
Font
Layout
Colours

Options

Cursor Size: Fairly obvious – I find the default of “small” fine for normal use.
Command History: The command history is a buffer of previous commands in the current session. You can access previous commands in the session by using the arrow keys (up and down and press Enter to choose a particular command), press F7 to display a pop up window that contains the list of buffered commands or type the first few letters of the command to execute and press F8.
Edit Options: QuickEdit mode allows you to single mouse click to paste into the command window (rather than right clicking and choosing paste). InsertMode means that you default to inserting a new command and clearing this option means that you overwrite text as the default editing mode.

Font

Allows you to adjust the font used in the console window. I personally increate the font size to “12 x 16” which I find easier on the eye.

Layout

Screen Buffer Size: This controls the virtual window size which is the amount of content the window can actually hold. If the virtual window size is larger than the actual window size, then the console window changes to include scrollbars.
Window Size: The size of the physical window. You should probably make the width the same as the screen buffer size width to avoid horizontal scroll bars.
Window Position: Uncheck Let system position window if you want to control the initial position of the window.

Colours

Allows you to set the foreground and background colours used by the PowerShell console.

Click OK to save your settings to your user profile. Note: You may need to run PowerShell as Administrator in order for your settings to be saved. It is also worth noting that your changes are only applicable to the shortcut that you used to start PowerShell.

Next step – Customise via Commands

Previous step – Installation

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 2 - Installation

IvorB — Fri, 30 Apr 2010 11:07:00 GMT

This is part 2 in a series of posts related to Windows PowerShell, and deals with Installation

The good news if you are running Windows 7 or Windows Server 2008 R2 (or later) is that you have nothing to do – PowerShell V2 was installed as part of the operating system.

If you have a different operating system and want to install PowerShell – you have to choose between PowerShell V1 and PowerShell V2. The only reason I can think of to choose PowerShell V1 is if you were working as part of a team where everyone is using that version. If possible – just go for PowerShell V2 as it includes a vast number of additional commands.

PowerShell is installed as part of Windows Management Framework so visit Microsoft Support for install packages for a number of different platforms.

Once PowerShell is on your system, fire it up by any of the following methods:

All Programs > Accessories > Windows PowerShell > Windows PowerShell V2
From a command line prompt (e.g. cmd), type powershell
Start menu > Search > type powershell
[Win] + R (for Run command) > type powershell

Whatever method you try, the result should be the same – the PowerShell command prompt which should look like:

Once you’ve got the PowerShell console open – let’s confirm that you have V2 installed by typing the following command:

get-host

You should see something like the following:

Assuming you have got the same – then we are good to go.

Next step – Customise the Console

Previous step – Introduction

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!

Windows PowerShell Series - Part 1 - Introduction

IvorB — Thu, 29 Apr 2010 16:38:00 GMT

This is the start of a number of posts related to Windows PowerShell. The goal is that each post will introduce a single concept, and build upon previous posts in the series. We’re going to start off with a very gentle introduction which will hopefully explain “What is Windows PowerShell?”

Windows PowerShell is the latest command line shell and scripting language from Microsoft. An initial reaction might be “Do we really need another shell?” and my answer is that you should give it a go. If you like it – use it. If you don’t like it – then chances are you will be able to achieve whatever you need to do some other way. What PowerShell does really well is bring together a large number of commands, make their usage consistent and makes it really easy for you to build your own powerful scripts.

PowerShell implements a scripting language based upon C# and an object model based upon Microsoft .NET framework. As such – it is incredibly easy for someone with a developer background to pick it up. However – System Administrators will also love the fact that they will be able to use PowerShell to manage Active Directory, Exchange, Windows File System, Windows Services and a wide variety of other essential system infrastructure components.

This series will attempt to cover as many aspects of PowerShell as possible, but feel free to make suggestions for content to cover.

Next step – Installing PowerShell…

Technorati Tags: PowerShell

Del.icio.us Digg It Share on Facebook Stumble It!