New-PSSessionConfigurationFile

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>]

L’applet New-PSSessionConfigurationFile de commande crée un fichier de paramètres qui définissent une configuration de session et l’environnement des sessions créées à l’aide de la configuration de session. Pour utiliser le fichier dans une configuration de session, utilisez le paramètre Path des applets de Register-PSSessionConfiguration commande ou Set-PSSessionConfiguration .

Le fichier de configuration de session créé New-PSSessionConfigurationFile est un fichier texte lisible par l’homme qui contient une table de hachage des propriétés et des valeurs de configuration de session. Le fichier a une extension de nom de .pssc fichier.

Tous les paramètres de New-PSSessionConfigurationFile sont facultatifs, à l’exception du paramètre Path . Si vous omettez un paramètre, la clé correspondante dans le fichier de configuration de session fait l’objet d’un commentaire, sauf indication contraire dans la description du paramètre.

Une configuration de session, également appelée point de terminaison, est un ensemble de paramètres sur l’ordinateur local qui définissent l’environnement des sessions PowerShell (PSSessions) qui se connectent à l’ordinateur. Toutes les PSSessions utilisent une configuration de session. Pour spécifier une configuration de session particulière, utilisez le paramètre ConfigurationName des applets de commande qui créent une session, telles que l’applet de New-PSSession commande.

Un fichier de configuration de session permet de définir facilement une configuration de session sans scripts complexes ni assemblages de code. Les paramètres du fichier sont utilisés avec le script de démarrage facultatif et tous les assemblys de la configuration de session.

Pour plus d’informations sur les configurations de session et les fichiers de configuration de session, consultez about_Session_Configurations et about_Session_Configuration_Files.

Cette applet de commande a été introduite dans PowerShell 3.0.

Cet exemple montre comment créer et les effets de l’utilisation d’une session sans langue.

Les étapes sont les suivantes :

1. Créez un nouveau fichier de configuration.
2. Enregistrez la configuration.
3. Créez une session qui utilise la configuration.
4. Exécutez des commandes dans cette nouvelle session.

Pour exécuter les commandes de cet exemple, démarrez PowerShell à l’aide de l’option Exécuter en tant qu’administrateur. Cette option est requise pour exécuter l’applet Register-PSSessionConfiguration de commande.

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

Dans cet exemple, le échoue car Invoke-Command est défini sur NoLanguage.

Cet exemple montre comment créer et les effets de l’utilisation d’une session sans langue.

Les étapes sont les suivantes :

1. Créez un nouveau fichier de configuration.
2. Enregistrez la configuration.
3. Créez une session qui utilise la configuration.
4. Exécutez des commandes dans cette nouvelle session.

Pour exécuter les commandes de cet exemple, démarrez PowerShell à l’aide de l’option Exécuter en tant qu’administrateur. Cette option est requise pour exécuter l’applet Register-PSSessionConfiguration de commande.

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

Dans cet exemple, le réussit car Invoke-Command est défini sur RestrictedLanguage.

Cet exemple montre comment modifier le fichier de configuration de session utilisé dans une session existante nommée « ITTasks ». Auparavant, ces sessions ne comportaient que les modules de base et un module interne ITTasks . L’administrateur souhaite ajouter le module PSScheduledJob aux sessions créées à l’aide de la configuration de session ITTasks.

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

Applet New-PSSessionConfigurationFile de commande permettant de créer un fichier de configuration de session qui importe les modules requis. L’applet Set-PSSessionConfiguration de commande remplace le fichier de configuration actuel par le nouveau. Cette nouvelle configuration n’affecte que les nouvelles sessions créées après la modification. Les sessions « ITTasks » existantes ne sont pas affectées.

Cet exemple montre comment modifier une configuration de session en modifiant la copie de configuration de session active du fichier de configuration. Pour modifier la copie de configuration de session du fichier de configuration, vous devez disposer d’un accès de contrôle total au fichier. Cela peut vous obliger à modifier les autorisations sur le fichier.

Dans ce scénario, nous souhaitons ajouter un nouvel alias pour l’applet Select-String de commande en modifiant le fichier de configuration actif.

L’exemple de code ci-dessous effectue les étapes suivantes pour effectuer cette modification :

1. Récupérez le chemin d’accès au fichier de configuration pour la session ITConfig.
2. L’utilisateur modifie le fichier de configuration à l’aide deNotepad.exe pour modifier la valeur AliasDefinitions comme suit : AliasDefinitions = @(@{Name='slst';Value='Select-String'}).
3. Testez le fichier de configuration mis à jour.

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

True

Utilisez le paramètre Verbose avec Test-PSSessionConfigurationFile pour afficher les erreurs détectées. L’applet de commande est renvoyée $True si aucune erreur n’est détectée dans le fichier.

Cet exemple montre une New-PSSessionConfigurationFile commande qui utilise tous les paramètres de l’applet de commande. Il est inclus pour afficher le format d’entrée correct pour chaque paramètre.

Le fichier SampleFile.pssc résultant s’affiche dans la sortie.

$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'
}

Cet exemple affiche une commande New-PSSessionConfigurationFile qui utilise tous les paramètres de l’applet de commande. Il est inclus pour afficher le format d’entrée correct pour chaque paramètre.

Le fichier SampleFile.pssc résultant s’affiche dans la sortie.

Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.

Vous ne pouvez pas rediriger d’objets vers cette applet de commande.

Cette applet de commande ne génère aucune sortie.

• Les paramètres, tels que VisibleCmdlets et VisibleProviders, n’importent pas d’éléments dans la session. Au lieu de cela, ils sélectionnent parmi les éléments importés dans la session. Par exemple, si la valeur du paramètre VisibleProviders est le fournisseur de certificats, mais que le paramètre ModulesToImport ne spécifie pas le module Microsoft.PowerShell.Security qui contient le fournisseur de certificats, le fournisseur de certificats n’est pas visible dans la session.

• New-PSSessionConfigurationFile crée un fichier de configuration de session dont le chemin d’accès est défini avec l’extension de nom de fichier .pssc. Lorsque vous utilisez le fichier de configuration de session pour créer une configuration de session, l’applet Register-PSSessionConfiguration de commande copie le fichier et enregistre une copie active du fichier dans le sous-répertoire SessionConfig du $PSHOME répertoire.

  La propriété ConfigFilePath de la configuration de session contient le chemin d’accès complet du fichier de configuration de session actif. Vous pouvez modifier le fichier de configuration actif dans le répertoire à tout moment à l’aide de n’importe $PSHOME quel éditeur de texte. Les modifications que vous apportez affectent toutes les nouvelles sessions qui utilisent la configuration de session, mais pas les sessions existantes.

  Avant d’utiliser un fichier de configuration de session modifié, utilisez l’applet Test-PSSessionConfigurationFile de commande pour vérifier que les entrées du fichier de configuration sont valides.