Recover deleted Active Directory objects with the AD Recycle Bin PowerPack

Last week Microsoft made the announcement that Windows Server 2008 R2 reached RTM.  Among the many cool new features provided with that release (Hello?  PowerShell v2?  Need I say more?), Microsoft has now added a recycle bin feature to Active Directory.  The management interface provided by Microsoft for this feature is the command line, or more specifically, PowerShell.  That’s great if you’re like me and you love to manage your infrastructure using PowerShell, but what if you prefer a GUI?  Fortunately there is a solution for you too.

As Jackson Shaw suggested on his blog about a week ago, PowerGUI provides an admin console that allows you to create your own management UI that is layered on top of PowerShell.  This admin console can be extended with PowerPacks, which are essentially add-ins that provide additional user interface elements in PowerGUI that invoke PowerShell script when clicked.  All you need to do is add the user interface elements you want and then provide the scripts to power those elements, managing the Active Directory Recycle Bin objects or anything else you need to manage.  Or alternatively you can check to see if someone on the PowerGUI Community like myself has already created a PowerPack with the functionality you are looking for.

In the case of the Active Directory Recycle Bin, you’re in luck.  I just finished creating the first release of a new PowerPack that is designed to allow you to manage any objects in your recycle bin.  You can find the Active Directory Recycle Bin PowerPack by following the hyperlink here or by going directly to and browsing into the Active Directory subcategory in the PowerPack Library.  This PowerPack includes the following features:

  • View the contents of the recycle bin, including hierarchies
  • Restore individual items in the recycle bin (recursively or not) to their original location
  • Restore individual items in the recycle bin (recursively or not) to a specified location
  • Permanently delete objects in the recycle bin (recursively or not)
  • Empty the contents of the recycle bin
  • Modify the number of days that the recycle bin is configured to retain objects and the number of days that objects are to be kept in a tombstone state before permanent deletion

If you would like to see a demo of the Active Directory Recycle Bin PowerPack, watch this screencast:

If you prefer watching a high resolution version of the screencast, you can watch it in flash format here or on YouTube directly in HD format here.

This is the initial release of this PowerPack and it contains a good amount of new functionality.  If you are experimenting with the Active Directory Recycle Bin feature, please take a look at this PowerPack and provide any feedback you have so that we can continue to provide improvements that are valuable to you and others in future releases.

Thanks for listening!

Kirk out.

Share this post:

Create custom nodes easily with the Active Directory PowerPack and PowerGUI

Here’s a great question that someone just posted today on the PowerGUI forums:

I have the latest verions of the Quest AD cmdlets, PowerGUI and the Active Directory PowerPack.  Can I use PowerGUI to search for old computer accounts?  For example: computer accounts that haven’t had their machine account password reset for over three months?

The timing of this question is perfect because the update of the Active Directory PowerPack that I posted two weeks ago allows you to do this without having to write any scripts yourself.  For those of you who want to try this but don’t have the most recent versions of PowerGUI, the Quest AD cmdlets and the Active Directory PowerPack installed, follow those links and download and install those before continuing.  Installation instructions are on the appropriate web pages where necessary.

Once you all of the necessary software installed, here’s what you need to do.

Step 1: Add the attributes you need to the list of attributes retrieved from Active Directory.

There are In the PowerGUI Admin Console, expand the “Active Directory” node and click on “Configuration”.  This will show you the current domain that PowerGUI will gather data from.  You can change this if you like, however you don’t need to unless you want to use alternate credentials or connect to another domain.  With the configuration showing in the grid, click on the “Manage default attributes” link.  That will present you with a view something like this:


This shows you the current list of attributes that are retrieved for each individual Active Directory object.  This will be initially configured with the default attributes as defined by the Quest AD cmdlets plus a few attributes that are required for the Active Directory PowerPack.  You can add whatever attributes you want to gather here for any of the object types.  To help solve our immediate problem and be able to get a list of computer accounts that have not had their machine account password reset for over three months, we need to add the pwdLastSet attribute for computer objects.  To do this, simply click on the “Add attribute…” action, provide the name of the pwdLastSet attribute in the “Attribute name” field and set the “Retrieve attribute for computer objects” value to True.  When you click on OK, that attribute configuration will be saved and any computer objects retrieved using the Quest AD cmdlets will have that attribute retrieved with them.

Step 2: Retrieve the objects you want from Active Directory and optionally show the attributes you want to filter on.

Once you have configured PowerGUI so that it will retrieve the pwdLastSet attribute for computer objects, you need to get your computers.  You can do this by simply clicking on the “Computers” child node under the “Active Directory” node.  This will present you with a list of computer accounts, showing their Name, Type and DN by default.

