2.2.4.37 Shell

Article
06/24/2021

The Shell data type is used in multiple messages. It is used in the body element of the wst:Create message (for more information, see section 3.1.4.5.2) and defines information required to properly initialize the targeted Shell. It describes the body element of the wsf:CreateResponse message and describes the properties of the created Shell instance (for more information, see section 3.1.4.5.2). It also describes the body element of the wst:GetResponse message and describes the properties of an existing Shell instance (for more information see section 3.1.4.2.1). This data type is used to create and describe both the Text-based Command Shell and the Custom Remote Shell. The element has several predefined elements and ends with an open content model, so additional resource-specific initialization can be provided by using a single XML element of arbitrary structure from another XML namespace.

The XML namespace URI that MUST be used by implementations for all Shell data types is http://schemas.microsoft.com/wbem/wsman/1/windows/shell.

 <xs:complexType name="Shell">
   <xs:sequence>
     <xs:element name="ShellId"
       type="xs:anyURI"
       minOccurs="0"
      />
     <xs:element name="Name"
       type="xs:string"
       minOccurs="0"
      />
     <xs:element name="ResourceUri"
       type="xs:anyURI"
       minOccurs="0"
      />    
      <xs:element name="Owner"
       type="xs:string"
       minOccurs="0"
      />
     <xs:element name="ClientIP"
       type="xs:string"
       minOccurs="0"
      />
     <xs:element name="ProcessId"
       type="xs:integer"
       minOccurs="0"
      />
     <xs:element name="Environment"
       type="EnvironmentVariableList"
       minOccurs="0"
      />
     <xs:element name="WorkingDirectory"
       type="xs:string"
       minOccurs="0"
       nillable="false"
      />
     <xs:element name="Lifetime"
       type="xs:duration"
       minOccurs="0"
      />
     <xs:element name="IdleTimeOut"
       type="xs:duration"
       minOccurs="0"
      />
     <xs:element name="InputStreams"
       type="StreamNameList"
       minOccurs="0"
      />
     <xs:element name="OutputStreams"
       type="StreamNameList"
       minOccurs="0"
      />
     <xs:element name="MaxIdleTimeOut"
       type="xs:duration"
       minOccurs="0"
      />
     <xs:element name="Locale"
       type="xs:string"
       minOccurs="0"
      />
     <xs:element name="DataLocale"
       type="xs:string"
       minOccurs="0"
      />
     <xs:element name="CompressionMode"
       type="xs:string"
       minOccurs="0"
      />
     <xs:element name="ProfileLoaded"
       type="xs:bolean"
       minOccurs="0"
      />
     <xs:element name="Encoding"
       type="xs:string"
       minOccurs="0"
      />
     <xs:element name="BufferMode"
       type=" OutputBufferingModeEnumeration"
       minOccurs="0"
      />
     <xs:element name="State"
       type="StateType"
       minOccurs="0"
      />
     <xs:element name="ShellRunTime"
       type="xs:duration"
       minOccurs="0"
      />
     <xs:element name="ShellInactivity"
       type="xs:duration"
       minOccurs="0"
      />
     <xs:any
       minOccurs="0"
       maxOccurs="unbounded"
       namespace="##other"
      />
   </xs:sequence>
 </xs:complexType>

Elements

ShellId: An xs:anyURI value that identifies the Shell. An optional element used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information, see section 3.1.4.2.1).

Name: An optional xs:string value that, if present, MUST contain a user-friendly name for the shell. There are no uniqueness requirements for this value.

ResourceURI: An optional xs:anyURI value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information, see section 3.1.4.2.1) that, if present, MUST match the ResourceUri used to create the shell.

Owner: An optional xs:string value that identifies the user account under which the Shell was created. An optional element used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section 3.1.4.2.1).

ClientIP: An optional xs:string value that identifies the IP address of the client machine that issued the initial wst:Create request that created the Shell. An optional element used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section 3.1.4.2.1).

ProcessId: An optional xs:integer value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see 3.1.4.2.1) that indicates the ID of the process hosting the shell instance.

Environment: Contains a sequence of EnvironmentVariable elements, the starting set of environment variables that the Shell will use.

WorkingDirectory: An xs:string value that MUST contain the starting directory that the Shell is to use for initialization.

Lifetime: An optional quota setting that configures the maximum time, in seconds, that the Remote Shell will stay open. The time interval is measured beginning from the time that the service receives a wst:Create request for a Remote Shell. The maximum allowed value MUST be 0x7FFFFFFF. The minimum allowed value MUST be 0. This configuration setting is used by the Shell Lifetime timer, as specified in section 3.1.5.

IdleTimeOut: An optional idle time-out for the Shell. The value MUST be expressed in milliseconds. The service SHOULD close and terminate the shell instance if it is idle for this much time. If the Shell is reused within this time limit, the countdown timer is reset once the command sequence is completed.<23>

InputStreams: A simple token list of all input streams the client will be using during execution. The only supported stream is "stdin". There is no requirement that the client make use of it. However, the client MUST NOT later attempt to send a named stream "stdin" if it is not specified in the wst:Create message. For example, if the client knows that "stdin" will not be used during the session, the client can specify an empty rsp:InputStreams element or omit it entirely. However, if the client anticipates that the "stdin" stream can be used, it MUST include the name in the list. If it is specified, there is no requirement that the client actually use it during the session.

OutputStreams: A simple token list of all output streams expected by the client. The supported streams are "stdout" and "stderr". There is no requirement that the client make all of them available output streams. For example, if the client only needs "stdout" during the session, it can list "stdout" as the sole stream of interest. If a stream is specified, there is no requirement that the client actually use it during the session.

MaxIdleTimeOut: An optional xs:duration value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section 3.1.4.2.1) that indicates the maximum IdleTimeOut that can be set on the shell instance.

Locale: An optional xs:string value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section 3.1.4.2.1) that indicates the [RFC3066] language code of the UI locale used by the shell instance.

DataLocale: An optional xs:string value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section3.1.4.2.1) that indicates the [RFC3066] language code of the UI locale used by the shell instance.

CompressionMode: An optional xs:string value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section3.1.4.2.1) that indicates the algorithm, if any, used by the protocol to compress Send and ReceiveResponse messages (for more information, see 3.1.4.1.31.6).

ProfileLoaded: An optional xs:boolean value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section3.1.4.2.1) that indicates whether the user profile is loaded within the shell instance (see the WINRS_NOPROFILE option specified in section for more information (section 3.1.4.5.2).

Encoding: An optional xs:string value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section3.1.4.2.1) that indicates the encoding of the protocol messages used when creating the shell instance.

BufferMode: An optional xs:OutputBufferingModeEnumeration value that indicates whether the server will block or drop results from the plug-in while the client is disconnected from the shell.

State: An optional xs:StateType value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section3.1.4.2.1) that indicates whether the shell instance is connected to any client.

ShellRunTime: An optional xs:duration value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section3.1.4.2.1) that identifies the amount of time that has elapsed since the Shell was created. The value MUST be expressed in seconds. An optional element used in the wst:GetResponse message (for more information, see section 3.1.4.2.1).

ShellInactivity: An optional xs:duration value used in the wst:CreateResponse message (for more information, see section 3.1.4.5.2) and wst:GetResponse message (for more information see section3.1.4.2.1) that identifies the amount of time that has elapsed since the Shell has been idle. The value MUST be expressed in seconds. An optional element used in the wst:GetResponse message (for more information, see section 3.1.4.2.1).

In addition to the preceding standardized initialization parameters, the open content model for the rsp:Shell body allows individual shells to have any additional XML content required for initialization.<24>

2.2.4.37 Shell

Additional resources