PowerShell Logo Small

New-PSSessionConfigurationFile



This is the built-in help made by Microsoft for the command 'New-PSSessionConfigurationFile', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Creates a file that defines a session configuration.

SYNTAX


New-PSSessionConfigurationFile [-Path] <String> [-AliasDefinitions [<IDictionary[]>]] [-AssembliesToLoad [<String[]>]] [-Author [<String>]] [-CompanyName [<String>]]
[-Copyright [<String>]] [-Description [<String>]] [-EnforceInputParameterValidation] [-EnvironmentVariables [<IDictionary>]] [-ExecutionPolicy {Unrestricted | RemoteSigned |
AllSigned | Restricted | Default | Bypass | Undefined}] [-FormatsToProcess [<String[]>]] [-Full] [-FunctionDefinitions [<IDictionary[]>]] [-Guid [<Guid>]] [-LanguageMode
{FullLanguage | RestrictedLanguage | NoLanguage | ConstrainedLanguage}] [-ModulesToImport [<Object[]>]] [-MountUserDrive] [-PowerShellVersion [<Version>]] [-RoleDefinitions
[<IDictionary>]] [-RunAsVirtualAccount] [-RunAsVirtualAccountGroups [<String[]>]] [-SchemaVersion [<Version>]] [-ScriptsToProcess [<String[]>]] [-SessionType {Empty |
RestrictedRemoteServer | Default}] [-TranscriptDirectory [<String>]] [-TypesToProcess [<String[]>]] [-UserDriveMaximumSize [<Int64>]] [-VariableDefinitions [<Object>]]
[-VisibleAliases [<String[]>]] [-VisibleCmdlets [<Object[]>]] [-VisibleExternalCommands [<String[]>]] [-VisibleFunctions [<Object[]>]] [-VisibleProviders [<String[]>]]
[<CommonParameters>]



Search powershellhelp.space

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 parameters 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 (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 is introduced in Windows PowerShell 3.0.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=289597
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
New-PSSessionConfigurationFile
Register-PSSessionConfiguration
Set-PSSessionConfiguration
Test-PSSessionConfigurationFile
Unregister-PSSessionConfiguration
WSMan Provider
about_Session_Configurations
about_Session_Configuration_Files

REMARKS

<

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 with 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 completes.
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 with 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 to 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 edit the session configuration copy of the configuration file, you might need to edit 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 edit 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 ($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.