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

O cmdlet New-PSSessionConfigurationFile cria um arquivo de configurações que definem uma configuração de sessão e o ambiente de sessões que são criadas usando a configuração de sessão. Para usar o arquivo em uma configuração de sessão, use o parâmetro Path dos cmdlets Register-PSSessionConfiguration ou Set-PSSessionConfiguration.

O arquivo de configuração de sessão que New-PSSessionConfigurationFile cria é um arquivo de texto legível por humanos que contém uma tabela de hash das propriedades e valores de configuração da sessão. O arquivo tem uma extensão de nome de arquivo .pssc.

Todos os parâmetros de New-PSSessionConfigurationFile são opcionais, exceto o parâmetro Path. Se você omitir um parâmetro, a chave correspondente no arquivo de configuração de sessão será comentada, exceto quando anotada na descrição do parâmetro.

Uma configuração de sessão, também conhecida como ponto de extremidade, é uma coleção de configurações no computador local que definem o ambiente para sessões do PowerShell (PSSessions) que se conectam ao computador. Todas as PSSessions de usam uma configuração de sessão. Para especificar uma configuração de sessão específica, use o parâmetro ConfigurationName de cmdlets que criam uma sessão, como o cmdlet New-PSSession.

Um arquivo de configuração de sessão facilita a definição de uma configuração de sessão sem scripts complexos ou assemblies de código. As configurações no arquivo são usadas com o script de inicialização opcional e todos os assemblies na configuração da sessão.

Para obter mais informações sobre configurações de sessão e arquivos de configuração de sessão, consulte about_Session_Configurations e about_Session_Configuration_Files.

Esse cmdlet foi introduzido no PowerShell 3.0.

Este exemplo mostra como criar e os efeitos do uso de uma sessão sem idioma.

As etapas incluem:

1. Crie um novo arquivo de configuração.
2. Registre a configuração.
3. Crie uma nova sessão que use a configuração.
4. Execute comandos nessa nova sessão.

Para executar os comandos neste exemplo, inicie o PowerShell usando a opção Executar como administrador. Essa opção é necessária para executar o cmdlet Register-PSSessionConfiguration.

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

Neste exemplo, o Invoke-Command falha porque o LanguageMode está definido como NoLanguage.

Este exemplo mostra como criar e os efeitos do uso de uma sessão sem idioma.

As etapas incluem:

1. Crie um novo arquivo de configuração.
2. Registre a configuração.
3. Crie uma nova sessão que use a configuração.
4. Execute comandos nessa nova sessão.

Para executar os comandos neste exemplo, inicie o PowerShell usando a opção Executar como administrador. Essa opção é necessária para executar o cmdlet Register-PSSessionConfiguration.

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

Neste exemplo, o Invoke-Command é bem-sucedido porque o LanguageMode está definido como RestrictedLanguage.

Este exemplo mostra como alterar o arquivo de configuração de sessão usado em uma sessão existente chamada "ITTasks". Anteriormente, essas sessões tinham apenas os módulos principais e um módulo ittasks interno. O administrador deseja adicionar o módulo PSScheduledJob às sessões criadas usando a configuração da sessão ITTasks.

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

O cmdlet New-PSSessionConfigurationFile para criar um arquivo de configuração de sessão que importa os módulos necessários. O cmdlet Set-PSSessionConfiguration substitui o arquivo de configuração atual pelo novo. Essa nova configuração afeta apenas novas sessões criadas após a alteração. As sessões "ITTasks" existentes não são afetadas.

Este exemplo mostra como alterar uma configuração de sessão editando a cópia de configuração de sessão ativa do arquivo de configuração. Para modificar a cópia de configuração de sessão do arquivo de configuração, você deve ter acesso de controle total ao arquivo. Isso pode exigir que você altere as permissões no arquivo.

Nesse cenário, queremos adicionar um novo alias para o cmdlet Select-String editando o arquivo de configuração ativo.

O código de exemplo abaixo executa as seguintes etapas para fazer essa alteração:

1. Obtenha o caminho do arquivo de configuração para a sessão ITConfig.
2. O usuário edita o arquivo de configuração usando Notepad.exe para alterar o valor AliasDefinitions da seguinte maneira: AliasDefinitions = @(@{Name='slst';Value='Select-String'}).
3. Teste o arquivo de configuração atualizado.

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

True

Use o parâmetro detalhado com Test-PSSessionConfigurationFile para exibir os erros detectados. O cmdlet retornará $True se nenhum erro for detectado no arquivo.

Este exemplo mostra um comando New-PSSessionConfigurationFile que usa todos os parâmetros de cmdlet. Ele está incluído para mostrar o formato de entrada correto para cada parâmetro.

O SampleFile.pssc resultante é exibido na saída.

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

Este exemplo exibe um comando New-PSSessionConfigurationFile que usa todos os parâmetros do cmdlet. Ele está incluído para mostrar o formato de entrada correto para cada parâmetro.

O SampleFile.pssc resultante é exibido na saída.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Você não pode canalizar nenhum objeto para esse cmdlet.

Este cmdlet não gera saída.

• Parâmetros, como VisibleCmdlets e VisibleProviders, não importam itens para a sessão. Em vez disso, eles selecionam entre os itens importados para a sessão. Por exemplo, se o valor do parâmetro VisibleProviders for o provedor de certificados, mas o parâmetro ModulesToImport não especificar o módulo Microsoft.PowerShell.Security que contém o provedor de certificados, o provedor de certificados não ficará visível na sessão.

• New-PSSessionConfigurationFile cria um arquivo de configuração de sessão que tem uma extensão de nome de arquivo .pssc no caminho especificado no parâmetro Path. Quando você usa o arquivo de configuração de sessão para criar uma configuração de sessão, o cmdlet Register-PSSessionConfiguration copia o arquivo de configuração e salva uma cópia ativa do arquivo no subdiretório SessionConfig do diretório $PSHOME.

  A propriedade ConfigFilePath da configuração da sessão contém o caminho totalmente qualificado do arquivo de configuração da sessão ativa. Você pode modificar o arquivo de configuração ativo no diretório $PSHOME a qualquer momento usando qualquer editor de texto. As alterações feitas afetam todas as novas sessões que usam a configuração da sessão, mas não as sessões existentes.

  Antes de usar um arquivo de configuração de sessão editado, use o cmdlet Test-PSSessionConfigurationFile para verificar se as entradas do arquivo de configuração são válidas.