Constrained Runspaces

Host applications can restrict what is available when a runspace is opened. They can restrict the programming elements that are available to the user, the data that is available to the user, and the Windows PowerShell language elements that can be applied by the user. From the perspective of the user at the command line, these constrained runspaces will appear as a restricted version of Windows PowerShell.

For example, you can create a runspace that does not allow the user to call some of the cmdlets that are provided by Windows PowerShell, or you can create a runspace that restricts the Windows PowerShell language so that users cannot assign values to variables. For samples of implementations of constrained runspaces, see Windows PowerShell01 Sample and Runspace11 Sample.

Restricting Programming Elements

You can restrict the availability of aliases, applications, cmdlets, functions, scripts, providers, and variables within a runspace in two ways. You can define a runspace that has only those elements that you specify when opening the runspace, and you can define a runspace that has public and private elements. In this case only those elements that are public will be available to the user at the command line.

The following code shows how to define a runspace that has only those elements that are specified by the host application. The System.Management.Automation.Runspaces.InitialSessionState.Create method creates an initial session state that has no commands, and the Add method is used to add the commands that will be available in the runspace. When the runspace is opened using this initial session state, only those two commands will be available.

// Create an empty InitialSessionState and then add two commands. 
InitialSessionState iss = InitialSessionState.Create();

// Add the Get-Process and Get-Command cmdlets to the session state.
SessionStateCmdletEntry ssce1 = new SessionStateCmdletEntry(

SessionStateCmdletEntry ssce2 = new SessionStateCmdletEntry(

Another way to restrict the availability of programming elements is to make them private. Private elements can be used by the host application, or internally by another public element, but they cannot be used by the user at the command line.

For another example, suppose that a command has a parameter that is needed by your host application but you do not want to make that parameter available to the user. You can create a runspace that makes the base command private, and then you can create a proxy command without the parameter that is public. The user can run the proxy command, and the proxy command can use the base command. But the user cannot run the base command. Here is an example of creating a proxy command.

defaultSessionState = InitialSessionState.CreateDefault();
commandIndex = GetIndexOfEntry(defaultSessionState.Commands, "get-childitem");
defaultSessionState.Commands[commandIndex].Visibility = SessionStateEntryVisibility.Private;
CommandMetadata getChildItemMetadata = new CommandMetadata(
string getChildItemBody = ProxyCommand.Create(getChildItemMetadata);
defaultSessionState.Commands.Add(new SessionStateFunctionEntry("get-childitem2", getChildItemBody));
this.runspace = RunspaceFactory.CreateRunspace(defaultSessionState);

See Also

© 2014 Microsoft