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

El New-PSSessionConfigurationFile cmdlet crea un archivo de configuración que define una configuración de sesión y el entorno de las sesiones que se crean mediante la configuración de sesión. Para usar el archivo en una configuración de sesión, use el parámetro Path de los Register-PSSessionConfiguration cmdlets o Set-PSSessionConfiguration .

El archivo de configuración de sesión que New-PSSessionConfigurationFile se crea es un archivo de texto legible que contiene una tabla hash de las propiedades y valores de configuración de la sesión. El archivo tiene una extensión de nombre de .pssc archivo.

Todos los parámetros de New-PSSessionConfigurationFile son opcionales, excepto el parámetro Path . Si omite un parámetro, la clave correspondiente en el archivo de configuración de la sesión se comenta, excepto donde se indique en la descripción del parámetro.

Una configuración de sesión, también conocida como punto de conexión, es una colección de opciones de configuración en el equipo local que definen el entorno para las sesiones de PowerShell (PSSessions) que se conectan al equipo. Todas las PSSessions utilizan una configuración de sesión. Para especificar una configuración de sesión determinada, use el parámetro ConfigurationName de los cmdlets que crean una sesión, como el New-PSSession cmdlet.

Un archivo de configuración de sesión facilita la definición de una configuración de sesión sin scripts complejos ni ensamblados de código. La configuración del archivo se utiliza con el script de inicio opcional y los ensamblados de la configuración de sesión.

Para obtener más información sobre las configuraciones de sesión y los archivos de configuración de sesión, consulte about_Session_Configurations y about_Session_Configuration_Files.

Este cmdlet se introdujo en PowerShell 3.0.

En este ejemplo se muestra cómo crear y los efectos de usar una sesión sin idioma.

Los pasos incluyen:

1. Cree un nuevo archivo de configuración.
2. Registre la configuración.
3. Cree una nueva sesión que utilice la configuración.
4. Ejecute comandos en esa nueva sesión.

Para ejecutar los comandos de este ejemplo, inicie PowerShell mediante la opción Ejecutar como administrador. Esta opción es necesaria para ejecutar el Register-PSSessionConfiguration cmdlet.

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

En este ejemplo, se produce un Invoke-Command error porque LanguageMode está establecido en NoLanguage.

En este ejemplo se muestra cómo crear y los efectos de usar una sesión sin idioma.

Los pasos incluyen:

1. Cree un nuevo archivo de configuración.
2. Registre la configuración.
3. Cree una nueva sesión que utilice la configuración.
4. Ejecute comandos en esa nueva sesión.

Para ejecutar los comandos de este ejemplo, inicie PowerShell mediante la opción Ejecutar como administrador. Esta opción es necesaria para ejecutar el Register-PSSessionConfiguration cmdlet.

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

En este ejemplo, el Invoke-Command se realiza correctamente porque LanguageMode se establece en RestrictedLanguage.

En este ejemplo se muestra cómo cambiar el archivo de configuración de sesión que se utiliza en una sesión existente denominada "ITTasks". Anteriormente, estas sesiones solo tenían los módulos principales y un módulo interno de ITTasks . El administrador desea agregar el módulo PSScheduledJob a las sesiones creadas mediante la configuración de sesión de ITTasks.

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

El New-PSSessionConfigurationFile cmdlet para crear un archivo de configuración de sesión que importe los módulos necesarios. El Set-PSSessionConfiguration cmdlet reemplaza el archivo de configuración actual por el nuevo. Esta nueva configuración solo afecta a las nuevas sesiones creadas después del cambio. Las sesiones "ITTasks" existentes no se ven afectadas.

En este ejemplo se muestra cómo cambiar la configuración de una sesión editando la copia de configuración de sesión activa del archivo de configuración. Para modificar la copia de configuración de sesión del archivo de configuración, debe tener acceso de control total al archivo. Esto puede requerir que cambie los permisos en el archivo.

En este escenario, queremos agregar un nuevo alias para el Select-String cmdlet editando el archivo de configuración activo.

En el código de ejemplo siguiente se realizan los siguientes pasos para realizar este cambio:

1. Obtenga la ruta del archivo de configuración para la sesión de ITConfig.
2. El usuario edita el archivo de configuración mediante Notepad.exe para cambiar el valor de AliasDefinitions de la siguiente manera: AliasDefinitions = @(@{Name='slst';Value='Select-String'}).
3. Pruebe el archivo de configuración actualizado.

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

True

Utilice el parámetro Verbose con Test-PSSessionConfigurationFile para mostrar los errores que se detecten. El cmdlet devuelve $True si no se detecta ningún error en el archivo.

En este ejemplo se muestra un New-PSSessionConfigurationFile comando que usa todos los parámetros del cmdlet. Se incluye para mostrar el formato de entrada correcto para cada parámetro.

El SampleFile.pssc resultante se muestra en la salida.

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

En este ejemplo se muestra un comando New-PSSessionConfigurationFile que usa todos los parámetros del cmdlet. Se incluye para mostrar el formato de entrada correcto para cada parámetro.

El SampleFile.pssc resultante se muestra en la salida.

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

No se puede canalizar ningún objeto a este cmdlet.

Este cmdlet no genera ningún resultado.

• Los parámetros, como VisibleCmdlets y VisibleProviders, no importan elementos en la sesión. En su lugar, seleccionan entre los elementos importados en la sesión. Por ejemplo, si el valor del parámetro VisibleProviders es el proveedor de certificados, pero el parámetro ModulesToImport no especifica el módulo Microsoft.PowerShell.Security que contiene el proveedor de certificados, el proveedor de certificados no está visible en la sesión.

• New-PSSessionConfigurationFile crea un archivo de configuración de sesión que tiene una extensión de nombre de archivo .pssc en la ruta de acceso especificada en el parámetro Path . Cuando se usa el archivo de configuración de sesión para crear una configuración de sesión, el Register-PSSessionConfiguration cmdlet copia el archivo de configuración y guarda una copia activa del archivo en el subdirectorio SessionConfig del $PSHOME directorio.

  La propiedad ConfigFilePath de la configuración de sesión contiene la ruta de acceso completa del archivo de configuración de sesión activo. Puede modificar el archivo de configuración activo en el $PSHOME directorio en cualquier momento utilizando cualquier editor de texto. Los cambios que realice afectarán a todas las sesiones nuevas que utilicen la configuración de sesión, pero no a las sesiones existentes.

  Antes de usar un archivo de configuración de sesión editada, use el Test-PSSessionConfigurationFile cmdlet para comprobar que las entradas del archivo de configuración son válidas.