Change method of the Win32_Service class (Mbnapi.h)
The Change WMI class method modifies a Win32_Service.
This topic uses Managed Object Format (MOF) syntax. For more information about using this method, see Calling a Method.
Syntax
uint32 Change(
[in] string DisplayName,
[in] string PathName,
[in] uint32 ServiceType,
[in] uint32 ErrorControl,
[in] string StartMode,
[in] boolean DesktopInteract,
[in] string StartName,
[in] string StartPassword,
[in] string LoadOrderGroup,
[in] string LoadOrderGroupDependencies[],
[in] string ServiceDependencies[]
);
Parameters
-
DisplayName [in]
-
The display name of the service. This string has a maximum length of 256 characters. The name is case- preserved in the service control manager. DisplayName comparisons are always case-insensitive.
Constraints: Accepts the same value as the Name property.
Example, "Atdisk".
-
PathName [in]
-
The fully qualified path to the executable file that implements the service, for example, "\SystemRoot\System32\drivers\afd.sys".
-
ServiceType [in]
-
The type of services provided to processes that call them.
-
1 (0x1)
-
Kernel Driver
-
2 (0x2)
-
File System Driver
-
4 (0x4)
-
Adapter
-
8 (0x8)
-
Recognizer Driver
-
16 (0x10)
-
Own Process
-
32 (0x20)
-
Share Process
-
256 (0x100)
-
Interactive Process
ErrorControl [in]
Severity of the error if this service fails to start during startup. The value indicates the action taken by the startup program if failure occurs. All errors are logged by the system.
Ignore (0)
User is not notified.
Normal (1)
Normal. User is notified.
Severe (2)
System is restarted with the last good configuration.
Critical (3)
System attempts to restart with a good configuration.
StartMode [in]
Start mode of the Windows base service. For more information, see the Remarks section.
Boot
Device driver started by the operating system loader. This value is valid only for driver services.
System
Device driver started by the operating system initialization process. This value is valid only for driver services.
Automatic
Service to be started automatically by the Service Control Manager during system startup.
Manual
Service to be started by the Service Control Manager when a process calls the StartService method.
Disabled
Service that can no longer be started.
DesktopInteract [in]
If True, the service can create or communicate with a window on the desktop.
StartName [in]
Account name the service runs under. Depending on the service type, the account name may be in the form of DomainName\Username or .\Username. The service process will be logged using one of these two forms when it runs. If the account belongs to the built-in domain, .\Username can be specified. If NULL is specified, the service will be logged on as the LocalSystem account. For kernel or system-level drivers, StartName contains the driver object name (that is, \FileSystem\Rdr or \Driver\Xns) that the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver runs with a default object name created by the I/O system based on the service name, for example, "DWDOM\Admin".
You also can use the User Principal Name (UPN) format to specify the StartName, for example, Username@DomainName.
StartPassword [in]
Password to the account name specified by the StartName parameter. Specify NULL if you are not changing the password. Specify an empty string if the service has no password.
Note
When changing a service from a local system to a network, or from a network to a local system, StartPassword must be an empty string ("") and not NULL.
LoadOrderGroup [in]
Group name that it is associated with. Load order groups are contained in the system registry, and determine the sequence in which services are loaded into the operating system. If the pointer is NULL, or if it points to an empty string, the service does not belong to a group. For more information, see the Remarks section.
Dependencies between groups should be listed in the LoadOrderGroupDependencies parameter. Services in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list, followed by services that do not belong to a group. The system registry has a list of load ordering groups located at:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder
LoadOrderGroupDependencies [in]
List of load-ordering groups that must start before this service starts. The array is doubly null-terminated. If the pointer is NULL, or if it points to an empty string, the service has no dependencies. Group names must be prefixed by the SC_GROUP_IDENTIFIER (defined in the Winsvc.h file) character to differentiate them from service names because services and service groups share the same namespace. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all of the members of the group.
ServiceDependencies [in]
List that contains the names of services that must start before this service starts. The array is doubly NULL-terminated. If the pointer is NULL, or if it points to an empty string, the service has no dependencies. Dependency on a service indicates that this service can run only if the service it depends on is running.
Return value
Returns one of the values listed in the following list, or any other value to indicate an error. For additional error codes, see WMI Error Constants or WbemErrorEnum. For general HRESULT values, see System Error Codes.
-
Success
-
0
The request was accepted.
-
Not Supported
-
1
The request is not supported.
-
Access Denied
-
2
The user did not have the necessary access.
-
Dependent Services Running
-
3
The service cannot be stopped because other services that are running are dependent on it.
-
Invalid Service Control
-
4
The requested control code is not valid, or it is unacceptable to the service.
-
Service Cannot Accept Control
-
5
The requested control code cannot be sent to the service because the state of the service (Win32_BaseService.State property) is equal to 0, 1, or 2.
-
Service Not Active
-
6
The service has not been started.
-
Service Request Timeout
-
7
The service did not respond to the start request in a timely fashion.
-
Unknown Failure
-
8
Unknown failure when starting the service.
-
Path Not Found
-
9
The directory path to the service executable file was not found.
-
Service Already Running
-
10
The service is already running.
-
Service Database Locked
-
11
The database to add a new service is locked.
-
Service Dependency Deleted
-
12
A dependency this service relies on has been removed from the system.
-
Service Dependency Failure
-
13
The service failed to find the service needed from a dependent service.
-
Service Disabled
-
14
The service has been disabled from the system.
-
Service Logon Failed
-
15
The service does not have the correct authentication to run on the system.
-
Service Marked For Deletion
-
16
This service is being removed from the system.
-
Service No Thread
-
17
The service has no execution thread.
-
Status Circular Dependency
-
18
The service has circular dependencies when it starts.
-
Status Duplicate Name
-
19
A service is running under the same name.
-
Status Invalid Name
-
20
The service name has invalid characters.
-
Status Invalid Parameter
-
21
Invalid parameters have been passed to the service.
-
Status Invalid Service Account
-
22
The account under which this service runs is either invalid or lacks the permissions to run the service.
-
Status Service Exists
-
23
The service exists in the database of services available from the system.
-
Service Already Paused
-
24
The service is currently paused in the system.
-
Other
-
25 4294967295
Remarks
When a computer starts, all the autostart services also start. On occasion, one of these services might fail to start along with the computer. When a service fails during system startup, the computer takes action based on the value of the service error control code.
most services are installed using the Normal error control code. A few of the exceptions, which are installed using the Ignore error code, include:
- File Replication Service
- Smart Card
- Secondary Logon
- WMI
For the services installed using the Ignore error code, no notification is given to the user that the service has failed. If you prefer on-screen notification that a service could not start, you can use WMI to change the error control code. Error control codes apply only to computer startup; error control codes are not used if you stop and then attempt to restart a service after the computer is running.
On occasion, you might need to change the account under which a given service runs. For example, you might run a service under an administrative account. Because this can create a security vulnerability, you might switch the service to an account with fewer privileges. Alternatively, you might have services running under an account that is about to be deleted, or you might want to ensure that, on all your servers, certain services run under certain accounts. You can use the Change method of the Win32_Service class to configure services to run under a specified user account. When selecting an account, keep in mind the following:
The account being used as a service account must have the right to log on as a service. This right can be granted by using Group Policy.
The account being used as a service account should not be a member of a local, domain, or enterprise Administrators group.
Each instance of a service should run under a unique user account. This provides additional security, and enables the auditing of individual service instances.
If the service is interactive, then the service must run under the LocalSystem account.
LocalSystem is required because only one window station (WinSta0) can be visible and interactive at a time. If a service runs under an account other than LocalSystem, it runs in the Service-0x03e7$\Default window station, which is an invisible window. Services running in this window station cannot receive input or display output.
When you assign an account to a service, the SCM requires the correct password for that account before it makes the assignment. If you supply an incorrect password, the SCM rejects the account. If you configure a service account using the LocalSystem, LocalService, or NetworkService account, you do not need to supply an account password because these accounts do not have passwords.
The SCM stores the account password in the services database. After the password is assigned, however, the SCM does not ensure that the password stored in the services database and the password assigned to the user account in Active Directory continue to match. Consequently, a situation similar to the following could occur:
- You configure a service to run under a particular user account.
- The service starts up under that account by using the current account password.
- You change the password for the user account.
- The service continues to run. However, if the service stops, you cannot restart it because the SCM continues to use the old, invalid password. Changing the password in Active Directory does not change the password stored in the services database.
If you run services under regular user accounts, you need to update those service passwords each time the user account password changes. This can be particularly time-consuming if you are not sure which services are running under that account or which computers have services running under that account. Fortunately, you can use WMI to check the service accounts on all your computers and, if necessary, change the service account password.
The Win32_LoadOrderGroup parameter represents a group of system services that define execution dependencies. The services must be initiated in the order specified by the Load Order Group because the services depend on each other. These dependent services require the presence of the antecedent services to function correctly.
To change a service from a network service to a local system the StartName and StartPassword parameters should have the following values:
StartName = "LocalSystem"
StartPassword = "" // - empty string, not NULL
To change a service from a local system service to a network the StartName and StartPassword parameters should have the following values:
StartName = "NT AUTHORITY\NetworkService"
StartPassword = "" // - empty string, not NULL
Examples
The following VBScript changes the service account for services from running under a specified user account to LocalSystem.
strComputer = "."
Set objWMIService = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" & strComputer & "\Root\CIMv2")
Set colServiceList = objWMIService.ExecQuery("SELECT * FROM Win32_Service WHERE StartName = '.\\NetSvc'")
For Each objService in colServices
errServiceChange = objService.Change( , , , , , , ".\LocalSystem" , "")
Next
The following VBScript changes the service account password for all scripts running under Netsvc
strComputer = "."
Set objWMIService = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" & strComputer & "\Root\CIMv2")
Set colServiceList = objWMIService.ExecQuery("SELECT * FROM Win32_Service WHERE StartName = '.\\NetSvc'")
For Each objservice in colServiceList
errReturn = objService.Change( , , , , , , , "password")
Next
Requirements
Requirement | Value |
---|---|
Minimum supported client |
Windows Vista |
Minimum supported server |
Windows Server 2008 |
Namespace |
Root\CIMV2 |
Header |
|
MOF |
|
DLL |
|