This is the built-in help made by Microsoft for the command 'New-PSSessionConfigurationFile', in PowerShell version 3 - as retrieved from
Windows version 'Microsoft Windows Server 2012 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.
Creates a file that defines a session configuration.
New-PSSessionConfigurationFile [-Path] <String> [-AliasDefinitions <Hashtable[]>] [-AssembliesToLoad <String[]>] [-Author <String>]
[-CompanyName <String>] [-Copyright <String>] [-Description <String>] [-EnvironmentVariables <Object>] [-ExecutionPolicy <ExecutionPolicy>]
[-FormatsToProcess <String[]>] [-FunctionDefinitions <Hashtable[]>] [-Guid <Guid>] [-LanguageMode <PSLanguageMode>] [-ModulesToImport
<Object[]>] [-PowerShellVersion <Version>] [-SchemaVersion <Version>] [-ScriptsToProcess <String[]>] [-SessionType <SessionType>]
[-TypesToProcess <String[]>] [-VariableDefinitions <Object>] [-VisibleAliases <String[]>] [-VisibleCmdlets <String[]>] [-VisibleFunctions
<String[]>] [-VisibleProviders <String[]>] [<CommonParameters>]
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.
<
Online Version: http://go.microsoft.com/fwlink/?LinkID=217036
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
New-PSSessionConfigurationFile
New-PSSessionConfigurationOption
Register-PSSessionConfiguration
Set-PSSessionConfiguration
Test-PSSessionConfigurationFile
Unregister-PSSessionConfiguration
WSMan Provider
about_Session_Configurations
about_Session_Configuration_Files
<
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"
@{
# 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.
PS C:\>