The Microsoft Management Console (MMC) Group Policy Management Console (GPMC) snap-in is an exceptionally helpful new tool in Windows Server 2003. GPMC lets you perform most Group Policy Object (GPO)—related tasks from one interface. Even better, GPMC installs several COM objects that you can use to automate most of these tasks. In "Scripting Group Policy Objects" (October 2003, http://www.winscriptingsolutions.com, InstantDoc ID 39856), I discussed how to get started using these objects. That article, as well as the other resources I've listed in "Related Resources," page 2, can teach you the basics of how to automate policy-based tasks. With the basics under your belt, you're ready to start using GPMC's COM objects for bigger and better tasks, such as programmatically searching for GPOs, finding all the Scope of Management (SOM) objects for a GPO, and finding all the SOM objects in an Active Directory (AD) tree.
A Simple Search for All GPOs
To use the scripts in "Scripting Group Policy Objects," you must know the globally unique identifier (GUID) of the GPO to which you want to connect in AD. The parts of the GPO that AD stores have a distinguished name (DN) such as cn={myguid}, cn=policies, cn=system, dc=mydomain, dc=mycorp, dc=com, where {myguid} is the GUID. In theory, using the GUID isn't a problem because GPOs tend to change little after administrators have set them up. But what if you don't want to hard-code the GUID in the script? Or what if you want to find out which GPOs exist in AD or which GPOs are linked to a specific SOM object? In such cases, you can automate searches within GPMC.
For example, the script SearchAndReport.vbs, which Listing 1, page 2, shows, searches the specified domain for all GPOs that exist, whether or not they're linked to an AD tree. The script begins by setting the DOMAIN constant to the name of the domain to search. If you want to use SearchAndReport.vbs, you must replace mydomain.mycorp.com with the name of your domain. This same holds true for all the constants in the scripts I present here. You need to replace the values that are being assigned to those constants with values that apply to your AD.
In the code at callout A in Listing 1, I use VBScript's CreateObject function to create a reference to the GPM object. I use the GPM object's GetDomain method with the DOMAIN constant as an argument to create a GPMDomain object that represents my domain. This GPMDomain object will let me create, query, and restore GPOs and search SOM objects in that domain. I also use the GPM object's CreateSearchCriteria method to create a reference to a GPMSearchCriteria object. You can use this object to specify the criteria for your search operation. In this case, I haven't specified any criteria—in other words, I passed in a "blank" GPMSearchCriteria object—which will prompt the retrieval of all the GPOs in the domain.
With the necessary objects in hand, I execute the search. As the code at callout B in Listing 1 shows, I use the GPMDomain object's SearchGPOs method with a blank GPMSearchCriteria object as the parameter. The SearchGPOs method returns a GPMGPOCollection object that contains all the GPOs in the domain. I then work with that collection in the usual manner. I start by using the GPMGPOCollection object's Count property to count the number of GPOs in the collection, then use the Echo command to display that number. Next, I use a For Each...Next statement to walk through the collection. For each GPO, I display the GPO's GUID, friendly display name, and DN. The GUID and the DN are both unique because they both contain the GUID. The display name doesn't have to be unique.
Finding SOM Objects for a GPO
As SearchAndReport.vbs demonstrates, searching a domain for all the GPOs it contains is simple. Let's now look at a more complicated search. Suppose you want to find all the domains and organizational units (OUs) that a GPO links to in the AD tree. In other words, suppose you want to find all the domain and OU SOM objects for a GPO. You can use a script such as FindSOMsforGPO.vbs, which Listing 2 shows. This script uses a known GPO as the basis for the search; a constant represents the GPO's GUID. The GUID in FindSOMsforGPO.vbs is the Default Domain Policy object's GUID, which is the same across all Windows 2003 and Windows 2000 Server domains. By using this GUID, you can run FindSOMsforGPO.vbs and discover all the domains and OUs to which the Default Domain Policy links.
Let's discuss how FindSOMsforGPO.vbs works. In the code at callout A in Listing 2, I create a reference to the GPM object and use that object's GetDomain method to create a GPMDomain object. Using the GPMDomain object's GetGPO method with the GUID constant as an argument, I retrieve the GPO that represents the Default Domain Policy.
Next, I need to search the domain for any SOM objects that use the same GUID as the defined GUID constant. To do this, I can use the GPMDomain object's SearchSOMs method to return a GPMSOMCollection object, which represents a collection of SOM objects. The SearchSOMs method requires a GPMSearchCriteria object as a parameter. However, if I pass in a blank GPMSearchCriteria object, as I did in Listing 1, I'll get all the SOM objects for the domain—and that's not what I want. Instead, I want to retrieve the SOM objects for only one specific GPO. To ensure that the search returns only those SOM objects, I need to add to the GPMSearchCriteria object a criterion that specifies the GPO in which I'm interested.
As the code at callout B in Listing 2 shows, I first create a GPMSearchCriteria object, as I did in Listing 1. Next, I need to use the GPMSearchCriteria object's Add method to add a criterion to the object.
In the Microsoft Developer Network (MSDN) Library, the syntax for the Add method might look complex, but the method is easy to use. To add criteria, you use the syntax
Add(SearchProperty,
SearchOperator, Value)
where SearchProperty and Value specify the property name and value, respectively, that you want to search for and where SearchOperator specifies the operator you want to use to conduct that search. The Add method includes operators that let you find a property that contains (opContains), doesn't contain (opNotContains), equals (opEquals), or doesn't equal (opNotEquals) a value. For example, if I'm searching for a specific GPO in the domain with a known GUID, I can use
gpoID opEquals GUID