New-PSSessionConfigurationFile

Syntax

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

Description

O New-PSSessionConfigurationFile cmdlet cria um ficheiro de definições que definem uma configuração de sessão e o ambiente das sessões que são criadas com a configuração da sessão. Para utilizar o ficheiro numa configuração de sessão, utilize o parâmetro Path dos Register-PSSessionConfiguration cmdlets ou Set-PSSessionConfiguration .

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

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

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

Um ficheiro de configuração de sessão facilita a definição de uma configuração de sessão sem scripts complexos ou assemblagens de código. As definições no ficheiro são utilizadas com o script de arranque opcional e quaisquer assemblagens na configuração da sessão.

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

Este cmdlet foi introduzido no PowerShell 3.0.

Exemplos

Exemplo 1: Criar e utilizar uma sessão NoLanguage

Este exemplo mostra como criar e os efeitos da utilização de uma sessão sem idioma.

Os passos incluem:

1. Create um novo ficheiro de configuração.
2. Registe a configuração.
3. Create uma nova sessão que utiliza a configuração.
4. Execute comandos nessa nova sessão.

Para executar os comandos neste exemplo, inicie o PowerShell com a opção Executar como administrador. Esta opção é necessária para executar o 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

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

Exemplo 2: Criar e utilizar uma sessão RestrictedLanguage

Este exemplo mostra como criar e os efeitos da utilização de uma sessão sem idioma.

Os passos incluem:

1. Create um novo ficheiro de configuração.
2. Registe a configuração.
3. Create uma nova sessão que utiliza a configuração.
4. Execute comandos nessa nova sessão.

Para executar os comandos neste exemplo, inicie o PowerShell com a opção Executar como administrador. Esta opção é necessária para executar o 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

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

Exemplo 3: Alterar um Ficheiro de Configuração de Sessão

Este exemplo mostra como alterar o ficheiro de configuração da sessão utilizado numa sessão existente denominada "ITTasks". Anteriormente, estas sessões tinham apenas os módulos principais e um módulo itTasks interno. O administrador quer adicionar o módulo PSScheduledJob a sessões criadas com 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 New-PSSessionConfigurationFile cmdlet para criar um ficheiro de configuração de sessão que importa os módulos necessários. O Set-PSSessionConfiguration cmdlet substitui o ficheiro de configuração atual pelo novo. Esta nova configuração afeta apenas as novas sessões criadas após a alteração. As sessões "ITTasks" existentes não são afetadas.

Exemplo 4: Editar um Ficheiro de Configuração de Sessão

Este exemplo mostra como alterar uma configuração de sessão ao editar a cópia de configuração de sessão ativa do ficheiro de configuração. Para modificar a cópia de configuração da sessão do ficheiro de configuração, tem de ter acesso de controlo total ao ficheiro. Isto pode exigir que altere as permissões no ficheiro.

Neste cenário, queremos adicionar um novo alias para o Select-String cmdlet ao editar o ficheiro de configuração ativo.

O código de exemplo abaixo executa os seguintes passos para fazer esta alteração:

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

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

True

Utilize o parâmetro Verboso com Test-PSSessionConfigurationFile para apresentar os erros detetados. O cmdlet devolve $True se não forem detetados erros no ficheiro.

Exemplo 5: Create um ficheiro de configuração de exemplo

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

O SampleFile.pssc resultante é apresentado 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 apresenta um comando New-PSSessionConfigurationFile que utiliza todos os parâmetros do cmdlet. Está incluído para mostrar o formato de entrada correto para cada parâmetro.

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

Parâmetros

-AliasDefinitions

-AssembliesToLoad

-Author

-CompanyName

-Copyright

-Description

-EnvironmentVariables

-ExecutionPolicy

-FormatsToProcess

-FunctionDefinitions

-Guid

-LanguageMode

-ModulesToImport

-Path

-PowerShellVersion

-SchemaVersion

-ScriptsToProcess

-SessionType

-TypesToProcess

-VariableDefinitions

-VisibleAliases

-VisibleCmdlets

-VisibleFunctions

-VisibleProviders

Entradas

None

Não é possível encaminhar quaisquer objetos para este cmdlet.

Saídas

None

Este cmdlet não gera nenhuma saída.

Notas

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

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

  A propriedade ConfigFilePath da configuração da sessão contém o caminho completamente qualificado do ficheiro de configuração de sessão ativa. Pode modificar o ficheiro de configuração ativo no diretório em $PSHOME qualquer altura através de qualquer editor de texto. As alterações efetuadas afetam todas as novas sessões que utilizam a configuração da sessão, mas não as sessões existentes.

  Antes de utilizar um ficheiro de configuração de sessão editada, utilize o Test-PSSessionConfigurationFile cmdlet para verificar se as entradas do ficheiro de configuração são válidas.

Ligações Relacionadas

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• Register-PSSessionConfiguration
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• Fornecedor WSMan
• about_Session_Configurations
• about_Session_Configuration_Files