SDK Resources > Intel vPro Scripting Library
CollapseAll image

Intel vPro Scripting Library

Intel.WsMan.Scripting.DLL is a .NET assembly that contains scriptable components for interacting with Intel® vPro™ firmware. The assembly defines interfaces that facilitate access to firmware resources using the WS-Management protocol as well as interfaces for using the media redirection features of Intel® AMT. It also provides access to the Intel® MEI driver.

Any .NET application can use the scripting library by adding a reference to Intel.WsMan.Scripting.DLL. For PowerShell environments, the library is automatically available when the Intel module is loaded via the Import-Module command.

For more information see the following:

Installing the Scripting Library

Look in <SDKRoot>\Windows\Common\WS-Management\IntelvProModule\x86 or x64 for the  install files. Execute the appropriate version for your environment. The installation does not require any special responses. The DLL and associated files are installed in \Modules\IntelvPro under the system PowerShell directory.  A silent installation of Intel vPro Module msi is possible by using the /quiet switch and running it with admin privileges.  In an admin rights cmd window:  c:\IntelvProModule-x64.msi/quiet.

See the PDF document at <SDKRoot>\Windows\Common\WS-Management\IntelvProModule for more about installation and the vPro Module capabilities.

Scripting Library Dependencies

The WS-Management aspects of the library have no dependences other than the .NET framework itself. The media redirection features require that IMRSDK.DLL and KVMLib.DLL be in the load path. The ME (local driver) interface requires that the appropriate chipset drivers be installed and that the application is running as “admin”.

WS-Management Operations

The Intel.Management.Wsman namespace provides a programming interface for exchanging firmware resources using the WS-Management protocol. Performing WsMan operations typically involves three basic steps. First, create a connection object and fill in the required connection information. Second, create a reference to a resource that is supported by the connection. Finally, perform one or more WS-Management operations on the reference.

Creating WS-Management Connections

Before WS-Management operations can be performed, a connection to a WS-Management endpoint must be established. Connections can be relatively simple requiring only a user name, password and address. However, depending on the state or configuration of the endpoint, connections may require more information such as digital certificates and proxy information.

 

using Intel.Management.Wsman;

 

 

// create a connection object

IWsmanConnection conn = newWsmanConnection();

 

// read the connection values from the project settings

conn.Username = "admin";

conn.Password = "P@ssw0rd";

conn.Address = "http://myAmtBox:16992/wsman";

conn.AuthenticationScheme = "Digest”;

 

//Optional – test the connection by sending a WsMan Identify

//to see if the endpoint is available, that it supports WS-Management,

//and that you have permissions to the endpoint

conn.Identify();  

 

Creating References

References can be thought of as representing the path or link to a resource and not the actual resource itself. There are a few different ways to define a reference to a resource. In general, a reference consists of a name and zero or more selectors. Selectors are typically simple name value pairs used to find or “select” a resource.

 

//Creating a reference using SQL style Syntax

IManagedReference refToObj =

  Connection.NewReference("SELECT * FROM CIM_SoftwareIdentity "

                          "WHERE InstanceID='AMT FW Core Version'");

 

//Creating a reference by manually adding selectors to it

IManagedReferencerefToObj =

  Connection.NewReference("CIM_SoftwareIdentity");

Connection.AddSelector("InstanceID","AMT FW Core Version");

 

Reference Names

Reference names are also referred to as Resource URIs and typically look like an actual URL (for example, http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_SoftwareIdentity). Even though the resource name looks like a URL, it really is not, although an organization may register documentation at the URL. It is not necessary to specify the full resource URI when using the connection object, as the connection object will automatically prefix any name it receives with the full URI when the name starts with CIM_, AMT_, or IPS_.

Working with EPRs

An endpoint reference (EPR) is a specific reference to a CIM object (See Working with Intel AMT using Endpoint References). When an object is created, the return parameter is the EPR.

For example, see the snippet in the “create a system defense policy” use case. The last line of this snippet is:

 

$systemDefensePolicyRef = $SystemDefensePolicyInstance.Create

 

Display the value of the reference:

 

write $systemDefensePolicyRef.Xml

 

The output will look something like this:

 

"<b:EndpointReference xmlns:b='http://schemas.xmlsoap.org/ws/2004/08/addressing' xmlns:c='http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd'><b:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</b:Address><b:ReferenceParameters><c:ResourceURI>http://intel.com/wbem/wscim/1/amt-schema/1/AMT_SystemDefensePolicy</c:ResourceURI><c:SelectorSet><c:Selector Name='InstanceID'>Intel(r) AMT:Handle:2</c:Selector></c:SelectorSet></b:ReferenceParameters></b:EndpointReference>"

 

You can save the full EPR and use it to retrieve the object.

 

# Perform some function, for example Get().

$systemDefensePolicyRef.Get()

 

Alternatively, you can save the selector set and use that to retrieve the object. In this example, the selector set consists of one property, the InstanceID.

The following code demonstrates retrieving an object using a selector:

 

$instanceID ="Intel(r) AMT:Handle:2"

# Set the reference using the selector.

$systemDefensePolicyRef =$wsmanConnectionObject.NewReference("SELECT * FROM AMT_SystemDefensePolicy WHERE InstanceID='"+$instanceID+"'")

# Perform a function, for example Get().

$systemDefensePolicyRef.Get()

 

Dealing with “From” Instances

