New-PSSession Configuration File

Syntax

New-PSSessionConfigurationFile
   [-Path] <String>
   [-SchemaVersion <Version>]
   [-Guid <Guid>]
   [-Author <String>]
   [-Description <String>]
   [-CompanyName <String>]
   [-Copyright <String>]
   [-SessionType <SessionType>]
   [-TranscriptDirectory <String>]
   [-RunAsVirtualAccount]
   [-RunAsVirtualAccountGroups <String[]>]
   [-MountUserDrive]
   [-UserDriveMaximumSize <Int64>]
   [-GroupManagedServiceAccount <String>]
   [-ScriptsToProcess <String[]>]
   [-RoleDefinitions <IDictionary>]
   [-RequiredGroups <IDictionary>]
   [-LanguageMode <PSLanguageMode>]
   [-ExecutionPolicy <ExecutionPolicy>]
   [-PowerShellVersion <Version>]
   [-ModulesToImport <Object[]>]
   [-VisibleAliases <String[]>]
   [-VisibleCmdlets <Object[]>]
   [-VisibleFunctions <Object[]>]
   [-VisibleExternalCommands <String[]>]
   [-VisibleProviders <String[]>]
   [-AliasDefinitions <IDictionary[]>]
   [-FunctionDefinitions <IDictionary[]>]
   [-VariableDefinitions <Object>]
   [-EnvironmentVariables <IDictionary>]
   [-TypesToProcess <String[]>]
   [-FormatsToProcess <String[]>]
   [-AssembliesToLoad <String[]>]
   [-Full]
   [<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 file name 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 Windows PowerShell sessions ( PSSessions ) that connect to, or terminate at, 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 in addition to 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 ( http://go.microsoft.com/fwlink/?LinkID=145152 ) and about_Session_Configuration_Files ( http://go.microsoft.com/fwlink/?LinkID=236023 ).

This cmdlet was introduced in Windows PowerShell 3.0.

Examples

Example 1: Designing a specialized session

PS C:\> New-PSSessionConfigurationFile -ModulesToImport DMSCmdlets, *Microsoft* -ScriptsToProcess \\Server01\Scripts\Get-DMSServers.ps1

The following command creates a session configuration file for IT technical sessions on a cloud-based document management server.

You can use the resulting file to create a customized session configuration on the server. The ACLs on the session configuration determine who can use the session configuration to create a session on the server.

Customized sessions that include the cmdlets, functions and scripts that technical users need make it easier for those users to write scripts that automate common tasks.

Example 2: Restricting Language in a Session

The first pair of commands uses the **New-PSSessionConfigurationFile** cmdlet to create two session configuration files. The first command creates a no-language file. The second command creates a restricted-language file. Other than the value of the *LanguageMode* parameter, the session configuration files are equivalent.

PS C:\> New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage

PS C:\> New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode RestrictedLanguage



The second pair of commands uses the configuration files to create session configurations on the local computer.

PS C:\> Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force

PS C:\> Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force



The third pair of commands creates two sessions, each of which uses one of the session configurations that were created in the previous command pair.

PS C:\> $NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage

PS C:\> $RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage



The seventh command uses the Invoke-Command cmdlet to run an If statement in the no-Language session. The command fails, because the language elements in the command are not permitted in a no-language session.

PS C:\> Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"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





The eighth command uses the **Invoke-Command** cmdlet to run the same If statement in the restricted-language session. Because these language elements are permitted in the restricted-language session, the command succeeds.

PS C:\> Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} }

Before

The commands in this example compare a no-language session to a restricted-language session. The example shows the effect of using the LanguageMode parameter of New-PSSessionConfigurationFile to limit the types of commands and statements that users can run in a session that uses a custom session configuration.

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

Example 3: Changing a Session Configuration File

The first command uses the **New-PSSessionConfigurationFile** cmdlet to create a session configuration file that imports the required modules.

PS C:\> New-PSSessionConfigurationFile -Path .\New-ITTasks.pssc -ModulesToImport Microsoft*, ITTasks, PSScheduledJob



The second command uses the **Set-PSSessionConfiguration** cmdlet to replace the current .pssc file with the new one. Changes to the session configuration affects all sessions created after the change is completed.

PS C:\> Set-PSSessionConfiguration -Name ITTasks -Path .\New-ITTasks.pssc

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

Example 4: Editing a Session Configuration File

The first command uses the Get-PSSessionConfiguration command to get the path of the configuration file for the ITConfig session configuration. The path is stored in the **ConfigFilePath** property of the session configuration.

PS C:\> (Get-PSSessionConfiguration -Name ITConfig).ConfigFilePath

C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\ITConfig_1e9cb265-dae0-4bd3-89a9-8338a47698a1.pssc



To modify the session configuration copy of the configuration file, you might have to change the file permissions.In this case, the current user, who is a member of the Administrators group on the system, was explicitly granted full control of the file by using the following method: Right-click the file icon, and then click Properties. On the Security tab, click Edit, and then click Add. Add the user, and then, in the Full control column, click Allow.Now the user can modify the file. A new slst alias for the Select-String cmdlet is added to the file.

PS C:\> AliasDefinitions = @(@{Name='slst';Value='Select-String'})



The second command uses the Test-PSSessionConfigurationFile cmdlet to test the edited file. The command uses the *Verbose* parameter, which displays the file errors that the cmdlet detects, if any.In this case, the cmdlet returns $True, which indicates that it did not detect any errors in the file.

PS C:\> Test-PSSessionConfigurationFile -Path (Get-PSSessionConfiguration -Name ITConfig).ConfigFilePath

True

This example shows how to change a session configuration by editing the active session configuration copy of the configuration file.

Example 5: Sample Configuration File

PS C:\> New-PSSessionConfigurationFile

-Path .\SampleFile.pssc

-Schema "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"

-RunAsVirtualAccount

-RunAsVirtualAccountGroups "Backup Operators"



                       @{

# 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 Windows 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.

Required Parameters

Optional Parameters

Inputs

None

You cannot pipe any objects to this cmdlet.

Outputs

None

This cmdlet does not generate any output.

Notes

• The Visible 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, either by using Windows PowerShell ISE or 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