IUpdateServer.RegisterComputer Method (String)

Article
10/10/2016

Applies To: Windows Server Update Services

Registers a client computer with the WSUS server.

Namespace: Microsoft.UpdateServices.Administration
Assembly: Microsoft.UpdateServices.Administration (in Microsoft.UpdateServices.Administration.dll)

Syntax

IComputerTarget RegisterComputer(
    string computerName
)

IComputerTarget^ RegisterComputer(
    String^ computerName
)

abstract RegisterComputer : 
        computerName:string -> IComputerTarget

Function RegisterComputer (
    computerName As String
) As IComputerTarget

Parameters

computerName
Type: System.String

Name of the client computer to add. For example, if the client is a member of a domain, use the fully qualified domain name (name.domain.corp.com). The name must be less than 256 characters.

Return Value

Type: Microsoft.UpdateServices.Administration.IComputerTarget

An IComputerTarget that represents the specified client computer. Use the instance to add the client to a group.

Exceptions

Exception

Condition

ArgumentException

The name contains a character that is not valid.

ArgumentNullException

computerName cannot be null.

ArgumentOutOfRangeException

computerName cannot be an empty string and must be less than 256 characters.

WsusObjectAlreadyExistsException

A client with the specified name is already registered.

Remarks

Typically, client computers register themselves the first time they contact the WSUS server. You can use this method to pre-register the computer so you can use the client information for planning purposes.

The name that you specify must match the name used by the client when the client first contacts the WSUS server. If the names match, WSUS updates the temporary Id value of the client you registered to the unique identifier that is specified by the client. If the names do not match, the client will register itself, leaving the client that you pre-registered untouched.

If you try to get the client using the temporary value after WSUS changes the identifier, you will receive a WsusObjectNotFoundException.

This method validates that the specified computer name is well-formed according to DNS standards, but does not verify that the name exists.

The client is placed in the All Computers group and the Unassigned Computers group. If the server's TargetingMode is Server, call AddComputerTarget to move the client from the Unassigned Computers group to another group.

This operation requires WSUS Administrator privileges.

Examples

The following example shows how to query computers from a fictitious Accounting organizational unit in Active Directory, register them in WSUS, and move them to the Accounting group. The server variable that is used in the example is an instance of IUpdateServer (for information on getting an IUpdateServer instance, see GetUpdateServer.

using System.DirectoryServices;
try
{
   IComputerTargetGroup accounting; //already set
   IComputerTarget client;

   //Use the DCs to specify the full domain server name (name.domain.corp.com)
   DirectoryEntry root = new DirectoryEntry("LDAP://OU=Accounting, DC=<name>, DC=<domain>, DC=<corp>, DC=com");
   DirectorySearcher searcher = new DirectorySearcher(root);
   searcher.SearchScope = SearchScope.OneLevel;
   searcher.Filter = "(objectClass=computer)";

   foreach (SearchResult result in searcher.FindAll())
   {
      String fullClientName = (String)result.GetDirectoryEntry().Properties["dnsHostName"].Value;
      if (null != fullClientName)
      {
         client = server.RegisterComputer(fullClientName);
         if (TargetMode.Server == server.GetConfiguration().TargetingMode)
         { 
            accounting.AddComputerTarget(client);
         }
      }
   }
}
catch (System.Runtime.InteropServices.COMException e)
{
   Console.WriteLine("Error retrieving computer name from Active Directory.");
}
catch (WsusObjectAlreadyExistsException e)
{
   Console.WriteLine("The client, {0}, already exists.\n{1}", fullClientName, e.Message);
}