Server Setup

PSWebApi.OwinSample is a Quick Start Example, it can be used as a scaffold for customizing your own PS-WebApi Server.

The main controller PSWebApiController shows how to use the two main extension methods this.InvokePowerShell(script.LocalFullPath(), allParameters) and this.InvokeCmd(script.LocalFullPath(), allArguments, ConfigHelper.CmdTimeoutSeconds) brought from nugget package https://www.nuget.org/packages/DataBooster.PSWebApi. You can leave this controller as it is if no need to enhance at present.

The only one configuration item that must be customized is the ScriptRoot in the Web.config. The ScriptRoot item is used to indicate a physical location for hosting all the PowerShell Scripts and batch/executable files, those files can be organized under any deep subdirectories. For example,

<configuration>
  <appSettings>
    <add key="ScriptRoot" value="D:\user-script-root\" />
  </appSettings>
</configuration>

Then, any command-line program (main entry is .exe, .bat or .ps1) been copied into (under) the ScriptRoot directory (D:\user-script-root\) becomes Web API (RESTful service) out of the box. The request URL should be http://base-uri/.../relative_path_from_ScriptRoot (Note that all back-slashes \ in physical path need to be replaced by forward-slashes / in the URL, and the ... part depends on your URL routing policy defined in Startup.cs).

You should have an enterprise authorization (access control) service to be integrated with the PS-WebApi service in your organization. The join-point is reserved in CustomAuthorizeAttribute.cs:

    public partial class CustomAuthorizeAttribute : AuthorizeAttribute
    {
        ...

        private bool CheckPrivilege(string script, string user)
        {
            // TO DO, please implement your own authorization logic here.

            return true;	// If allow permission
            return false;	// If deny permission
        }
    }

CheckPrivilege(string script, string user):

• script parameter will receive above relative_path_from_ScriptRoot;
• user parameter will be the authenticated user name of current HTTP client.

HTTP Client

Request-URI

If there is a PowerShell script "D:\user-script-root\Dept1\ps\test\demo1.ps1", the HTTP client should call it by URL like http://base-uri/ps.json/Dept1/ps/test/demo1.ps1?p1=1&=arg....
If there is a batch file "D:\user-script-root\Dept1\bat\test\demo2.bat", the HTTP client should call it by URL like http://base-uri/cmd/Dept1/bat/test/demo2.bat?=1&=arg....
Calling executable file follows the same pattern as batch file.

Response MediaType

PowerShell

PowerShell has built-in support for JSON, XML, CSV, HTML and plain text media types. The desired content-type (media type) of a response can be required by Request-URI or the Accept request-header field. Request-URI has a higher priority.

1. The Request-URI way depends on how you register your URL Routing. As an example, the OwinSample Startup.cs leads to following patterns:

   • http://BaseUrl/ps.json/script-path.ps1 ==> Media-type: application/json
   • http://BaseUrl/ps.xml/script-path.ps1 ==> Media-type: application/xml
   • http://BaseUrl/ps.csv/script-path.ps1 ==> Media-type: text/csv
   • http://BaseUrl/ps.html/script-path.ps1 ==> Media-type: text/html
   • http://BaseUrl/ps.string/script-path.ps1 ==> Media-type: text/plain
   • http://BaseUrl/ps.null/script-path.ps1 ==> HTTP 204 - NoContent

2. The Accept request-header can also be used to specify certain media types which are desired for the response. Use the URL http://BaseUrl/ps/script-path.ps1 with following request-header:

   • Accept: application/json
     or
     Accept: text/json
   • Accept: application/xml
     or
     Accept: text/xml
   • Accept: text/csv
     or
     Accept: application/csv
   • Accept: text/html
     or
     Accept: application/xhtml
   • Accept: text/plain
   • Accept: application/null

Batch/Executable

• http://BaseUrl/cmd/batch-or-executable-path.bat

  Since neither Batch-Program nor Console-Application would return an object, the response content-type is always text/plain.

  The response body presents the text in the standard output (stdout) stream if the program runs successfully with a 0 ExitCode and the standard error (stderr) stream is empty; Otherwise, the response body presents the text in stderr or exception messages with a HTTP 500 Internal Error header.

