README
Wmic.js
A Node.js fluent interface to Windows Management Instrumentation CLI(WMIC).
Getting Started
Prerequisites
Typically WMI service is enabled on your Windows OS. If not, please use the following commands to start the service:
sc start winmgmt // Start WMI Service
sc query winmgmt // Check if the service is running
If you are using wmic.js connecting to a remote machine, please make sure wmi firewall settings enabled:
netsh advfirewall firewall set rule group="windows management instrumentation (wmi)" new enable=yes
Installing
npm install wmic-js
And import it:
const wmic = require('wmic-js');
Usage
The goal of wmic.js is to provide a JavaScript interface to WMIC
and make it delight for you to run WMIC commands and get the result.
Wmic.js supports most of the WMIC features, including all of the
alias, class and path, and verbs like get
, set
, list
, call
, create
and delete
.
For more information about wmic, please run this command:
wmic /?
Initialize
Firstly, you need to use wmic object to create a Query:
wmic();
// Or
wmic(options);
Options
options
object is optional for defining WMIC global switches,
WMIC executable path and WMIC commands handler. Default option values
are listed below:
const defaultOptions = {
// Supported global switches
role: null,
node: null,
user: null,
password: null,
failfast: null,
implevel: null,
authlevel: null,
namespace: null,
privileges: null,
// WMIC executable path
binary: 'wmic',
// Result encoding, only used in WMIC built-in command handler
encoding: null,
// WMIC commands handler
exec: function(command) {
// built-in handler
}
};
Commands
Next, you need to specify an command for the query. There are four
types of command: alias
, class
, path
and context
corresponding
to the WMIC commands. You can directly call one of them after wmic()
:
// Specify query command by `alias`, `class` or `path`
wmic().alias(friendlyName);
wmic().class(className);
wmic().path(path);
// Or get the current WMIC context and stop right here
wmic().context();
Here are some examples:
wmic().alias('Environment');
wmic().class('StdRegProv');
wmic().path('StdRegProv');
Where/orWhere Clause
WMI uses a subset of SQL named Windows Management Instrumentation Query
Language(WQL). Wmic.js support the where
/orWhere
clause to limit query
results. The where
/orWhere
method takes in either two or three parameters,
or a closure for nested where conditions:
wmic().alias('NICConfig').where('Index', 1);
// Equals to
wmic().alias('NICConfig').where('Index', '=', 1);
// You can also use other operators
wmic().alias('NICConfig').where('Description', 'LIKE', '%WAN%');
// Use orWhere to give an alternative condition
wmic().alias('NICConfig').where('Description', 'LIKE', '%WAN%').orWhere('Description', 'LIKE', '%LAN%');
Please use closure to get complex where clause:
wmic().alias('Environment').where(function() {
this.where('Name', 'A').where('VariableValue', 1);
}).orWhere(function() {
this.where('Name', 'B').where('VariableValue', 2);
});
This is equal to
wmic Environment WHERE '(Name="A" AND VariableValue=1) OR (Name="B" AND VariableValue=2)'
find(pWhere)
Wmic.js also provides an extra verb find
for you to specify pWhere conditions
easily:
wmic().alias(friendlyName).find(pWhereValue);
Here's an example:
wmic().alias('NICConfig').find(1);
// Same as
wmic().alias('NICConfig').where('Index', 1);
For aliases and their supported pWhere fields, please use this command:
wmic ALIAS /?
Verbs
Wmic.js supports get
, set
, list
, call
, create
and delete
to fetch
information in JSON format or apply changes. Wmic.js uses Promises to pass
results.
get(...fieldNames)
Get certain fields or all fields of some WMI objects. fieldNames
is optional.
wmic().alias('NICConfig').find(1).get('Description').then(console.log);
// [
// {
// Description: 'VirtualBox Host-Only Ethernet Adapter #2'
// }
// ]
// Or get all fields
wmic().alias('NICConfig').find(1).get().then(console.log);
// [
// {
// ArpAlwaysSourceRoute: null,
// ArpUseEtherSNAP: null,
// Caption: '[00000001] VirtualBox Host-Only Ethernet Adapter',
// DatabasePath: '%SystemRoot%\\System32\\drivers\\etc',
// ...
// }
// ]
To get more information about field names, please run this command:
wmic [alias|class SOMECLASS|path SOMEPATH] GET /?
list(format)
A short cut to get(...fieldNames)
, format
can be BRIEF
, FULL
, SYSTEM
,
etc.
wmic().alias('NICConfig').find(1).list('BRIEF').then(console.log);
// [
// {
// "Description": "VirtualBox Host-Only Ethernet Adapter #2",
// "DHCPEnabled": "FALSE",
// "DNSDomain": null,
// "Index": "1",
// "ServiceName": "VBoxNetAdp"
// }
// ]
To get more information about formats, please run this command:
wmic [alias|class SOMECLASS|path SOMEPATH] LIST /?
create(parameter)
Create a resource using giving fields and values. The parameter
is an object
whose key is field name and value is field value. Here is an example for creating
an environment variable for current user:
wmic().alias('Environment').create({
'UserName': '%USERDOMAIN%\\%USERNAME%',
'Name': 'EXAMPLE_ENV',
'VariableValue': 1
}).then(console.log);
// null
To get more information about create action, please run this command:
wmic [alias|class SOMECLASS|path SOMEPATH] CREATE /?
set(parameter)
Modify resources using giving fields and values. The parameter
is similar to
the one in create(parameter)
. PLEASE USE WHERE TO SELECT THE RESOURCES THAT
YOU WANT TO SET.
wmic().alias('Environment').where('Name', 'EXAMPLE_ENV').set({
'VariableValue': 2
}).then(console.log);
// null
To get more information about set action, please run this command:
wmic [alias|class SOMECLASS|path SOMEPATH] SET /?
delete()
Delete resources. PLEASE USE WHERE TO SELECT THE RESOURCES THAT YOU WANT TO DELETE.
wmic().alias('Environment').where('Name', 'EXAMPLE_ENV').delete().then(console.log);
// null
To get more information about delete action, please run this command:
wmic [alias|class SOMECLASS|path SOMEPATH] DELETE /?
call(method, ...parameters)
Call a WMI method on WMI objects.
// Set your operating system's time
const DateTime = require('wmic-js').Types.DateTime;
wmic().alias('OS').where('SerialNumber', '00000-00000-00000-00000')
.call('SetDateTime', new DateTime(new Date()))
.then(console.log);
// { ReturnValue: 0 }
// Check registry key access
const UInt32 = require('wmic-js').Types.UInt32;
const KEY_QUERY_VALUE = new UInt32(1);
const HKEY_LOCAL_MACHINE = new UInt32(2147483650);
wmic.class('StdRegProv').call('CheckAccess', HKEY_LOCAL_MACHINE, "SYSTEM\\CurrentControlSet", KEY_QUERY_VALUE)
.then(console.log);
// { bGranted: true, ReturnValue: 0 }
To get more information about call action, please run this command:
wmic [alias|class SOMECLASS|path SOMEPATH] CALL /?
Other things you should know...
The
context
command will directly return a Promise containing WMIC running context:wmic().context().then(console.log); // { // "NAMESPACE": "root\\\\cimv2", // "ROLE": "root\\\\cli", // "NODE(S)": "HOMEPC", // "IMPLEVEL": "IMPERSONATE", // ... // }
Wmic.js will detect your system's encoding(actually code page), so under most occasions you don't need to specify
encoding
option forwmic()
. But you may do this if you are sure about the system's encoding and need a better performance.Many WMIC commands needs to be called under administrator privileges, you can use third-party packages like sudo-prompt to provide such executing environment and override default execution handler:
const elevate = require('sudo-prompt').exec; const extract = require('wmic-js').extract; wmic({ exec: function(command) { return new Promise(function(resolve, reject) { elevate(command, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }, function(error, stdout, stderr) { // Decode with stdout and extract information using #extract(text) }) }) }})
Please refer to test/elevate.js for more information.
You can use
node
global switch to execute same WMI commands on different machines at the same time, machine(node) names will be attached to the results:wmic({ node: [ '127.0.0.1', 'localhost' ] }).alias('os').list().then(console.log); // [ // { // "node": "127.0.0.1", // "result": [ // { // "BuildNumber": "14393", // "Organization": "", // "SystemDirectory": "C:\\WINDOWS\\system32", // ... // } // ] // }, // { // "node": "HOMEPC", // "result": [...] // } // ]
Deployment
Test
npm test
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
Authors
- PPoffice - Initial work - PPOffice
See also the list of contributors who participated in this project.
License
This project is licensed under the MIT License - see the LICENSE.md file for details