# Environments

Environments allow you to define an executable, arguments, modules and variables to use when running scripts, hosting APIs and dashboards. 

Environments are stored within the `environments.ps1` file. 

## Configuring Environments

To configure environments, you can use the Settings \ Environments page. 

![Environments Page](https://3638551245-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M6jY7sXTmhiAIMGYw_m-887967055%2Fuploads%2FTxuS8kxZb2rE6JnHmrWw%2Fimage.png?alt=media\&token=0c73a500-7ea5-4d41-a3f3-918a0ada3b2b)

Environments support setting the name, path, arguments, modules and variables.

![](https://3638551245-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M6jY7sXTmhiAIMGYw_m%2F-MHG9V2esP9zAvDiSfX5%2F-MHGCdfKm47pzCwktTqz%2Fimage.png?alt=media\&token=1aef6356-7a2f-4b93-8da6-9a9f96937b71)

### Name 

The name of the environment. This name will be shown through out the rest of the platform when running scripts, configuring the API host environment and hosting dashboards. 

### Path and Arguments

Environments support defining a path to an executable and arguments for that executable. These should be either PowerShell.exe or Pwsh.exe. 

You can also define modules and variables. 

### Modules

The modules list allows you to define zero or more modules to load in the PowerShell runspaces for the environment. These modules will be part of the initial session state so they will not need to be loaded manually. Items added to this list can either be module names or full paths to module files. 

### Variables

The variables list allows you to define zero or more variables to load in the PowerShell runspaces for the environment. This list can consist of variable names from the [variable configuration](https://docs.powershelluniversal.com/master-1/platform/variables). 

You can also use wild cards (`*`) to bring in multiple variables that match a pattern.

### PSModulePath

You can use the `-PSModulePath` parameter of `New-PSUEnvironment` to configure additional PSModulePaths to include within the environment. 

### Runspace Recycling

{% hint style="info" %}
Available in PowerShell Universal 2.8 or later.
{% endhint %}

The `-RunspaceRecycling` parameter of `New-PSUEnvironment` will cause runspaces to be disposed and recreated periodically. This may increase CPU usage but reduce memory usage in some environments. 

### High Performance Runspace Pools

{% hint style="info" %}
Available in PowerShell Universal 2.9 or later.
{% endhint %}

High Performance Runspace Pools uses an alternate technique to pooling resources. They are much faster than pools traditionally used by PowerShell Universal. APIs and Dashboards support the use of these types of pools. 

High performance pools do not support debugging, persistence or runspace recycling. 

## Using Environments

Environments can be used across the platform. 

### APIs

To select the environment to use, modify the `settings.ps1` file and include the `-ApiEnvironment` parameter of `Set-PSUSetting`. It needs to be the name of the environment. 

### Automation

Each script, job and schedule can use an environment. You can define environments for scripts by modifying the `scripts.ps1` and setting the `-Environment` parameter of `New-PSUScript`. To set the environment of a schedule, set the `-Environment` parameter of `New-PSUSchedule` in `schedules.ps1`. When invoking a script, you can also choose an environment to use. 

### Dashboards

To use a particular environment for a dashboard, set the `-Environment` parameter of `New-PSUDashboard` in `dashboards.ps1`.

### Security

By default, authentication and authorization happen within the `Universal.Server.exe` process. To run these out of process, you can select an environment by setting the `-SecurityEnvironment` parameter of `Set-PSUSetting` in `settings.ps1`. 

## Integrated Environment

{% hint style="info" %}
The integrated environment does not support running as alternate credentials. 
{% endhint %}

The integrated environment uses the PowerShell Universal server process directly rather than starting external PowerShell processes to service requests. 

The integrated environment is easier to configure and use than having multiple disparate environments. You will also see a performance improvement because there is no need to serialize and communicate via interprocess communication. 

The downside is that you cannot elevate to alternate credentials or use alternate PowerShell versions. You will be using the current version of the PowerShell Universal server's PowerShell SDK. 

### Configuring

The integrated environment is always available and you do not need to configured it directly. If you do want to import modules or set up persistent runspaces, you can set settings for the integrated environment in `environments.ps1`. 

{% code title=".universal\environments.ps1" %}

```powershell
New-PSUEnvironment -Name 'Integrated' -Path 'none' -Modules @('ActiveDirectory')
```

{% endcode %}

### APIs

To set the integrated environment, you can use the `Set-PSUSetting` in `settings.ps1`. 

{% code title=".universal\settings.ps1" %}

```powershell
Set-PSUSetting -ApiEnvironment 'Integrated'
```

{% endcode %}

### Automation

You can assign the integrated environment to scripts and schedules. You can also set the integrated environment as the default environment for the platform. 

```powershell
Set-PSetting -DefaultEnvironment 'Integrated'
```

You can also choose the integrated environment from the run dialog. 

![](https://3638551245-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M6jY7sXTmhiAIMGYw_m%2F-MbHQWTcNDESbEoHNnH2%2F-MbHQwibCtS2hOZOFipE%2Fimage.png?alt=media\&token=39ede18f-0e44-48b0-bf26-b6d148d690c9)

### Dashboards

You can run dashboards in the integrated environment. Select the integrated environment from the environment drop down. 

![](https://3638551245-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M6jY7sXTmhiAIMGYw_m%2F-MbHQWTcNDESbEoHNnH2%2F-MbHQmplyZqqiUySrwHm%2Fimage.png?alt=media\&token=28e09056-f94e-4221-88a1-17388314405e)

### Module Support

The integrated environment works by creating multiple ruspaces within the PowerShell Universal service. Some modules do not work well when run within a single process. Below is a list of modules with known issues running within the integrated environment. 

* VMware.PowerCLI
* Az

## API

* [New-PSUEnvironment](https://github.com/ironmansoftware/universal-docs/blob/master/cmdlets/New-PSUEnvironment.txt)
* [Get-PSUEnvironment](https://github.com/ironmansoftware/universal-docs/blob/master/cmdlets/Get-PSUEnvironment.txt)
* [Remove-PSUEnvironment](https://github.com/ironmansoftware/universal-docs/blob/master/cmdlets/Remove-PSUEnvironment.txt)