Parameters and Arguments

Parameters and arguments can be carried through either URI query-string or message body, or both.
JSON is the only one recognizable media-type in the request body, please always include the "Content-Type: application/json" or "Content-Type: text/json" in your request header if the request contains a body.
If both request body and query-string are supplied, the query-string parts (parameters and arguments) will be taken into the command line first, then append the body parts (parameters and arguments).

PowerShell

1. From URI query-string

   All the name/value pairs in query-string are passed to PowerShell. Empty name and duplicate names are acceptable in query-string. Empty-named parameters will be converted to arguments. For the following Uri example:

   test-args.ps1?np1=0.618&np1=2.71828&=arg1...&=arg2...
   

   ==>

   test-args.ps1 `
   -np1 "0.618" `
   -np1 "2.71828" `
   "arg1..." `
   "arg2..."
   

   Get through Uri query-string, all the values are always string type.

2. From Body
   For the moment, PowerShell parameters/arguments can only accept a JSON object (which can be deserialized into a Dictionary<string,object>) from the request body. Any invalid JSON will be ignored without warning.

   • To add an argument (unnamed-parameter), please use an empty string or any-length white-space string as the key-name of a key/value pair.
     To have multiple arguments, please use different number of white-space as the key-name of key/value pairs.
   • To add multiple named-parameters with the same parameter name, please add different number of white-space before or after the actual parameter name as the key-name of key/value pairs, since a dictionary object cannot carry duplicate keys. When the server side receives the dictionary object, it will trim all leading and trailing white-space from the key-name before it pass to PowerShell. But the value parts will always remain as it is (no trim).
   • If a value is null and its key is null, empty or white-space; that key/value pair will be discarded together.

   For the following JSON example:

   {
       "named_param1": 3.14,
       "": "This is an argument (unnamed-parameter)",
       "np2": "Value 1 of 3",
       "np2 ": "Value 2 of 3",
       " np2 ": "Value 3 of 3",
       " ": " This is another argument "
   }
   

   ==>

   test-args.ps1 `
   -named_param1 3.14 `
   "This is an argument (unnamed-parameter)" `
   -np2 "Value 1 of 3" `
   -np2 "Value 2 of 3" `
   -np2 "Value 3 of 3" `
   " This is another argument "
   

Batch/Executable

Essentially, there is no concept of named-parameter in batch/executable world. Command line can only supply string-typed arguments. There are some different treatments on arguments from PowerShell.

1. From URI query-string
   Each name/value pair will be split into two arguments. For examples:

   • test-args.bat?/n1=value1 is equivalent to test-args.bat?=/n1&=value1
     (both result to the same command line: test-args.bat /n1 value1)
   • test-args.bat?-n2=value2 is equivalent to test-args.bat?=-n2&=value2
     (both result to the same command line: test-args.bat -n2 value2)

2. From Body
   Three kinds of JSON data can be accepted as command line arguments. Each request can use one of a kind in the message body:

   • JSON Object (Dictionary<string,object>)
     Similar to URI query-string, JSON Object is an unordered set of name/value pairs. Each name/value pair basically will be split into two arguments. All leading and trailing white-space will be trimmed from the name. If the name becomes empty, it won't be added into the command line as an argument. But the value part won't be trimmed. Any type other than string will be converted into a string by ToString() method (null value will become an empty string ""). A null value will be discarded only when its name is null, empty or white-space.
     For Example,

     {
         "/n1": 3.14,
         "-n2": "Value 1 of 2",
         "-n2 ": "Value2of2",
         " ": null,
         "": " This is the last argument "
     }
     

     ==>

     test-args.bat /n1 3.14 -n2 "Value 1 of 3" -n2 Value2of3 " This is the last argument "
     

   • JSON Array
     Using a JSON Array is most straightforward way, each item in the array will be passed to command line as arguments (no trim); null value will become an empty string "" (enclosed by double quotes).

     For example,

     [