Information in this document is subject to change without notice. The example companies, organizations, products, people, and events depicted herein are fictitious. No association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarked, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

This source code is subject to terms and conditions of the Apache License, Version 2.0. A copy of the license can be found in the License.html file at the root of this distribution. If you cannot locate the Apache License, Version 2.0, please send an email to ironpy@microsoft.com. By using this source code in any fashion, you are agreeing to be bound by the terms of the Apache License, Version 2.0.

PowerShell from IronPython

A brief example which utilizes managed Windows PowerShell APIs to run shell commands directly from IronPython.

Overview

PowerShell (PS) is a new command-line shell for Windows which provides some pretty dramatic improvements over its predecessor - the DOS prompt. The most important new feature PS provides as far as IronPython is concerned is a set of managed interfaces accessible via the Common Language Runtime. We can tap directly into these from IronPython.

Utilizing PS from IronPython offers quite a bit more to developers than the standard Python modules used to run commands, manipulate the filesystem, etc. This sample includes two Python scripts, each of which are designed to determine if your host meets some of the minimum system requirements to play the game "Age of Empires III Trial Edition". What sets these two scripts apart is that the first script, minsysreq_ps.py, leverages a helper module, powershell.py, to obtain PS functionality in a very useful and object-oriented way. The second script, minsysreq.py, uses PS commands directly to achieve the same results.

Note: the scripts distributed with this sample collect various performance and runtime info about your PC and emit this to the console for your own personal use.  None of this information is transmitted to Microsoft.

Prerequisites

The prerequisites to successfully run the PowerShell from IronPython demo are:

• IronPython 2.6 distribution
  • If you are new to IronPython, please go over the tutorial that comes with this distribution
  • Download from here
• Windows PowerShell 2.0
  • Needed to access the managed PS APIs
  • Download from here
• Age of Empires III Trial Edition (Optional)
  • Run this while executing the minsysreq* scripts distributed with this sample to get runtime info about Age of Empires III
  • This step is entirely optional. The sample scripts will still run without installing Age of Empires III!
  • Download from here

Getting Started

Please make sure the sample folder IPPowerShell (where this readme.htm is located) contains at least the following:

.\minsysreq.py

.\minsysreq_ps.py

.\powershell.py

HINT: if the folder containing the IronPython distribution is not already in your PATH environment variable, please add it from the command prompt you'll be working in.  By doing this you will be able to run the "ipy" command from any arbitrary directory:

set PATH=%PATH%;%ProgramFiles%\IronPython 2.6

Using powershell.py from an Interactive IronPython Session

From the command prompt, navigate to the IPPowerShell directory and type the following command:

> ipy.exe -i powershell.py

This starts an interactive IronPython session and imports quite a few modules, functions, objects, etc. into the global namespace. Most importantly you should find a "shell" object. "shell" is an instance of the Shell class (defined within powershell.py) which in turn is a wrapper for the standard PS cmdlets and aliases. You should take special note that the conversion from PS to IronPython involved the following rules with respect to Shell's methods:

• for every PS cmdlet, there is a corresponding Shell method where the name is completely lowercase with "-"s translated into "_"s.  E.g., the PS command "Get-Process" becomes the Shell method "shell.get_process()"

• for most simple PS aliases, there is a corresponding Shell method where the name is completely lowercase with "-"s translated into "_"s.  E.g., the PS alias "ls" becomes the Shell method "shell.ls()". Aliases that do not directly map into a corresponding PS cmdlet (such as "more") have no Shell method mapping.

• if a PS cmdlet accepts (non-parameter) arguments, they are supplied directly to the Shell method in the form of a single string parameter. E.g., the PS command "Write-Error "Some error message here..."" would become "shell.write_error("Some error message here...")"

• cmdlet parameters are mapped as keyword parameters of Shell methods.  E.g., the PS command "Get-Date -DisplayHint date" becomes the Shell method "shell.get_date(DisplayHint='date')"

• the return value from one cmdlet can be piped in as the input to another cmdlet. To do this, one just needs to invoke the 2nd cmdlet method on the return value of the first cmdlet.  E.g., the PS command "Get-Process ipy | ConvertTo-Html" becomes "shell.get_process("ipy").convertto_html()"

• properties of the return value object from a PS cmdlet are accessible as Python object attributes.  E.g., the PS command "Get-Process ipy | Select-Object -First 1 -Property WS" becomes "shell.get_process("ipy")[0].WS" 

Checking Minimum System Requirements for AOE III Trial Edition

Included with this sample are two scripts designed to automatically determine if your system is capable of playing Age of Empires III Trial Edition by using PS API(s) from IronPython. The first script, minsysreq_ps.py, uses the nice PS wrapper module powershell.py, while minsysreq.py uses the managed PS assembly directly to achieve the same goal. Furthermore, both scripts will emit some runtime information such as memory usage if AOE III is currently running. This serves as a nice example because the standard Python modules provide little support for obtaining this type of information.

To run these scripts it is necessary to issue the following commands from the IPPowerShell directory: "ipy.exe minisysreq_ps.py" and "ipy.exe minsysreq.py". The output for both of these scripts should be identical and similar to the following:

If you are already running AOE III, you'd also see the following extra output:

Please explore the contents of both scripts in the IPPowerShell directory to assist you in using PowerShell from your own IronPython scripts and modules!

This concludes our tutorial. Have fun playing with PowerShell from IronPython!