New-PSSessionConfigurationFile

Syntax

New-PSSessionConfigurationFile
   [-Path] <String>
   [-SchemaVersion <Version>]
   [-Guid <Guid>]
   [-Author <String>]
   [-CompanyName <String>]
   [-Copyright <String>]
   [-Description <String>]
   [-PowerShellVersion <Version>]
   [-SessionType <SessionType>]
   [-ModulesToImport <Object[]>]
   [-AssembliesToLoad <String[]>]
   [-VisibleAliases <String[]>]
   [-VisibleCmdlets <String[]>]
   [-VisibleFunctions <String[]>]
   [-VisibleProviders <String[]>]
   [-AliasDefinitions <Hashtable[]>]
   [-FunctionDefinitions <Hashtable[]>]
   [-VariableDefinitions <Object>]
   [-EnvironmentVariables <Object>]
   [-TypesToProcess <String[]>]
   [-FormatsToProcess <String[]>]
   [-LanguageMode <PSLanguageMode>]
   [-ExecutionPolicy <ExecutionPolicy>]
   [-ScriptsToProcess <String[]>]
   [<CommonParameters>]

Description

The New-PSSessionConfigurationFile cmdlet creates a file of settings that define a session configuration and the environment of sessions that are created by using the session configuration. To use the file in a session configuration, use the Path parameter of the Register-PSSessionConfiguration or Set-PSSessionConfiguration cmdlets.

The session configuration file that New-PSSessionConfigurationFile creates is a human-readable text file that contains a hash table of the session configuration properties and values. The file has a .pssc filename extension.

All parameters of New-PSSessionConfigurationFile are optional, except for the Path parameter. If you omit a parameter, the corresponding key in the session configuration file is commented-out, except where noted in the parameter description.

A session configuration, also known as an endpoint, is a collection of settings on the local computer that define the environment for PowerShell sessions (PSSessions) that connect to the computer. All PSSessions use a session configuration. To specify a particular session configuration, use the ConfigurationName parameter of cmdlets that create a session, such as the New-PSSession cmdlet.

A session configuration file makes it easy to define a session configuration without complex scripts or code assemblies. The settings in the file are used with the optional startup script and any assemblies in the session configuration.

For more information about session configurations and session configuration files, see about_Session_Configurations and about_Session_Configuration_Files.

This cmdlet was introduced in PowerShell 3.0.

Examples

Example 1: Creating and using a NoLanguage session

This example show how to create and the effects of using a no-language session.

The steps include:

1. Create a new configuration file.
2. Register the configuration.
3. Create a new session that uses the configuration.
4. Run commands in that new session.

To run the commands in this example, start PowerShell by using the Run as administrator option. This option is required to run the Register-PSSessionConfiguration cmdlet.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force
$NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage
Invoke-Command -Session $NoLanguage -ScriptBlock { if ((Get-Date) -lt '1January2099') {'Before'} else {'After'} }

The syntax is not supported by this runspace. This might be because it is in no-language mode.
    + CategoryInfo          : ParserError: (if ((Get-Date) ...') {'Before'}  :String) [], ParseException
    + FullyQualifiedErrorId : ScriptsNotAllowed
    + PSComputerName        : localhost

In this example, the Invoke-Command fails because the LanguageMode is set to NoLanguage.

Example 2: Creating and using a RestrictedLanguage session

This example show how to create and the effects of using a no-language session.

The steps include:

1. Create a new configuration file.
2. Register the configuration.
3. Create a new session that uses the configuration.
4. Run commands in that new session.

To run the commands in this example, start PowerShell by using the Run as administrator option. This option is required to run the Register-PSSessionConfiguration cmdlet.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode RestrictedLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name RestrictedLanguage -Force
$NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage
Invoke-Command -Session $NoLanguage -ScriptBlock { if ((Get-Date) -lt '1January2099') {'Before'} else {'After'} }

Before

In this example, the Invoke-Command succeeds because the LanguageMode is set to RestrictedLanguage.

Example 3: Changing a Session Configuration File

This example shows how to change the session configuration file that is used in an existing session named "ITTasks". Previously, these sessions had only the core modules and an internal ITTasks module. The administrator wants to add the PSScheduledJob module to sessions created by using the ITTasks session configuration.

New-PSSessionConfigurationFile -Path .\New-ITTasks.pssc -ModulesToImport Microsoft*, ITTasks, PSScheduledJob
Set-PSSessionConfiguration -Name ITTasks -Path .\New-ITTasks.pssc

The New-PSSessionConfigurationFile cmdlet to create a session configuration file that imports the required modules. The Set-PSSessionConfiguration cmdlet replaces the current configuration file with the new one. This new configuration only affects new sessions created after the change. Existing "ITTasks" sessions are not affected.

Example 4: Editing a Session Configuration File

This example shows how to change a session configuration by editing the active session configuration copy of the configuration file. To modify the session configuration copy of the configuration file, you must have full control access to the file. This may require you to change the permissions on the file.

In this scenario, we want to add a new alias for the Select-String cmdlet by editing the active configuration file.

The example code below performs the following steps to make this change:

1. Get the configuration file path for the ITConfig session.
2. The user edits the configuration file using Notepad.exe to change the AliasDefinitions value as follows: AliasDefinitions = @(@{Name='slst';Value='Select-String'}).
3. Test the updated configuration file.

$ITConfig = Get-PSSessionConfiguration -Name ITConfig
notepad.exe $ITConfig.ConfigFilePath
Test-PSSessionConfigurationFile -Path $ITConfig.ConfigFilePath

True

Use the Verbose parameter with Test-PSSessionConfigurationFile to display any errors that are detected. The cmdlet returns $True if no errors are detected in the file.

Example 5: Create a sample configuration file

This example shows a New-PSSessionConfigurationFile command that uses all the cmdlet parameters. It is included to show the correct input format for each parameter.

The resulting SampleFile.pssc is displayed in the output.

$configSettings = @{
    Path = '.\SampleFile.pssc'
    SchemaVersion = '1.0.0.0'
    Author = 'User01'
    Copyright = '(c) Fabrikam Corporation. All rights reserved.'
    CompanyName = 'Fabrikam Corporation'
    Description = 'This is a sample file.'
    ExecutionPolicy = 'AllSigned'
    PowerShellVersion = '3.0'
    LanguageMode = 'FullLanguage'
    SessionType = 'Default'
    EnvironmentVariables = @{TESTSHARE='\\Test2\Test'}
    ModulesToImport = @{ModuleName='PSScheduledJob'; ModuleVersion='1.0.0.0'; GUID='50cdb55f-5ab7-489f-9e94-4ec21ff51e59'},'PSDiagnostics'
    AssembliesToLoad = 'System.Web.Services','FSharp.Compiler.CodeDom.dll'
    TypesToProcess = 'Types1.ps1xml','Types2.ps1xml'
    FormatsToProcess = 'CustomFormats.ps1xml'
    ScriptsToProcess = 'Get-Inputs.ps1'
    AliasDefinitions = @{Name='hlp';Value='Get-Help';Description='Gets help.';Options='AllScope'},@{Name='Update';Value='Update-Help';Description='Updates help';Options='ReadOnly'}
    FunctionDefinitions = @{Name='Get-Function';ScriptBlock={Get-Command -CommandType Function};Options='ReadOnly'}
    VariableDefinitions = @{Name='WarningPreference';Value='SilentlyContinue'}
    VisibleAliases = 'c*','g*','i*','s*'
    VisibleCmdlets = 'Get*'
    VisibleFunctions = 'Get*'
    VisibleProviders = 'FileSystem','Function','Variable'
}
New-PSSessionConfigurationFile @configSettings
Get-Content SampleFile.pssc

@{

# Version number of the schema used for this configuration file
SchemaVersion = '1.0.0.0'

# ID used to uniquely identify this session configuration
GUID = 'f7039ffa-7e54-4382-b358-a393c75c30d3'

# Specifies the execution policy for this session configuration
ExecutionPolicy = 'AllSigned'

# Specifies the language mode for this session configuration
LanguageMode = 'FullLanguage'

# Initial state of this session configuration
SessionType = 'Default'

# Environment variables defined in this session configuration
EnvironmentVariables = @{
    TESTSHARE='\\Test2\Test'
}

# Author of this session configuration
Author = 'User01'

# Company associated with this session configuration
CompanyName = 'Fabrikam Corporation'

# Copyright statement for this session configuration
Copyright = '(c) Fabrikam Corporation. All rights reserved.'

# Description of the functionality provided by this session configuration
Description = 'This is a sample file.'

# Version of the PowerShell engine used by this session configuration
PowerShellVersion = '3.0'

# Modules that will be imported
ModulesToImport = @{
    ModuleVersion='1.0.0.0'
    ModuleName='PSScheduledJob'
    GUID='50cdb55f-5ab7-489f-9e94-4ec21ff51e59'
}, 'PSDiagnostics'

# Assemblies that will be loaded in this session configuration
AssembliesToLoad = 'System.Web.Services', 'FSharp.Compiler.CodeDom.dll'

# Aliases visible in this session configuration
VisibleAliases = 'c*', 'g*', 'i*', 's*'

# Cmdlets visible in this session configuration
VisibleCmdlets = 'Get*'

# Functions visible in this session configuration
VisibleFunctions = 'Get*'

# Providers visible in this session configuration
VisibleProviders = 'FileSystem', 'Function', 'Variable'

# Aliases defined in this session configuration
AliasDefinitions = @(
@{
    Description='Gets help.'
    Name='hlp'
    Options='AllScope'
    Value='Get-Help'
},
@{
    Description='Updates help'
    Name='Update'
    Options='ReadOnly'
    Value='Update-Help'
}
)

# Functions defined in this session configuration
FunctionDefinitions = @(
@{
    Name='Get-Function'
    Options='ReadOnly'
    ScriptBlock={Get-Command -CommandType Function}
}
)

# Variables defined in this session configuration
VariableDefinitions = @(
@{
    Value='SilentlyContinue'
    Name='WarningPreference'

# Type files (.ps1xml) that will be loaded in this session configuration
TypesToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Types1.ps1xml', 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Types2.ps1xml'

# Format files (.ps1xml) that will be loaded in this session configuration
FormatsToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\CustomFormats.ps1xml'

# Specifies the scripts to execute after the session is configured
ScriptsToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Get-Inputs.ps1'
}

This example displays a New-PSSessionConfigurationFile command that uses all of the cmdlet parameters. It is included to show the correct input format for each parameter.

The resulting SampleFile.pssc is displayed in the output.

Parameters

-AliasDefinitions

-AssembliesToLoad

-Author

-CompanyName

-Copyright

-Description

-EnvironmentVariables

-ExecutionPolicy

-FormatsToProcess

-FunctionDefinitions

-Guid

-LanguageMode

-ModulesToImport

-Path

-PowerShellVersion

-SchemaVersion

-ScriptsToProcess

-SessionType

-TypesToProcess

-VariableDefinitions

-VisibleAliases

-VisibleCmdlets

-VisibleFunctions

-VisibleProviders

Inputs

None

You cannot pipe any objects to this cmdlet.

Outputs

None

This cmdlet does not generate any output.

Notes

• Parameters, such as VisibleCmdlets and VisibleProviders, do not import items into the session. Instead, they select from among the items imported into the session. For example, if the value of the VisibleProviders parameter is the Certificate provider, but the ModulesToImport parameter does not specify the Microsoft.PowerShell.Security module that contains the Certificate provider, the Certificate provider is not visible in the session.

• New-PSSessionConfigurationFile creates a session configuration file that has a .pssc file name extension in the path that you specify in the Path parameter. When you use the session configuration file to create a session configuration, the Register-PSSessionConfiguration cmdlet copies the configuration file and saves an active copy of the file in the SessionConfig subdirectory of the $PSHOME directory.

  The ConfigFilePath property of the session configuration contains the fully qualified path of the active session configuration file. You can modify the active configuration file in the $PSHOME directory at any time using any text editor. The changes that you make affect all new sessions that use the session configuration, but not existing sessions.

  Before using an edited session configuration file, use the Test-PSSessionConfigurationFile cmdlet to verify that the configuration file entries are valid.

Related Links

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• Register-PSSessionConfiguration
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan Provider
• about_Session_Configurations
• about_Session_Configuration_Files