Projects

PowerShell Studio projects help group related files and settings together. For example, a PowerShell utility might consist of several different Forms and Scripts. A project can keep these files together, whereas the PowerShell Studio packager can create an executable file that includes everything in the package.

Starting a Project

To create a project, click on the small triangle in the top left corner, next to the new menu on the ribbon bar:

Clicking on the new menu will create a new PowerShell script instead of a project.

Project Templates

There are a total of four project templates to choose from. Once you have chosen a template, specify the project name and choose a distinct folder to store the project files in.

Checking the 'Create Project Folder' option will ensure that your project files are stored in their own sub directory in the Projects folder, rather than mixing them together with files from other projects.

The default location for project files is:

%homepath%\Documents\SAPIEN\PowerShell Studio 2015\Projects

This path can be changed to reflect your environment in the General pane of the Options menu, under "Directories", as shown below.

Create

New projects are based on a template; PowerShell Studio provides four templates to choose from. All four options are described below.

Once you have chosen your template, you will need to provide the following information:

• Project name
  A name for your project.
• Location
  The folder in which you wish to store your project.
• Create Project Folder
  Select this option to store your project files in a new sub-folder named after your project. Uncheck this option if you want to store your project file in an existing folder.

PowerShell will create all of the files specified in the template and display them in the Project pane.

Project Templates

• Collection
  This project allows you to keep track of a group of files, which typically consists of (but not limited) to ps1 script files. There is no entry point in the project since these are individual files. All files within the project are considered 'content'. The Collection Project also allows you to group and deploy independent script files in an organized manner.
  
• Empty
  An empty project contains a single file called Startup.pss. It is used to create a script application. This script executes when the project is executed, and is a great place do any preparatory work before calling other scripts in the project.
  
• Form
  A form project contains three files.
  
  1. Globals.ps1
     A script file containing functions and variables that will be available throughout your project. Anything you define in this script will become global to the project.
  2. MainForm.psf
     An empty form in which you build the GUI for your script.
  3. Startup.pss
     The script that runs when your project is executed.

• Multi-Form
  A multi-form project is the same as a form project with the addition of another form called ChildForm.psf.
  
• Module
  A module project contains two files.
  1. SQLModule.psd1
     The manifest file for your module.
  2. SQLModule.psm1
     The PowerShell script code for your module.
  Notice below, that the files are named the same as the project:
  

New Module From Functions

You may find at times you reuse various functions and constantly copy them into new scripts or find different variations of the same function are located in different scripts. You may come to the conclusion that those functions would better serve you in the form of a module where all your scripts can reference the functions in a centralized location. This is where the New Module From Functions feature comes in handy.

The New Module From Functions allows you to import functions from various ps1 scripts and merge them into a new script module. When you select this project from the menu, it will ask you to select a file (if one is not already open) and present you with the following dialog:

Let's cover each field individually:

• Module Name
  Enter the name you wish to give your new module
• Location
  Specify the folder where the module will be saved. The default is PowerShell Studio's project directory.
• Create Module Folder
  This option creates a folder using the module's name and places all the generated files within that folder. This folder will be created in the folder specified by the Location field.
• Source Files
  Contains the list of files from which the selected functions will be extracted
• Add File
  Use the Add File button to add ps1 scripts to the Source Files, in order to extract their functions.
• Remove File
  Use the Remove File button to remove unnecessary files from the Source Files list. This can help de-clutter the functions list.
• Functions
  The functions section contains a node for each file and its respective list of functions that are declared in said file.
  
  Use this list to check the functions you wish to import into the new module. If a function references another function, it will have a Referenced Functions folder icon below that contains a list of all of the referenced functions.
  

 When you check a function in the list that has references, it will automatically check all the referenced functions as well.

 You can check and un-check all the functions in the file by checking/un-checking the file's node.

Create Module

Once you have selected the functions and specified a module name, you can press the Create Module button to generate the new module.

Note on duplicate functions: In some instances you may have a duplicate function that is defined in multiple files, PowerShell Studio will compare these functions and if they are identical, it will only insert the function once. If the functions are different, PowerShell Studio will automatically rename the duplicate. A warning will be displayed in the Output window when this occurs:

The new module project will contain three files:

1. Module Name.psd1
   Contains the module's manifest
2. Module Name.psm1
   Contains all the imported functions and an Export-ModuleMember cmdlet statement, which lists all of the imported functions.
   
3. Module Name.Help.xml
   Contains the PowerShell XML Help file for the module, generated using the imported functions.

Projects and Your Workflow

One of the most valuable uses for projects is managing development workflow. When using projects, you can develop entirely on your local machine, ensuring that your work-in-progress doesn't affect production users. When you're ready, the project can be deployed - by PowerShell Studio, as a single unit - to a production server where the project goes "live".

This contrasts with the common technique of editing files directly in production, such as on a web server. With this technique, changes are seen immediately by users, but so are mistakes. Editing "live" files directly is a very poor development practice. PowerShell Studio projects means that you don't ever need to edit live. Instead, it allows you to work on your local machine which serves as a development "sandbox" or test bed. You then deploy the completed, tested, and debugged files, into production.

Project Properties

Project properties are shown in the Property pane. You must first click on the project name, in the Project pane, for the results to show.

----->

There are two project level properties:

1. Project Name
   Allows you to change the project name.
2. Project Path
   The location where the project is stored. This is not an editable property.

Collection Project

If you have various ps1 scripts that dot source each other, you can now create a Collection Project to enjoy the following benefits:

• Being able to manage multiple files
• PrimalSense support for dot source files
• Apply rename refactoring on all your files.

When you first create a Collection Project, you will notice that there is no Startup.pss file. There is no entry point in the project since these are individual files. All files within the project are considered 'Content'.

You can run each file individually using the Project's context menu or using the usual Run Ribbon buttons (v4. 1.64 and up).

Deployment is handled on a project basis. You can deploy all the project files to a single destination or create an install that includes all the project files.

The project's packaging is restricted because there are all individual files.

Collection Project Deployment

These options accommodate your deployment needs by controlling the behavior of the Packager, MSI, and Deployment as a whole or as individual files.

• Deploy As
  This determines the deployment behavior of the Project as a whole. There are two Deploy As options to choose from:

  File

  Tells the project to handle each file individually when it comes to deployment. Each project file will maintain its own independent settings. When to use: Use this setting when you are using the Collection Project to group individual files that don't necessary interact with each other. With this setting, you can package and deploy (publish) each script independently.

  Project

  Tells the project to handle the deployment of all of the files as a whole. You must define a primary file for the purposes of the Packager and MSI builder. When to use: Use this setting when you have a group of files that interact and have a start/entry point script. For example, if you have a primary script that dot sources various secondary scripts. In this case, the primary script will get converted into an executable and you can create an installer that includes the primary packaged script and all of the supporting files/scripts. The project files are also deployed (published) as a whole.

• Primary File
  This property will tell the project which file is the primary file when Deploy As is set to Project. The primary file will be the file that is packaged into an executable. All other files will be considered external "Content".

Previously the deployment options were unavailable in the Collection Project unless you opened the files independent of the project.

These new deployment settings now allow the Collection Project to fit your deployment needs.

Managing Project Files

Project files are managed via the Project pane. Right clicking on the project name will display the project menu. Here you can run, rename, close, add existing/new files, add new folders, and navigate to the project folder in Windows Explorer.

Right clicking on a project file displays the file menu where you can open, rename, remove, delete, preview, debug, or run a file.

Project File Properties

File properties are shown in the Property pane. You must first click on the file name, in the Project pane, for the results to show.

----->

There are five project file properties:

1. Build
   This property determines what PowerShell Studio does with a file when you export a project. Three options are supported:
   1. Include
      The file is included in the export. The Command Extension and Reference Name properties are used to help integrate the file contents into the shell.
   2. Exclude
      The file will not be included in the export.
   3. Content
      The file will be included in the export but any code contained in the file will not be integrated into the shell. This is a useful option when you want to include data files in your project.
2. Command Extension
   If set to true, any functions and variables defined in the file are added into the shell so that they can be used by other forms and scripts in the package.
3. File Path
   The location where the file is stored. This is not an editable property.
4. Name
   The name of the file can be edited here.
5. Reference Name
   If the Command Extension is set to false, this property provides a call function name that can be used to invoke the file from another part of the project. If Command Extension is set to true, this property is ignored.

Referencing Project Forms and Scripts (Call Functions)

The reference name property described above is used to create a Call Function that allows simple invocation of a project file. If you add a script file called Utilities.ps1 to a project and you examine its properties, you will see that PowerShell Studio has generated a Reference Name called Call-Utilities_ps1. You can use this name elsewhere in your project scripts to run the code in Utilities.ps1.

PowerShell Studio uses this method to load the first form in a project from the project startup script (Startup.pss).

Projects and Source Control

Projects can be managed as a unit through PowerShell Studio's source control integration. Source control integration must be configured first.

To work with source control, right-click the project name in the Project Pane.

• Add to source control
  Adds the project to source control.
• Check in
  Checks in one or more project files which have changed or not yet been checked in.

Individual files within the project can be checked in or out independently as well, although checking files in together - as a project - helps to simplify file and source control management.

Running a Project

There are two ways to run a project.

1. Click Run on the Run menu of the Home ribbon:
   
   The execution options you see will depend on the project type
2. Right-click on the project and choose one of the Run options:
   

Exporting a Project

Exporting a project converts the project into a single script file that contains all of your code, plus the auto-generated code produced by PowerShell Studio.

To export a project, navigate to Deploy on the ribbon bar and then to the Export menu, to choose where you would like to export your project - either to a file or to the clipboard.

Adding Script Parameters to Projects

Adding a Param block to the Startup.pss file allows you to provide startup parameters to your project when it runs. The runtime behavior depends on how the project is started. If you start your project from the console, then you provide parameter values on the command line, separated by spaces. If you are starting a Forms project, then PowerShell Studio will prompt you for the parameter values. If you package a project into an EXE file, then you must always provide startup parameters on the command line. You can also add Param blocks to forms and scripts in your project, as long as their Command Extension property is not set to true. Simply add a Param block to the beginning of the file and provide parameter values when you invoke the file.

For example, if we wanted to pass the current user's name to each form in our script, we could add a Param block to each form:

Then supply an appropriate value when we call the form:

Creating Script Modules

In the past, extra functionality for PowerShell was created by developers using Visual Studio, and delivered in the form of PowerShell Snap-ins. With the release of PowerShell v2.0, Microsoft introduced the capability to extend PowerShell via the use of Modules, which can now be created from PowerShell script code rather than C# or Visual Basic .Net.

A script module is a library of PowerShell functions delivered together for some common purpose. Microsoft Windows ships with a number of modules to address common requirements, for example: BitsTransfer, TroubleshootingPack, WebAdministration, etc. Script modules are a great way to create packaged, reusable utilities for your company, that can be installed anywhere they are required.

The Module Project template includes everything that you need to get started:

The psm1 file is where you define the functions that implement your module. A psm1 file is just a regular PowerShell script with a different extension. You add functions to the file in the same way that you would create a regular ps1 script file.

This module file contains two functions. When the module is loaded into PowerShell, both of these become available in the shell.

Sometimes you will add functions to a module solely to help other functions do their work. These 'helper' functions do not need to be visible to module users, and PowerShell provides a mechanism to accomplish this. In the example above, we do not need to share the function Get-UserName with our users. By calling Export-ModuleMember in our module, we can tell PowerShell what to reveal.

Here we have added the Export-ModuleMember call and specified that only Write-HelloWorld should be visible. Now when the module is imported, users only see one function:

Export-ModuleMember can also be used to make aliases, cmdlets and variables visible to module users.

The psd1 file is a module manifest file. It is used to provide extra metadata about a module including such things as:

• Module version number
• Author
• Description
• Prerequisites for executing the module - required PowerShell version, required CLR version, other modules and assemblies that must be present
• Export restrictions - lists of functions, variables, aliases and cmdlets to export.

Using a module manifest file allows you to cleanly separate your code from instructions and metadata about your code. It is the preferred way of working.

Form Return Variables

In order to simplify working with forms in a project, PowerShell Studio will create special variables that allow you to refer directly to a property of controls on a child form. These variables become available when you add a form call function into your code.

To demonstrate this, start by creating a new form project and add a button to the main form so that it looks like the screenshot below:

Now right click on the project node, and add a new file.

Choose Form and give it a name. Click Add.

Next, choose Dialog Style Template.

Add a textbox, called textbox1, to the new form so that it looks like the screenshot below:

Now return to the code for the main form and add the call helper function into the button click handler, so that it looks like the screenshot below:

At this point, PowerShell Studio will make the text property of the textbox in the child form, directly accessible in the main form, through a variable called $child_form_textbox1. You can use it in the code in the main form. An example of this is shown on the screenshot below:

These form return variables make it simple to gather the results from a data entry forms.

The controls that support this mechanism are summarized below, along with the type of data that they return.