Summary: Learn how to use Windows PowerShell to automate basic administrative tasks on a WSUS server.

Microsoft Scripting Guy, Ed Wilson, is here. Today we have the second blog post by Boe Prox about WSUS and Windows PowerShell. See yesterday’s blog for the introduction to WSUS and to learn more about Boe.

Take it away, Boe…

In yesterday’s blog, I showed you how to install a WSUS server and configure your clients via Group Policy and/or registry modifications, and I briefly introduced you to the steps taken to make your first connection to a WSUS server by using Windows PowerShell and the assemblies that are available after you install the Administration Console.

Today, we start looking at some of the basic administration steps for managing your WSUS server. Some of the steps I plan to discuss work with clients and target groups.

To step back one day, here are the steps for making your initial connection to the server. Note that you must have the WSUS Administration Console installed to access the required assemblies. (I covered installing the WSUS Administration Console in yesterday’s blog).

[void][reflection.assembly]::LoadWithPartialName(“Microsoft.UpdateServices.Administration”)

$wsus = [Microsoft.UpdateServices.Administration.AdminProxy]::getUpdateServer(“dc1”,$False)

$wsus

OK, we now have a connection to the WSUS server and we are ready to dive into some Windows PowerShell fun!

The first thing I do, is see what I have available to me in the form of methods on this object.

$wsus | Get-Member –Type Method

The output is shown in the following image.

Yes, that is quite a number of available methods to use. Depending on what methods you use, they will return objects that have more methods within them! Therefore, there are many possibilities for exploration within your WSUS server from which to pull information.

Finding WSUS clients

You can quickly query and identify one or all of the clients that are currently using the WSUS server with a couple of commands. Each query returns a Microsoft.UpdateServices.Internal.BaseApi.ComputerTarget object that you can use for other commands within the WSUS server, and it has its own set of methods that you can utilize. Before we dig into those, let us look at the possible commands that we can use to locate a client in WSUS.

GetComputerTargetByName()

$wsus.GetComputerTargetByName(“dc1.rivendell.com”)

As you can see in the following image, this command requires the full domain name of the system that you are going to query. Anything less than the full name will result in the command throwing an error (also shown in the following image).

SearchComputerTargets()

$wsus.SearchComputerTargets(“DC1”)

This command allows you to specify a shorter name to query the client on the WSUS server. This can also be used for performing a wildcard search for clients, such as in the following example.

$wsus.SearchComputerTargets(“D”)

As you can see, I can pull up all clients that start with the letter D.

GetComputerTarget()

This method is a little tougher to use in that you have to know the client ID, which you probably won’t be able to locate unless you use on of the methods listed previously to query for a client. In the example that follows, I already located a client ID from a previous query.

$wsus.GetComputerTarget([guid]” db683962-0b62-4dd2-be0d-b535c25cf7f7”)

GetComputerTargets()

This method has a couple of uses that are great to use for searching clients. The first way to use is method is to call it as it is. This will perform a complete dump of all of the clients in WSUS.

$wsus.GetComputerTargets()

The second way to use this method is to supply a computer scope object to use for the query, which is my favorite way to look for clients. This example will have to wait a couple more days when I discuss working with the computer scope object for reporting.

So with that, we have covered a few different ways to query the WSUS server for clients, and now let’s look at a couple of useful methods within the computer object that can help us with our administration.

An important computer object gotcha!

There is one little thing that I have yet to mention about the computer object that you get from each of these queries. Even if you return only one object from your query (without using Select-Object –First 1 or anything else along those lines), that object will actually be part of a collection (Microsoft.UpdateServices.Administration.ComputerTargetCollection) that you will have to work with to actually be able to use that object’s methods.

$Client = $wsus.SearchComputerTargets(“DC1”)

$Client.GetType().ToString()

To use the methods, you need to step through each member of the collection—or in the case of only one member of the collection being returned, by slicing into the array as shown in the following example.

$client[0].GetType().ToString()

Now that is more like it! Now we can start playing with some of the fun methods of this object.

Getting a client’s target group membership

This method is useful for pulling all of the groups that a client is a member of:

GetComputerTargetGroups()

$Client = $wsus.SearchComputerTargets(“DC1”)

$client[0].GetComputerTargetGroups()

Removing a client from the WSUS server

