PrimalScript - Help Manual

The Script Packager contains everything you need to customize your executable files and create a package.

To open Packager Settings and configure a script package

1.Click Deploy on the ribbon, then click Settings in the Packager section to open the Script Packager interface:

2.Select the desired settings in the Script Packager interface (see details below):

•Script Engine

•Output Settings

•Restrictions

•Version Information

•Build Commands

 

Script Engine

Target Platform

The Script Packager provides four options for building executables:

•Microsoft Windows 32 Bit will generate a 32 bit excecutable.

•Microsoft Windows 64 Bit will generate a 64 bit executable.

•Microsoft Windows 32 and 64 Bit will generate a 32 bit and a 64 bit executable.

•Microsoft Windows Native will create a starter executable which will launch the correct version depending on the current platform.

Select the desired platform from the options in the Target drop-down list:

 

Script Engines

Each script engine option provides a preview of what the selection will do:

 Each package contains only one engine type. To include more than one script type in an executable file, create an MSI file.

STA Mode

 

Output Settings

Output Settings Options

 

Engine Settings

The packaged executable files are generated in a platform specific folder under a common folder. It is recommended that you leave the common folder default name of "bin" for consistency:

The build target you select will determine the platform specific folder that the packaged file(s) are generated in:

•32 bit files will be in bin\x86

•64 bit files will be in bin\x64

•32 bit and 64 bit files will be in their respective folders (bin\x86 and bin\x64)

•Windows Native executables will be in bin\Any platform

 

Choosing the Windows Native option will generate three .exe files:

o<app>x86.exe and <app>x64.exe are your actual packaged script.

o<app>.exe is a starter application that will execute the right package for the current platform.

You must install or deploy all three files together for your application to work. The starter application will receive the same icon, digital signature, and manifest as the packaged files, so a shortcut to <app>.exe will create the same experience.

 If you select both Windows Native and Generate .config file, then .config files will be generated for all three of the .exe files.

 

External Scripts

Select Resolve and include external scripts to deploy dot sourced files with the executable. If this option is enabled, the code of the external scripts will get injected into the packaged script when building the executable.

•Files specified with or without single and double quotes are supported. Files that do not exist will issue a warning. If you have a dot source statement inside a comment block, the file will be inserted into the comment block.

•Using a line comment will prevent a file from being resolved.

•If you need to resolve only some but not all external files, you can use a different case for the file extension:

o./include/lib.ps1 will be resolved by the packager.

o./include/lib.PS1 will not be resolved.

In other words, the statement is case sensitive; the actual filename's case is not relevant.

 

Alternate Credentials

By default, the scripts in a package run in the security context of the user who runs the package. You can specify alternate credentials (a username and password) that will be used to run the scripts.

The alternate credentials you supply must be available (either as local or domain accounts) on any computer where the packaged executable will run. Also, the credentials must generally have local administrator privileges on the computer where the package will run.

Alternate Credentials options:

•Username

Username of the specified user that will run the scripts in the package.

 To specify a domain, use username@domainname format, not domain\user format. Do not specify a domain or computer name for local accounts.

•Password

Password of the specified user that will run the scripts in the package.

•Run Mode

Select the user profile that will run the scripts in the package.

oCurrent user

Runs scripts with the security context of the current user, in the current user's environment.

oImpersonate user

Runs scripts with the security context of the specified user, in the current user's environment.

oRunAs user

Runs scripts with the security context of the specified user, in the specified user's environment

Elevate Regular User to Full Administrator

This section explains how to package a script as an executable, with the objective of allowing a regular user to accomplish a task that requires full administrator privileges.

Some background:

Since Windows Vista, the Administrator security token is split—you cannot simply logon as Admin and do anything you need to do. An Admin must elevate in order to accomplish certain tasks (e.g., when accessing or modifying certain system areas). This has ramifications for packaging executables—you cannot successfully use a run mode of RunAs or Impersonation, and also elevate at the same time.

When selecting RunAs or Impersonation:

•The specified credentials are stored inside the packaged executable, encrypted.

•When the packaged executable is launched, it uses certain API calls to create a new security token (Impersonation) or run itself with the specified credentials (RunAs). The executable needs to load and execute in order for this to happen.

When selecting a manifest for elevation:

•The manifest is embedded in the executable—unencrypted—because Windows needs to read this information.

•Windows will load and evaluate this manifest before any code is executed. If you run this from a regular user, you will be prompted for Admin credentials and also to verify elevation. The credentials stored inside the package have no effect at this point because they would only be applied after the fact.

Essentially, due to the way Windows evaluates manifests, elevation happens before RunAs / Impersonation—but it needs to be the other way around to avoid prompts and to not give regular users Admin privileges. The Script Packager accomplishes this via a two-step process:

1.Starter.exe—a simple script packaged as an executable that includes; the Admin credentials, a run mode of either RunAs or Impersonation, and instructions to launch your script.

2.Your script—packaged as an executable, with a manifest for elevation.

Using this process, Starter.exe will launch and use the specified Admin credentials, and then your script will run with elevation.

 Depending on your local settings, you may get a prompt to allow your script to modify your system, but it will not prompt you for actual credentials.

 

Restrictions

Use the Restrictions to limit the environment in which the package runs.

 When restricted to a specific version, the executables display the expected and encountered versions in the error message.

 

Version Information

Use the Version Information settings to specify characteristics of the current version of the executable file.

 The version number must be in #.#.#.# format.

 

Build Commands

Use the Build Commands to define custom commands to run before or after packaging.

 The commands will be executed in the sequence defined; one after the other, rather than in parallel.

Use the four buttons at the top-right of each section to manage the pre- and post-packaging commands:

From left to right:

• Add File - Browses for a file / exe.

• Remove - Removes the command.

• Move Up - Moves the command up in the order.

• Move Down - Moves the command down in the order.

 

 

See also:

Creating a Script Package

PrimalScript Editor

Script Debugger

Getting Help