With the list of computer objects showing, you can optionally add the pwdLastSet attribute to the view by right-clicking in the column headers and selecting “More…” from the menu that appears.  With the list of all attributes that can be added showing, scroll down until you find the pwdLastSet attribute and check the checkbox beside it.  Then click on OK to save that change and your pwdLastSet attribute will be retrieved with your computer objects from the Computers node.

Step 3: Create a client-side filter to filter out the objects you don’t care about.

With the list of all of your computer objects showing, you can create a filter to reduce the number of objects to those that you need to see.  To do this, click on the Filters button above the column headers.  This will make the filter panel visible.


You can use this panel to filter any collection based on the properties of the objects in that collection.  For our particular problem, we want to see computer objects whose password has not been changed in the last 3 months.  We can get that by selecting “pwdLastSet” in the “Property” field, “Less or equal” in the “Operator” field, and selecting the calendar date three months ago in the “Value” field using the calendar control.  Once that is set, click on the “Apply” button to apply the filter and your list of computer objects will be filtered to only show those whose machine passwords haven’t changed in the last 3 months.

Step 4: Make the newly filtered data set available in its own node.

Now that you have the data you’re looking after, your “Computers” node is now configured to always show you the filtered list because PowerGUI remembers the filters you apply to nodes.  You might not like this configuration, preferring to have a separate node to view the data that you want.  Fortunately, PowerGUI lets you do create that easily too, and you still don’t have to do any scripting.  To create a separate node that lets you get the same data set, simply click on the “Save As…” button in the filter panel.  This will allow you to save the script from the Computers node with the filter you have created automatically applied as a client-side filter for that script.  Simply give the new script node a name (something intuitive like “Computers with old passwords” will do), and click on OK to save the new child node.  Then you can click on the “Clear All” button in the filter panel for your “Computers” node because that filter will no longer be needed.  Now click on your new node and you’ll get the list of computers you are after, and it will look something like the screenshot below.


Step 5: Make your work reusable at any time by taking it one step further.

At this point you have successfully created a new node that gets specifically the data you were looking for and you didn’t have to do any scripting to get it, which is great!  You can make it a little better still though.  For our specific problem that we’re trying to solve, we created a new node that reports any computer object with a machine account password that hasn’t been changed within 3 months from today.  But tomorrow that will be come 3 months and 1 day.  The next day that will become 3 months and 2 days.  What if you want to customize the node so that it reports computers whose machine accounts have not had their passwords changed in the last 3 months, no matter what day you click on it?  For that to work you will have to do a minor script modification.

Right-click on your new “Computers with old passwords” node and select properties.  This will show you the script used to retrieve your computers and filter the list.  At the very end of that script, you will see something like the following:

