The Windows PowerShell ISE

The Windows PowerShell Integrated Scripting Environment (ISE) is a host application for Windows PowerShell. In the ISE, you can run commands and write, test, and debug scripts in a single Windows-based graphic user interface. The ISE provides multiline editing, tab completion, syntax coloring, selective execution, context-sensitive help, and support for right-to-left languages. Menu items and keyboard shortcuts are mapped to many of the same tasks that you would do in the Windows PowerShell console. For example, when you debug a script in the ISE, you can right-click on a line of code in the edit pane to set a breakpoint.

Support

The ISE was first introduced with Windows PowerShell V2 and was re-designed with PowerShell V3. The ISE is supported in all supported versions of Windows PowerShell up to and including Windows PowerShell V5.1.

The PowerShell ISE is no longer in active feature development. As a shipping component of Windows, it continues to be officially supported for security and high-priority servicing fixes. We currently have no plans to remove the ISE from Windows.

There is no support for the ISE in PowerShell v6 and beyond. Users looking for replacement for the ISE should use Visual Studio Code with the PowerShell Extension.

Key Features

Key features in Windows PowerShell ISE include:

• Multiline editing: To insert a blank line under the current line in the Command pane, press SHIFT + ENTER .
• Selective execution: To run part of a script, select the text you want to run, and then click the Run Script button. Or, press F5 .
• Context-sensitive help: Type Invoke-Item , and then press F1 . The Help file opens to the article for the Invoke-Item cmdlet.

The Windows PowerShell ISE lets you customize some aspects of its appearance. It also has its own Windows PowerShell profile script.

To start the Windows PowerShell ISE

Click Start, select Windows PowerShell, and then click Windows PowerShell ISE. Alternately, you can type powershell_ise.exe in any command shell or in the Run box.

To get Help in the Windows PowerShell ISE

On the Help menu, click Windows PowerShell Help. Or, press F1 . The file that opens describes Windows PowerShell ISE and Windows PowerShell, including all the help available from the Get-Help cmdlet.

Starting Windows PowerShell

Windows PowerShell is a scripting engine .DLL that’s embedded into multiple hosts. The most common hosts you’ll start are the interactive command-line powershell.exe and the Interactive Scripting Environment powershell_ise.exe .

To start Windows PowerShellВ® on Windows ServerВ® 2012 R2, WindowsВ® 8.1, Windows Server 2012, and Windows 8, see Common Management Tasks and Navigation in Windows.

PowerShell Core has renamed binary

PowerShell Core, referred to as PowerShell, is version 6 and higher that’s open source and uses .NET Core. Supported versions are available on Windows, macOS, and Linux.

Beginning in PowerShell 6, the PowerShell binary was renamed pwsh.exe for Windows and pwsh for macOS and Linux. You can start PowerShell preview versions using pwsh-preview . For more information, see What’s New in PowerShell Core 6.0 and About pwsh.

To find cmdlet reference and installation documentation for PowerShell 7, use the following links:

Document	Link
Cmdlet reference	PowerShell Module Browser
Windows installation	Installing PowerShell Core on Windows
macOS installation	Installing PowerShell Core on macOS
Linux installation	Installing PowerShell Core on Linux

To view content for other PowerShell versions, see How to use the PowerShell documentation.

How to Start Windows PowerShell on Earlier Versions of Windows

This section explains how to start Windows PowerShell and Windows PowerShell Integrated Scripting Environment (ISE) on WindowsВ® 7, Windows ServerВ® 2008 R2, and Windows ServerВ® 2008. It also explains how to enable the optional feature for Windows PowerShell ISE in Windows PowerShell 2.0 on Windows ServerВ® 2008 R2 and Windows ServerВ® 2008.

Use any of the following methods to start the installed version of Windows PowerShell 3.0, or Windows PowerShell 4.0, where applicable.

From the Start Menu

• Click Start, type PowerShell, and then click Windows PowerShell.
• From the Start menu, click Start, click All Programs, click Accessories, click the Windows PowerShell folder, and then click Windows PowerShell.

At the Command Prompt

In cmd.exe, Windows PowerShell, or Windows PowerShell ISE, to start Windows PowerShell, type:

You can also use the parameters of the powershell.exe program to customize the session. For more information, see PowerShell.exe Command-Line Help.

With Administrative privileges (Run as administrator)

Click Start, type PowerShell, right-click Windows PowerShell, and then click Run as administrator.

How to Start Windows PowerShell ISE on Earlier Releases of Windows

Use any of the following methods to start Windows PowerShell ISE.

From the Start Menu

• Click Start, type ISE, and then click Windows PowerShell ISE.
• From the Start menu, click Start, click All Programs, click Accessories, click the Windows PowerShell folder, and then click Windows PowerShell ISE.

At the Command Prompt

In cmd.exe , Windows PowerShell, or Windows PowerShell ISE, to start Windows PowerShell, type:

With Administrative privileges (Run as administrator)

Click Start, type ISE, right-click Windows PowerShell ISE, and then click Run as administrator.

How to Enable Windows PowerShell ISE on Earlier Releases of Windows

In Windows PowerShell 4.0 and Windows PowerShell 3.0, Windows PowerShell ISE is enabled by default on all versions of Windows. If it isn’t already enabled, Windows Management Framework 4.0 or Windows Management Framework 3.0 enables it.

In Windows PowerShell 2.0, Windows PowerShell ISE is enabled by default on Windows 7. However, on Windows Server 2008 R2 and Windows Server 2008, it’s an optional feature.

To enable Windows PowerShell ISE in Windows PowerShell 2.0 on Windows Server 2008 R2 or Windows Server 2008, use the following procedure.

To enable Windows PowerShell Integrated Scripting Environment (ISE)

1. Start Server Manager.
2. Click Features and then click Add Features.
3. In Select Features, click Windows PowerShell Integrated Scripting Environment (ISE).

Starting the 32-Bit Version of Windows PowerShell

When you install Windows PowerShell on a 64-bit computer, Windows PowerShell (x86), a 32-bit version of Windows PowerShell is installed in addition to the 64-bit version. When you run Windows PowerShell, the 64-bit version runs by default.

However, you might occasionally need to run Windows PowerShell (x86), such as when you’re using a module that requires the 32-bit version or when you’re connecting remotely to a 32-bit computer.

To start a 32-bit version of Windows PowerShell, use any of the following procedures.

What is PowerShell?

PowerShell is a cross-platform task automation solution made up of a command-line shell, a scripting language, and a configuration management framework. PowerShell runs on Windows, Linux, and macOS.

Shell

PowerShell is modern command shell that includes the best features of other popular shells. Unlike most shells that only accept and return text, PowerShell accepts and returns .NET objects. The shell includes the following features:

• Robust command-line history
• Tab completion and command prediction (See about_PSReadLine)
• Supports command and parameter aliases
• Pipeline for chaining commands
• In-console help system, similar to Unix man pages

Scripting language

As a scripting language, PowerShell is commonly used for automating the management of systems. It is also used to build, test, and deploy solutions, often in CI/CD environments. PowerShell is built on the .NET Common Language Runtime (CLR). All inputs and outputs are .NET objects. No need to parse text output to extract information from output. The PowerShell scripting language includes the following features:

• Extensible through functions, classes, scripts, and modules
• Extensible formatting system for easy output
• Extensible type system for creating dynamic types
• Built-in support for common data formats like CSV, JSON, and XML

Configuration management

PowerShell Desired State Configuration (DSC) is a management framework in PowerShell that enables you to manage your enterprise infrastructure with configuration as code. With DSC, you can:

• Create declarative configurations and custom scripts for repeatable deployments
• Enforce configuration settings and report on configuration drift
• Deploy configuration using push or pull models

Next steps

Getting started

Are you new to PowerShell and don’t know where to start? Take a look at these resources.

PowerShell in action

Take a look at how PowerShell is being used in different scenarios and on different platforms.

About Scripts

Short description

Describes how to run and write scripts in PowerShell.

Long description

A script is a plain text file that contains one or more PowerShell commands. PowerShell scripts have a .ps1 file extension.

Running a script is a lot like running a cmdlet. You type the path and file name of the script and use parameters to submit data and set options. You can run scripts on your computer or in a remote session on a different computer.

