New-PSUEnvironment

Creates a new PowerShell Universal environment.

SYNOPSIS

Creates a new PowerShell Universal environment.

SYNTAX

New-PSUEnvironment -Name <String> [-Version <String>] [-Type <EnvironmentType>] [-Path <String>]
 [-Arguments <String>] [-Modules <String[]>] [-Variables <String[]>] [-PSModulePath <String[]>]
 [-StartupScript <String[]>] [-PersistentRunspace] [-RunspaceRecycling] [-MaxRunspaces <Int32>]
 [-MaxVirtualMemory <Int64>] [-RecycleSchedule <String>] [-Credential <Variable>] [-Description <String>]
 [-DisableImplicitWinCompat] [-Minimal] [-Disabled] [-ProcessStartupScript <String>] [-EnableDebugger]
 [-Verb <String>] [-ComputerName <String>] [-AppToken <String>] [-UseDefaultCredentials] [-Integrated]
 [-TrustCertificate] [-Cookies] [<CommonParameters>]

DESCRIPTION

Environments define PowerShell execution environments within PowerShell Universal. You can use them when executing APIs, Scripts, Dashboards and the security processes for authentication and authorization.

Environments are stored within the ./universal/environments.ps1 file.

You can also use this cmdlet to create environments through the REST API.

EXAMPLES

Example 1

PS C:\> New-PSUEnvironment -Name '7.1' -Path 'pwsh.exe'

Creates a new environment called 7.1 that uses the pwsh.exe for running APIs, scripts or dashboards.

Example 2

PS C:\> New-PSUEnvironment -Name '7.1' -Path 'pwsh.exe' -ArgumentList "-ExecutionPolicy Bypass"

Creates a new environment called 7.1 that uses the pwsh.exe executable and sets the execution policy to ByPass.

Example 3

PS C:\> New-PSUEnvironment -Name '7.1' -Path 'pwsh.exe' -ArgumentList "-ExecutionPolicy Bypass" -Variables @("*")

Creates a new environment that uses all the variables defined with New-PSUVariable.

Example 4

PS C:\> New-PSUEnvironment -Name '7.1' -Path 'pwsh.exe' -ArgumentList "-ExecutionPolicy Bypass" -Modules @("ActiveDirectory")

Creates a new environment that automatically loads the ActiveDirectory module.

Example 5

PS C:\> New-PSUEnvironment -Name '7.1' -Path 'pwsh.exe' -ArgumentList "-ExecutionPolicy Bypass" -PersistentRunspace

Creates a new environment that uses persistent runspaces. Persistent runspaces are used for APIs and do not reset between each execution.

PARAMETERS

-AppToken

The AppToken that is used for calling the PowerShell Universal Management API. You can also call Connect-PSUServer before calling this cmdlet to set the AppToken for the entire session.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Arguments

Arguments to pass to the PowerShell process when starting the environment.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ComputerName

Specifies the computer name or URL that should be called when accessing the PowerShell Universal Management API. You can also use Connect-PSUServer before calling this cmdlet to set the computer name for the entire session.

Type: String
Parameter Sets: (All)
Aliases: Uri

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Modules

Modules to automatically load when creating new runspaces in the environment.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Name

The name of the environment.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PSModulePath

Additional paths to add to the PSModulePath for the environment.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Path

The path to the PowerShell executable.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PersistentRunspace

Whether to enable persistent runspaces. This is only used for APIs.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Variables

Variables to import into the runspace. These are variables defined by New-PSUVariable.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-UseDefaultCredentials

Use default credentials when connecting to the management API

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Integrated

Executes the command internally rather than using the Management API. Only works when running script from within PowerShell Universal.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-StartupScript

A script to run when creating the runspaces in this environment.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Version

A version number to display.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-RunspaceRecycling

Whether to recycle runspaces. Runspaces will be recycled (disposed and recreated) after an amount of time or a number of uses.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-MaxRunspaces

The maximum number of runspaces to create for this environment.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-EnableDebugger

Enables the PowerShell debugging feature for this environment.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Credential

The credential to use with this environment

Type: Variable
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-MaxVirtualMemory

The maximum virtual memory in bytes. When the threshold is reached, the process is restarted. Ignored for the integrated environment.

Type: Int64
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-RecycleSchedule

A CRON schedule to restart this environment. Ignored for the integrated environment.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Description

A description for this environment.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-DisableImplicitWinCompat

Disables Windows PowerShell Implicit Compatibility mode.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Minimal

A minimal environment that does not load any modules or variables.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ProcessStartupScript

A script that runs once when the process starts. This is not run for each runspace.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Disabled

Environment is disabled.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TrustCertificate

Whether the cmdlet should ignore certificate issues.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Type

The type of environment. PowerShell 7 and Windows PowerShell 5.1 are supported. Use Custom to create a custom environment

Type: EnvironmentType
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Verb

The verb to use when creating the process for this environment. This is not used for the integrated environment.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Cookies

Reuses and persists authentication cookies for the current PowerShell session.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -Verbose, -WarningAction, -WarningVariable, and -ProgressAction. For more information, see about_CommonParameters.

INPUTS

None

OUTPUTS

System.Object

NOTES

RELATED LINKS

New-PSUVariable