This method is pretty self-explanatory:

Delete()

It will delete the current computer object that is calling this method. This is a great way to remove stale computers that are off the domain or have not checked in for an extended period for other reasons.

$client[0].Delete()

There are two more methods that are great to use; however, I am going to leave those hanging until later in the week because they require the Update Scope object, which I will go into more detail about then. The two methods that I am talking about are:

GetUpdateInstallationInfoPerUpdate()

GetUpdateInstallationSummary()

So stay tuned until later in the week and I will show you what you can do with these methods!

Target groups

Next on the list are target groups in WSUS and how we can use Windows PowerShell to manage these. Luckily, there are only two methods that we can use to query for the target groups. Each of these methods used will return the following type of Target Group object: Microsoft.UpdateServices.Internal.BaseApi.ComputerTargetGroup. 

The first method to look at is:

GetComputerTargetGroups()

This method returns all the target groups that exist on the WSUS server. It is an all-or-nothing approach, and you can then filter that collection for the group you are looking for.

$wsus.GetComputerTargetGroups()

As you can see, I only have two groups at this time that also happen to be the default groups you get with the WSUS installation. I used this one first so I can transition more easily into the next method. This works great, but it has a small prerequisite: You have to know the ID of the group.

GetComputerTargetGroup()

As I mentioned, this method requires the ID of the WSUS target group. It is not the most useful method if you have no idea what that group ID is without first using the GetComputerTargetGroups() method.

$wsus.GetComputerTargetGroup([guid]” a0a08746-4dbe-4a37-9adf-9e7652c0b421”)

Creating a new target group

We now have a couple of ways to get our target groups from WSUS, but it would be great if we could also create our own groups. This can be done very easily by using the following method from the WSUS server object that we created with our initial connection:

CreateComputerTargetGroup()

We have a couple of options with this method that we can use to create a target group. The first way is to create a group at the root of the target groups and the second allows you to create a child group underneath a parent. First, let’s create a root group:

$wsus.CreateComputerTargetGroup(“TESTGROUP”)

An object is immediately returned when you create the new group.

Now I will create a child group underneath this group. The first thing that I need to do is get the group object of the parent.

$group = $wsus.GetComputerTargetGroups() | Where {$_.Name –eq “TESTGROUP”}

$wsus.CreateComputerTargetGroup(“CHILDGROUP”,$group)

$wsus.GetComputerTargetGroups()

And just like that, I have my child group. OK, the console does not really show you that this is truly a child group, so here it is in GUI form.

Removing a target group

Removing a target group is pretty simple. All you have to do is call the Delete method from the group object.

Delete()

$group = $wsus.GetComputerTargetGroups() | Where {$_.Name –eq “TESTGROUP”}

$group.Delete()

Adding a client to a target group

Adding a client to a group is also very easy, you just need to have the computer object for the client that you want to add to the group. The method that you can use is:

AddComputerTarget()

$Client = $wsus.SearchComputerTargets(“DC1”)

$group = $wsus.GetComputerTargetGroups() | Where {$_.Name –eq “TESTGROUP”}

$group.AddComputerTarget($client[0])

Remember, the GetComputerTargetGroups() I showed you earlier? Let’s go ahead and run that now to see DC1’s memberships.

$client[0].GetComputerTargetGroups()

Removing a client from a target group

Removing a client from a group works very much like adding a client to the group. The computer object is again required for the method that will remove the client. The method for the client removal is:

RemoveComputerTarget()

$Client = $wsus.SearchComputerTargets(“DC1”)

$group = $wsus.GetComputerTargetGroups() | Where {$_.Name –eq “TESTGROUP”}

$group.RemoveComputerTarget($client[0])

And let’s verify that DC1 is no longer in the TESTGROUP.

$client[0].GetComputerTargetGroups()

All gone! Because it has no other group memberships at this time, DC1 gets put back into the “Unassigned Computers” group.

This really is only a handful of possible methods that are available for the client and target group objects, but these are some of the more important methods that you should know about for working with the WSUS server.

That wraps up today’s introduction to administering a WSUS server by using Windows PowerShell. Tomorrow I will continue talking about some basic administration techniques that you can use for your WSUS server by using Windows PowerShell.

~Boe

Boe, thank you for your blog. It rocks.

WSUS Week will continue tomorrow.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy