Scripting in Windows Remote Management

The Scripting API in WinRM and the accompanying COM API for C++ are designed to closely reflect the operations of the WS-Management protocol.

The WinRM Scripting API in Windows Remote Management supports all the WS-Management protocol operations except one. It does not allow subscriptions to events. To subscribe to events from the BMC System Event Log, you must use the Wecutil or Wevtutil command-line tools. For more information, see Events.

The WinRM Scripting API is called by Winrm.vbs, a command-line tool, which is written in Visual Basic Scripting Edition (VBScript). Winrm.vbs provides examples of how to use the WinRM Scripting API.

Using WSman Compared to Using WMI Scripting

WMI connects to remote computers through DCOM, which requires the configuration described in Connecting to WMI on a Remote Computer. WinRM does not use DCOM to connect to a remote computer. Instead, the WS-Management protocol sends SOAP messages and the service uses a single port for HTTP and a port for HTTPS transport.

Unlike the winrm command-line tool, scripts must provide the XML required to pass to the WS-Management protocol messages. They must also provide URIs. For more information, see Resource URIs and Windows Remote Management and WMI.

The WMI Scripting API works with objects, such as instances of Win32_LogicalDisk, which represent resources on a computer. This WMI class is defined in Managed Object Format (MOF) files, which are stored in binary form in the WMI repository. In WMI, a Get operation for a single resource or a query for multiple instances returns WMI objects.

A WinRM script does not return objects, but rather streams of XML text. For more information, see Windows Remote Management and WMI.

Displaying XML Output from WinRM Scripts

The WinRM Scripting API gets and receives XML strings that describe resources. The resultant XML is in the form of a text stream and requires an XML transform to be displayed in some other way.

The following WinRM script produces raw XML output.

Set Wsman = CreateObject("Wsman.Automation")
Set xmlFile = CreateObject( "MSxml.DOMDocument")
Set Session = Wsman.CreateSession
Response = Session.Get("" _
    & "1/wmi/root/cimv2/Win32_Service?Name=Spooler")
xmlFile.Save( "c:\RawOutput.xml")

The following block of text shows the XML output from the WinRM script.

<p:Win32_Service xmlns:xsi="
instance" xmlns:p="
/wmi/root/cimv2/Win32_Service" xmlns:cim="https://schemas.dmtf
.org/wbem/wsman/1/base" cim:Class="Win32_Service"><p:AcceptP
<p:Caption>Print Spooler</p:Caption><p:CheckPoint>0</p:CheckP
<p:Description>Loads files to memory for later printing</p:De
ayName>Print Spooler</p:DisplayName><p:ErrorControl>Normal</p
:ErrorControl><p:ExitCode>0</p:ExitCode><p:InstallDate xsi:ni
viceType>Own Process</p:ServiceType><p:Started>true</p:Starte
/p:TagId><p:WaitHint>0</p:WaitHint><cim:Location xmlns:cim="h
ttp://" xmlns:a="https://sc" xmlns:w="https://sche"><a:Address>https://schemas.xm</a:Address><a:
w:SelectorSet><w:Selector Name="Name">spooler</w:Selector></w

Your scripts can use an XML transform to make this output more readable. For more information, see Displaying XML Output from WinRM Scripts.

The following version of the script formats the XML into human-readable output.

Set Wsman = CreateObject("Wsman.Automation")
Set xmlFile = CreateObject( "MSXml.DOMDocument" )
Set xslFile = CreateObject( "MSXml.DOMDocument" )

Set Session = Wsman.CreateSession
Response = Session.Get("" _
    & "1/wmi/root/cimv2/Win32_Service?Name=Spooler")
xslFile.Load( "WsmTxt.xsl" )
Wscript.Echo xmlFile.TransformNode( xslFile )

The XSL transform creates the following output.

    AcceptPause = false
    AcceptStop = true
    Caption = Print Spooler
    CheckPoint = 0
    CreationClassName = Win32_Service
    Description = Loads files to memory for later printing
    DesktopInteract = true
    DisplayName = Print Spooler
    ErrorControl = Normal
    ExitCode = 0
    InstallDate = null
    Name = Spooler
    PathName = C:\Windows\System32\spoolsv.exe
    ProcessId = 1720
    ServiceSpecificExitCode = 0
    ServiceType = Own Process
    Started = true
    StartMode = Auto
    StartName = LocalSystem
    State = Running
    Status = OK
    SystemCreationClassName = Win32_ComputerSystem
    SystemName = wsplab6-4
    TagId = 0
    WaitHint = 0

WinRM Script and Winrm.cmd Output

The output from a WinRM script is encoded in Unicode. If you create a FileSystemObject and write a file from the script, the resulting file is Unicode. However, if you redirect the output to a file, the encoding is ANSI. If you redirect the output to an XML file and there are Unicode characters in the output, the XML will be invalid. Be aware that the Winrm command-line tool outputs ANSI.

About Windows Remote Management

Using Windows Remote Management


DOM Reference