Writing a script saves a command for later use and makes it easy to share with others. Most importantly, it lets you run the commands simply by typing the script path and the filename. Scripts can be as simple as a single command in a file or as extensive as a complex program.

Scripts have additional features, such as the #Requires special comment, the use of parameters, support for data sections, and digital signing for security. You can also write Help topics for scripts and for any functions in the script.

How to run a script

Before you can run a script on Windows, you need to change the default PowerShell execution policy. Execution policy does not apply to PowerShell running on non-Windows platforms.

The default execution policy, Restricted , prevents all scripts from running, including scripts that you write on the local computer. For more information, see about_Execution_Policies.

The execution policy is saved in the registry, so you need to change it only once on each computer.

To change the execution policy, use the following procedure.

At the command prompt, type:

The change is effective immediately.

To run a script, type the full name and the full path to the script file.

For example, to run the Get-ServiceLog.ps1 script in the C:\Scripts directory, type:

To run a script in the current directory, type the path to the current directory, or use a dot to represent the current directory, followed by a path backslash ( .\ ).

For example, to run the ServicesLog.ps1 script in the local directory, type:

If the script has parameters, type the parameters and parameter values after the script filename.

For example, the following command uses the ServiceName parameter of the Get-ServiceLog script to request a log of WinRM service activity.

As a security feature, PowerShell does not run scripts when you double-click the script icon in File Explorer or when you type the script name without a full path, even when the script is in the current directory. For more information about running commands and scripts in PowerShell, see about_Command_Precedence.

Run with PowerShell

Beginning in PowerShell 3.0, you can run scripts from File Explorer.

To use the «Run with PowerShell» feature:

Run File Explorer, right-click the script filename and then select «Run with PowerShell».

The «Run with PowerShell» feature is designed to run scripts that do not have required parameters and do not return output to the command prompt.

Running scripts on other computers

To run a script on one or more remote computers, use the FilePath parameter of the Invoke-Command cmdlet.

Enter the path and filename of the script as the value of the FilePath parameter. The script must reside on the local computer or in a directory that the local computer can access.

The following command runs the Get-ServiceLog.ps1 script on the remote computers named Server01 and Server02.

Get help for scripts

The Get-Help cmdlet gets the help topics for scripts as well as for cmdlets and other types of commands. To get the help topic for a script, type Get-Help followed by the path and filename of the script. If the script path is in your Path environment variable, you can omit the path.

For example, to get help for the ServicesLog.ps1 script, type:

How to write a script

A script can contain any valid PowerShell commands, including single commands, commands that use the pipeline, functions, and control structures such as If statements and For loops.

To write a script, open a new file in a text editor, type the commands, and save them in a file with a valid filename with the .ps1 file extension.

The following example is a simple script that gets the services that are running on the current system and saves them to a log file. The log filename is created from the current date.

To create this script, open a text editor or a script editor, type these commands, and then save them in a file named ServiceLog.ps1 .

Parameters in scripts

To define parameters in a script, use a Param statement. The Param statement must be the first statement in a script, except for comments and any #Require statements.

Script parameters work like function parameters. The parameter values are available to all of the commands in the script. All of the features of function parameters, including the Parameter attribute and its named arguments, are also valid in scripts.

When running the script, script users type the parameters after the script name.

The following example shows a Test-Remote.ps1 script that has a ComputerName parameter. Both of the script functions can access the ComputerName parameter value.

To run this script, type the parameter name after the script name. For example:

For more information about the Param statement and the function parameters, see about_Functions and about_Functions_Advanced_Parameters.

Writing help for scripts

You can write a help topic for a script by using either of the two following methods:

Comment-Based Help for Scripts

Create a Help topic by using special keywords in the comments. To create comment-based Help for a script, the comments must be placed at the beginning or end of the script file. For more information about comment-based Help, see about_Comment_Based_Help.

XML-Based Help for Scripts

Create an XML-based Help topic, such as the type that is typically created for cmdlets. XML-based Help is required if you are translating Help topics into multiple languages.

To associate the script with the XML-based Help topic, use the .ExternalHelp Help comment keyword. For more information about the ExternalHelp keyword, see about_Comment_Based_Help. For more information about XML-based help, see How to Write Cmdlet Help.

Returning an exit value

By default, scripts do not return an exit status when the script ends. You must use the exit statement to return an exit code from a script. By default, the exit statement returns 0 . You can provide a numeric value to return a different exit status. A nonzero exit code typically signals a failure.

On Windows, any number between [int]::MinValue and [int]::MaxValue is allowed.

On Unix, only positive numbers between [byte]::MinValue (0) and [byte]::MaxValue (255) are allowed. A negative number in the range of -1 through -255 is automatically translated into a positive number by adding 256. For example, -2 is transformed to 254 .

In PowerShell, the exit statement sets the value of the $LASTEXITCODE variable. In the Windows Command Shell (cmd.exe), the exit statement sets the value of the %ERRORLEVEL% environment variable.

Any argument that is non-numeric or outside the platform-specific range is translated to the value of 0 .

Script scope and dot sourcing

Each script runs in its own scope. The functions, variables, aliases, and drives that are created in the script exist only in the script scope. You cannot access these items or their values in the scope in which the script runs.

To run a script in a different scope, you can specify a scope, such as Global or Local, or you can dot source the script.

The dot sourcing feature lets you run a script in the current scope instead of in the script scope. When you run a script that is dot sourced, the commands in the script run as though you had typed them at the command prompt. The functions, variables, aliases, and drives that the script creates are created in the scope in which you are working. After the script runs, you can use the created items and access their values in your session.

To dot source a script, type a dot (.) and a space before the script path.

After the UtilityFunctions.ps1 script runs, the functions and variables that the script creates are added to the current scope.

For example, the UtilityFunctions.ps1 script creates the New-Profile function and the $ProfileName variable.

If you run the UtilityFunctions.ps1 script in its own script scope, the New-Profile function and the $ProfileName variable exist only while the script is running. When the script exits, the function and variable are removed, as shown in the following example.

When you dot source the script and run it, the script creates the New-Profile function and the $ProfileName variable in your session in your scope. After the script runs, you can use the New-Profile function in your session, as shown in the following example.

For more information about scope, see about_Scopes.

Scripts in modules

A module is a set of related PowerShell resources that can be distributed as a unit. You can use modules to organize your scripts, functions, and other resources. You can also use modules to distribute your code to others, and to get code from trusted sources.

You can include scripts in your modules, or you can create a script module, which is a module that consists entirely or primarily of a script and supporting resources. A script module is just a script with a .psm1 file extension.

For more information about modules, see about_Modules.

Other script features

PowerShell has many useful features that you can use in scripts.

#Requires — You can use a #Requires statement to prevent a script from running without specified modules or snap-ins and a specified version of PowerShell. For more information, see about_Requires.

$PSCommandPath — Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is introduced in PowerShell 3.0.

$PSScriptRoot — Contains the directory from which a script is being run. In PowerShell 2.0, this variable is valid only in script modules ( .psm1 ). Beginning in PowerShell 3.0, it is valid in all scripts.

$MyInvocation — The $MyInvocation automatic variable contains information about the current script, including information about how it was started or «invoked.» You can use this variable and its properties to get information about the script while it is running. For example, the $MyInvocation .MyCommand.Path variable contains the path and filename of the script. $MyInvocation .Line contains the command that started the script, including all parameters and values.

Beginning in PowerShell 3.0, $MyInvocation has two new properties that provide information about the script that called or invoked the current script. The values of these properties are populated only when the invoker or caller is a script.

PSCommandPath contains the full path and name of the script that called or invoked the current script.

PSScriptRoot contains the directory of the script that called or invoked the current script.

Unlike the $PSCommandPath and $PSScriptRoot automatic variables, which contain information about the current script, the PSCommandPath and PSScriptRoot properties of the $MyInvocation variable contain information about the script that called the current script.

Data sections — You can use the Data keyword to separate data from logic in scripts. Data sections can also make localization easier. For more information, see about_Data_Sections and about_Script_Internationalization.

Script Signing — You can add a digital signature to a script. Depending on the execution policy, you can use digital signatures to restrict the running of scripts that could include unsafe commands. For more information, see about_Execution_Policies and about_Signing.