Retrieving resources represented by a reference results in an instance object. An instance object represents a copy of the actual object at the time it was retrieved. Instances consist of one or more named properties and each property has an associated value. Collectively the properties describe the information the resource is trying to convey. The GetProperty() method can be used to retrieve the value of a property.

 

//Retrieve an an instance of a single resource

IManagedInstance cimObj = refToObj.Get();

//get the value of the a property called VersionString

string value = cimObj.GetProperty("VersionString").ToString();

//Retrieve an Instance Directly by using a query instead of a reference

IManagedInstance cimObj =

  Connection.NewInstance("SELECT * FROM CIM_SoftwareIdentity "

                         "WHERE InstanceID='AMT FW Core Version'");

//Retrieve all instances of a class by using a query instead of a reference

IWsmanEnumeration collection =

    Connection.ExecQuery("SELECT * FROM CIM_SoftwareIdentity");

foreach (IWsmanItem item in colObj)

{

   item.Object.GetProperty("VersionString").ToString();

}

 

Instance Properties and the IWsmanItem Object

Since the value of a property can be of different types, the IWsmanItem interface is used to describe the value. Often the value of a property will be a simple string. However, a property can be a more complex type such as a nested object, an embedded reference to an object, or even an array of values. The IWSmanItem facilitates retrieving the appropriate value of the property based on its detected type.

 

//Check if a property exists

cimObj.GetProperty("VersionString").IsNull

 

//Retrieve the value of a simple string property

cimObj.GetProperty("VersionString").ToString();

 

 

//Retrieve the value of a property as a reference to an object

IManagedReferencerefToObj = cimObj.GetProperty("Antecedent").Ref;

 

//Get all the values of an array property

foreach (IWsmanItem item in logObj.GetProperty("Capabilities"))

{

    item.ToString();

}

    

Enumerating a Null item (meaning the property does not exist) will result in an empty enumeration.

Enumerating Resources

The Enumerate() method of the IManagedReference interface can be used to retrieve all the resources belonging to a ResourceUri. Because different types of resources can potentially be returned by an enumeration, the IWsmanItem interface is used to describe the resource. The default behavior of enumerate is to return objects, so the Object property of the IWsmanItem will return the actual object. More advanced enumerations can be used that can result in both objects and references being returned or even references instead of the object.

 

//Enumerate all instances of a class by name only

IWsmanEnumeration features = Connection.NewReference("CIM_BIOSFeatureBIOSElements").Enumerate(null, null);

foreach (IWsmanItem elements in features)

{

}

 

//Use a SQL query to enumerate instances

IWsmanEnumeration colObj =

    Connection.ExecQuery("SELECT * FROM CIM_Privilege");

foreach (IWsmanItem item in colObj)

{

}

 

ExecQuery() will return an empty enumeration even if the class does not exist while the Enumerate() Method of IManagedReference interface will throw an InvalidResourceURI exception if the class is does not exist.

Invoking Methods

Actions can be performed on resources by using the Invoke() method on the IManagedReference interface. All input arguments to a method are passed in a single object known as the INPUT object. All output arguments to a method are passed in a single object known as the OUTPUT object. Each property of an INPUT or OUTPUT object represents an individual parameter. Properties (parameters) can be added to the INPUT method using the SetProperty() or AddProperty Method. The INPUT objects are created by invoking the CreateMethodInput method.

 

//Create an INPUT object for the method

IManagedInstance inputObj =

        RefToService.CreateMethodInput("RequestPowerStateChange");

//Set the a Parameter named “PowerState”

inputObj.SetProperty("PowerState", "5");

//Set the a Parameter named “ManagedElement”

inputObj.SetProperty("ManagedElement", refToUser);

//After setting all the input paramerts invoke the method

IManagedInstance outObj = serviceRef.InvokeMethod(inputObj);

//Get the ReturnValue of the method

string result = outObj.GetProperty("ReturnValue").ToString();

 

The invoke method returns a single output object containing all output parameters. All method invocations will result in at least one output parameter called “ReturnValue”. A return value of “0” typically indicates success.

Changing Values of Instances

Properties can be added or changed by using the SetProperty() or AddProperty() methods of the IManagedInstance interface. SetProperty() will replace or update any existing property of the same name while, AddProperty() will add an additional property of the same name. AddProperty() is useful when specifying an array of property values while SetProperty() is usefull when dealing with single values.

 

//Retrieve an an instance of a single resource

IManagedInstance cimObj = refToObj.Get();

//Set the value of the a property called “HostName” to a value of “MyAmtBox”

cimObj.SetProperty(“HostName","MyAmtBox");

 

IManagedInstance cimObj = refToObj.Get();

 

//Remove an existing property by setting its value to null

cimObj.SetProperty("ServicePrincipleName",null);

 

//Define an array of of values

cimObj.AddProperty("ServicePrincipleName","HTTP/MyAMT.mydomain.com:16992");

cimObj.AddProperty("ServicePrincipleName","HTTP/MyAMT.mydomain.com:16993");

cimObj.AddProperty("ServicePrincipleName","HTTP/MyAMT.mydomain.com:16994");

cimObj.AddProperty("ServicePrincipleName","HTTP/MyAMT.mydomain.com:16995");

 

//Define a property were the value contains a complete XML definition

cimObj.AddProperty(null , "<tns: AccountTemplate..");

 

 

 

Copyright © 2006-2021, Intel Corporation. All rights reserved.