func_Computers | Where-Object {
    $_.'pwdlastset' -le [System.DateTime]"2009-02-08"

The Where-Object cmdlet contains the filter that is excluding any computers whose pwdLastSet attribute is greater than 3 months from the day we did this (for me that that’s February 8, 2009 since I created the node on May 8, 2009).  To change that filter so that it always works using a date 3 months earlier than now, you simply need to replace [System.DateTime]”2009-02-08” with (Get-Date).AddMonths(-3).  That changes the end of our script to this:

func_Computers | Where-Object {
    $_.'pwdlastset' -le (Get-Date).AddMonths(-3)

That’s it!  A simple replacement of the filter condition and you’re off and running with a brand new node designed to meet your specific needs with PowerGUI, the Quest AD cmdlets and the Active Directory PowerPack!

In a future article I’ll show you just how simple it is for you to take a collection of extensions to PowerPacks that you have created like this and package them up in a PowerPack so that you can share them with other users in the Community as well!


Kirk out.


Share this post:

The Active Directory PowerPack, the Quest AD cmdlets, and what can happen when you change public object interfaces or cmdlet parameter attributes in PowerShell

This is about what can happen when things go wrong and what not to do so that things don’t go wrong.

In case you didn’t know, I work at Quest Software on the PowerGUI Team.  My position is rather unique because I work exclusively with Windows PowerShell, and I don’t think there are too many jobs out there that offer that experience.  The main focus of my job is to create and extend PowerPacks, which are collections of PowerShell scripts that are packaged together to define an extension to the customizable PowerGUI Admin Console.  The scripts in the PowerPacks I create range anywhere from the extremely simple (one cmdlet or function call) to the very complicated (a script that calls into one or more functions that span many thousands of lines of PowerShell script).

Among others, one of the PowerPacks that I manage is the Active Directory PowerPack.  The Active Directory PowerPack provides a management interface to Active Directory, and it uses the Quest AD cmdlets in its PowerShell scripts to do the actual management of Active Directory.  For quite a few reasons1,  I need to explicitly indicate which connection should be used when you use that PowerPack to do something with Active Directory, regardless of what it is you are doing.  This means I am absolutely dependent on being able to determine what connection should be used in any script that is included in the PowerPack.  For scripts that are used at the beginning of a pipeline I look for the appropriate connection information that is stored globally.  For other scripts that are used later in a pipeline with Quest AD cmdlets I look at the Connection property that is attached to the objects coming down the pipeline.  This model has worked very well until recently when something unexpected happened.

Almost two weeks ago, just after version 1.2 of the Quest AD cmdlets was released, it came to my attention that the Connection property that I am so dependent on was not included on objects in that release.  For those of you who are not developers, this type of change (changing a public interface in an SDK) is very bad news.  It is called a breaking change, and the name is very fitting – the Active Directory PowerPack started breaking all over the place for users who upgraded their Quest AD cmdlets to version 1.2!

Amid a flurry of email discussions between myself and the Quest AD cmdlets team I spent the next week and a bit putting together an update to the Active Directory PowerPack so that it would work despite these changes, basically putting the Connection property there myself if it isn’t there.  At the same time, the Quest AD cmdlets team quickly started work on a 1.2.1 patch release to put the Connection property back in so that scripts outside of PowerGUI that use that property wouldn’t be affected either.  The patch for the Quest AD cmdlets is not available yet, but the updated Active Directory PowerPack, and the updated Network PowerPack which also used the Quest AD cmdlets a fair amount and was therefore susceptible to this change, are now posted in the PowerPack library and available for download.  If you use these PowerPacks, I strongly recommend you download and import the most recent releases of each of these PowerPacks.  Their document page in the PowerPack library contains all of the information you need to upgrade your PowerPacks and get started using the new versions.

Now that I have finished dealing with the impact of a breaking change like this one and the unpleasant work that ensues,  I thought it would be worthwhile to share with others what exactly consititutes a breaking change in a PowerShell cmdlet or advanced function.  The following is a list of 13 rules that you should adhere to when updating your cmdlets or advanced functions if you want to avoid introducing breaking changes:

  1. Do not remove any published parameters that are included in your published cmdlets or advanced functions.
  2. Do not rename any published parameters that are included in your published cmdlets or advanced functions unless you add an alias to the parameter that is the old parameter name.
  3. Do not reduce or remove pipeline support for any published parameters in your published cmdlets or advanced functions that support pipeline input.
  4. Do not remove support for $null input for any published parameters in your published cmdlets or advanced functions that support $null input.
  5. Do not modify the default value for any published parameters in your published cmdlets or advanced functions unless that modification will not change how the command functions in existing scripts.
  6. Do not add a required flag to any parameter in published parameter sets in your published cmdlets or advanced functions.
  7. Do not modify the position of any published parameters in published parameter sets in your published cmdlets or advanced functions.
  8. Do not replace the associated object type with an incompatible type for any published parameters in your published cmdlets or advanced functions.
  9. Do not remove wildcard support for any published parameters in your published cmdlets or advanced functions that have wildcard support.
  10. Do not remove support for building the value from the remaining arguments in any published parameters in your published cmdlets or advanced functions that support building the value in this manner.
  11. Do not remove any of your published parameters from published parameter sets in your published cmdlets or advanced functions.
  12. Do not increase validation restrictions for any of your published parameters in your published cmdlets or advanced functions that have validation restrictions.
  13. Do not modify or remove aliases for any published parameters in your published cmdlets or advanced functions.

Additionally you need to pay attention to the objects that are returned by your cmdlets or advanced functions so that you don’t introduce breaking changes on those either.  The following rules should be adhered to in order to avoid breaking changes on objects returned by your cmdlets or advanced functions:

  1. Do not remove a public property or method.
  2. Do not replace the types associated with a public property or method with incompatible types.
  3. Do not modify the order of the parameters in a public method.
  4. Do not add required parameters in a public method.

Not following these rules means risking breaking production scripts, risking making your customers unhappy, and many other potential undesirable consequences.  Please, if you are seriously trying to add value to the PowerShell ecosystem by extending it with additional commands, pay attention to these rules and don’t introduce breaking changes when you update them!

Thanks for listening!

Kirk out.

1 Reasons why the connection must be explicitly indicated in the Active Directory PowerPack:
1. The Quest AD cmdlets allow you to connect to many different directory services.
2. Opening a connection to a directory service with the Quest AD cmdlets changes a global variable that is used automatically by other cmdlets in the same snapin when you don’t explicitly indicate what connection to use.
3. In PowerGUI you can create or import other PowerPacks that may open their own connections to different directory services using the Quest AD cmdlets, Active Directory or otherwise.
4. In PowerShell, whether you are using the Quest AD cmdlets interactively or invoking a script that uses them, you are likely only working with one set of data from one directory service at a time in a logical manner.  Working in a user interface that is built on top of PowerShell is less restrictive, allowing you to move more freely between multiple data sets from multiple sources (directory services in this case) in what would be considered an illogical manner as far as script creation goes.

Share this post: