This is the built-in help made by Microsoft for the document 'about_Session_Configuration_Files', in PowerShell version 4 - as retrieved from
Windows version 'Microsoft Windows 8.1 Enterprise' PowerShell help files on 2016-06-24.
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.
TOPIC
about_Session_Configuration_Files
SHORT DESCRIPTION
Describes session configuration files, which can be used in a
session configuration ("endpoint") to define the environment
of sessions that use the session configuration.
LONG DESCRIPTION
A "session configuration file" is a text file with a .pssc file name
extension that contains a hash table of session configuration
properties and values. You can use a session configuration file to
set the properties of a session configuration and, thereby, to define
the environment of Windows PowerShell sessions that use the session
configuration.
Session configuration files make it easy to design custom session
configurations without complex C# assemblies or scripts.
A "session configuration" or "endpoint" is a collection of settings
on the local computer that determine which users can create sessions
on the computer and which commands they can run in the sessions.
For more information about session configurations, see
about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152).
Session configurations were introduced in Windows PowerShell 2.0. Session
configuration files were introduced in Windows PowerShell 3.0. You must use
Windows PowerShell 3.0 to include a session configuration file in a
session configuration, but users of Windows PowerShell 2.0 and later are
affected by all settings in the session configuration.
Creating Custom Sessions
You can customize many features of a Windows PowerShell session by
specifying session properties in a session configuration. You can
customize a session by writing a C# program that defines a custom
runspace, or you can use a session configuration file to define the
properties of sessions that are created by using the session
configuration.
You can use a session configuration file to create fully functioning
sessions for highly trusted users, locked-down sessions for minimal
access, and sessions designed for particular tasks that contain only
the modules required for the task.
For example, you can determine whether users of the session can use
Windows PowerShell language elements, such as script blocks, or whether
they can only run commands. You can determine which version of Windows
PowerShell can run in the session, which modules are imported into the
session and which cmdlets, functions, and aliases session users can
run.
Creating a Session Configuration File
The easiest way to create a session configuration file is by using
the New-PSSessionConfiguration cmdlet. This cmdlet generates a file
with the correct syntax and format, and it verifies many of the
property values.
For detailed descriptions of the properties that you can set in a
session configuration file, see the help topic for the
New-PSSessionConfigurationFile cmdlet.
To create a session configuration file with the default values,
use the following command:
PS C:\> New-PSSessionConfigurationFile -Path .\Defaults.pssc
To open and view the file in your default text editor, use the
following command:
PS C:\> Invoke-Item -Path .\Defaults.pssc
To create a session configuration for sessions in which
user can run commands, but not use other elements of the Windows
PowerShell language, type:
PS C:\> New-PSSessionConfigurationFile -LanguageMode NoLanguage -Path .\NoLanguage.pssc
To create a session configuration for sessions in which users can
use only Get cmdlets, type:
PS C:\> New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc
Using a Session Configuration File
You can include a session configuration file when you create a session configuration
or add it to the session configuration at later time.
To include a session configuration file when creating a session configuration, use
the Path parameter of the Register-PSSessionConfiguration cmdlet.
The following command includes the NoLanguage.pssc file when it creates the NoLanguage
session configuration.
PS C:\> Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc
To add a session configuration file to an existing session configuration, use
the Path parameter of the Set-PSSessionConfiguration cmdlet. The change affects all
new sessions created with the session configuration after the command completes.
The following command adds the NoLanguage.pssc file to LockedDown session
configuration.
PS C:\> Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc
When users use the LockedDown session configuration to create a session, they can
run cmdlets, but they cannot create or use variables, assign values, or use other
Windows PowerShell language elements.
For example, the following command uses the New-PSSession cmdlet to create a
session on the local computer that uses the LockedDown session configuration.
The command saves the session in the $s variable. The ACL of the session
configuration determines who can use it to create a session.
PS C:\> $s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown
The following command uses the Invoke-Command cmdlet to run commands in the session
in the $s variable. The first command, which runs the Get-UICulture cmdlet, succeeds.
However, the second command, which gets the value of the $PSUICulture variable, fails.
PS C:\> Invoke-Command -Session $s {Get-UICulture}
en-US
PS C:\> Invoke-Command -Session $s {$PSUICulture}
The syntax is not supported by this runspace. This might be because it is in no-language mode.
+ CategoryInfo : ParserError: ($PSUICulture:String) [], ParseException
+ FullyQualifiedErrorId : ScriptsNotAllowed
Editing a Session Configuration File
To edit the session configuration file that is being used by a session
configuration, begin by locating the active copy of the session configuration
file.
When you use a session configuration file in a session configuration,
Windows PowerShell creates an active copy of the session configuration file
and stores it in the $pshome\SessionConfig directory on the local computer.
The location of the active copy of a session configuration file is stored
in the ConfigFilePath property of the session configuration object.
The following command gets the location of the session configuration file
for the NoLanguage session configuration.
PS C:\> (Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath
C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc
You can edit the file in any text editor. The file is changed as soon as
you save it and is effective in new sessions that use the session configuration.
Testing a Session Configuration File
Be sure to test all manually edited session configuration files. If the file
syntax and values are not valid, users will not be able to use the session
configuration to create a session.
For example, the following command tests the active session configuration
file of the NoLanguage session configuration.
PS C:\> Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc
You can use Test-PSSessionConfigurationFile to test any session configuration
file, including the files the New-PSSessionConfiguration creates. For more information,
see the help topic for the Test-PSSessionConfigurationFile cmdlet.
Removing a Session Configuration File
You cannot safely remove a session configuration file from a session configuration,
but you can replace the file with one that has no effect.
To remove a session configuration file, create a session configuration
file with the default settings and then use the Set-PSSessionConfiguration cmdlet
to replace the custom session configuration file with a default version.
For example, the following command creates a Default session configuration file
and then replaces the active session configuration file in the NoLanguage session
configuration.
PS C:\> New-PSSessionConfigurationFile -Path .\Default.pssc
PS C:\> Set-PSSessionConfiguration -Name NoLanguage -Path .\Default.pssc
As a result of this command the NoLanguage session configuration now provides
full language support (the default) in all sessions created with the session
configuration.
Viewing the Properties of a Session Configuration
The session configuration objects that represent session configurations that use
session configuration files have additional properties that make it easy to discover
and analyze the session configuration. (Note that the type name includes a formatted
view definition.)
PS C:\> Get-PSSessionConfiguration NoLanguage | Get-Member
TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration
Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
Architecture NoteProperty System.String Architecture=64
Author NoteProperty System.String Author=juneb
AutoRestart NoteProperty System.String AutoRestart=fals
Capability NoteProperty System.Object[] Capability=Sys
CompanyName NoteProperty System.String CompanyName=Unkn
configfilepath NoteProperty System.String configfilepath=C
Copyright NoteProperty System.String Copyright=(c) 20
Enabled NoteProperty System.String Enabled=True
ExactMatch NoteProperty System.String ExactMatch=true
ExecutionPolicy NoteProperty System.String ExecutionPolicy=
Filename NoteProperty System.String Filename=%windir
GUID NoteProperty System.String GUID=0c115179-ff
ProcessIdleTimeoutSec NoteProperty System.String ProcessIdleTimeo
IdleTimeoutms NoteProperty System.String IdleTimeoutms=72
lang NoteProperty System.String lang=en-US
LanguageMode NoteProperty System.String LanguageMode=NoL
MaxConcurrentCommandsPerShell NoteProperty System.String MaxConcurrentCom
MaxConcurrentUsers NoteProperty System.String MaxConcurrentUse
MaxIdleTimeoutms NoteProperty System.String MaxIdleTimeoutms
MaxMemoryPerShellMB NoteProperty System.String MaxMemoryPerShel
MaxProcessesPerShell NoteProperty System.String MaxProcessesPerS
MaxShells NoteProperty System.String MaxShells=300
MaxShellsPerUser NoteProperty System.String MaxShellsPerUser
Name NoteProperty System.String Name=NoLanguage
PSVersion NoteProperty System.String PSVersion=3.0
ResourceUri NoteProperty System.String ResourceUri=http
RunAsPassword NoteProperty System.String RunAsPassword=
RunAsUser NoteProperty System.String RunAsUser=
SchemaVersion NoteProperty System.String SchemaVersion=1.
SDKVersion NoteProperty System.String SDKVersion=1
OutputBufferingMode NoteProperty System.String OutputBufferingM
SessionType NoteProperty System.String SessionType=Defa
UseSharedProcess NoteProperty System.String UseSharedProcess
SupportsOptions NoteProperty System.String SupportsOptions=
xmlns NoteProperty System.String xmlns=http://sch
XmlRenderingType NoteProperty System.String XmlRenderingType
Permission ScriptProperty System.Object Permission {get=
The new properties make it easier to search session configurations. For example, you
can use the ExecutionPolicy property to find an session configuration that supports
sessions with the RemoteSigned execution policy. Because the ExecutionPolicy property
exists only on sessions that use session configuration files, the command might not
get all qualifying session configurations.
PS C:\> Get-PSSessionConfiguration | where {$_.ExecutionPolicy -eq "RemoteSigned"}
The following command gets session configurations in which the RunAsUser is the
Exchange administrator.
PS C:\> Get-PSSessionConfiguration | where {$_.RunAsUser -eq "Exchange01\Admin01"}
NOTES
An Empty session type is designed for you to create custom sessions with selected
commands. If you do not add modules, functions, or scripts to an empty session, the
session is limited to expressions and might not be usable.
SEE ALSO
about_Session_Configurations
New-PSSession
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
New-PSSessionConfigurationFile
Register-PSSessionConfiguration
Set-PSSessionConfiguration
Test-PSSessionConfigurationFile
Unregister-PSSessionConfiguration