Create method of the Win32_Service class (CIMWin32 WMI Providers)

Article
04/27/2021

The Create WMI class method creates a new system service.

This topic uses Managed Object Format (MOF) syntax. For more information about using this method, see Calling a Method.

Syntax

uint32 Create(
  [in] string  Name,
  [in] string  DisplayName,
  [in] string  PathName,
  [in] uint8   ServiceType,
  [in] uint8   ErrorControl,
  [in] string  StartMode,
  [in] boolean DesktopInteract,
  [in] string  StartName,
  [in] string  StartPassword,
  [in] string  LoadOrderGroup,
  [in] string  LoadOrderGroupDependencies[],
  [in] string  ServiceDependencies[]
);

Parameters

Name [in]

Name of the service to install to the Create method. The maximum string length is 256 characters. The Service Control Manager database preserves the case of the characters, but service name comparisons are always case-insensitive. Forward-slashes (/) and double back-slashes (\) are invalid service name characters.

DisplayName [in]

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 parameter.

Example: "Atdisk".

PathName [in]

Fully qualified path to the executable file that implements the service.

Example: "\SystemRoot\System32\drivers\afd.sys".

ServiceType [in]

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 the Create method fails to start. The value indicates the action taken by the startup program if failure occurs. All errors are logged by the system.

User is not notified.

User is notified.

System is restarted with the last-known-good configuration.

System attempts to start with a good configuration.

StartMode [in]

Start mode of the Windows base service.

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 windows on the desktop.

StartName [in]

Account name under which the service runs. Depending on the service type, the account name may be in the form of DomainName\Username or User Principal Name (UPN) format (Username@DomainName). The service process is 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 is logged on as the LocalSystem account. For a kernel or system-level drivers, StartName contains the driver object name (that is, \FileSystem\Rdr or \Driver\Xns) which 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. Example: DWDOM\Admin.

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.

LoadOrderGroup [in]

Group name associated with the new service. Load order groups are contained in the 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. 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 registry has a list of load ordering groups located at:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder

LoadOrderGroupDependencies [in]

Array of load-ordering groups that must start before this service. Each item in the array is delimited by NULL and the list is terminated by two NULL values. In Visual Basic or script you can pass a vbArray. 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 it from a service name, 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]

Array that contains names of services that must start before this service starts. Each item in the array is delimited by NULL and the list is terminated by two NULL values. In Visual Basic or script you can pass a vbArray. If the pointer is NULL, or if it points to an empty string, the service has no dependencies. Dependency on a service means that this service can only run 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.

0: The request was accepted.
1: The request is not supported.
2: The user did not have the necessary access.
3: The service cannot be stopped because other services that are running are dependent on it.
4: The requested control code is not valid, or it is unacceptable to the service.
5: The requested control code cannot be sent to the service because the state of the service (State property of the Win32_BaseService class) is equal to 0, 1, or 2.
6: The service has not been started.
7: The service did not respond to the start request in a timely fashion.
8: Unknown failure when starting the service.
9: The directory path to the service executable file was not found.
10: The service is already running.
11: The database to add a new service is locked.
12: A dependency this service relies on has been removed from the system.
13: The service failed to find the service needed from a dependent service.
14: The service has been disabled from the system.
15: The service does not have the correct authentication to run on the system.
16: This service is being removed from the system.
17: The service has no execution thread.
18: The service has circular dependencies when it starts.
19: A service is running under the same name.
20: The service name has invalid characters.
21: Invalid parameters have been passed to the service.
22: The account under which this service runs is either invalid or lacks the permissions to run the service.
23: The service exists in the database of services available from the system.
24: The service is currently paused in the system.

Remarks

Services are generally installed in one of two ways: either as a part of the operating system installation or by using an installation program provided by the service developer. However, some services, particularly those created in-house, might not have an installation program. In those instances, you can use the Create method to programmatically install services.

Despite the name, the Create method does not actually create a service; it merely installs an existing service. To use this command, you need to copy the service executable file to a computer and then use Create to install the service.

The Create method is similar to the Change method. In both cases, the properties of the service are passed as parameters to the method. As with the parameters used with the Change method, the order in which these parameters are passed is very important.

The LoadOrderGroup parameter represents a grouping of system services defining execution dependencies. The services must be initiated in the order specified by the Load Order Group, as the services are dependent on each other. These dependent services require the presence of the antecedent services to function correctly.

Examples

The following VBScript installs a service named DbService

Const OWN_PROCESS = 16
Const NOT_INTERACTIVE = True
strComputer = "."
Set objWMIService = GetObject("winmgmts:" _
 & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")
Set objService = objWMIService.Get("Win32_BaseService")
errReturn = objService.Create ("DbService", "Personnel Database", _
"c:\windows\system32\db.exe", OWN_PROCESS ,2 ,"Automatic" , _
 NOT_INTERACTIVE ,".\LocalSystem" ,"")

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Namespace	Root\CIMV2
MOF	CIMWin32.mof
DLL	CIMWin32.dll