Compartilhar via


New-PSSessionConfigurationFile

Cria um arquivo que define uma configuração de sessão.

Sintaxe

New-PSSessionConfigurationFile
   [-Path] <String>
   [-SchemaVersion <Version>]
   [-Guid <Guid>]
   [-Author <String>]
   [-Description <String>]
   [-CompanyName <String>]
   [-Copyright <String>]
   [-SessionType <SessionType>]
   [-TranscriptDirectory <String>]
   [-RunAsVirtualAccount]
   [-RunAsVirtualAccountGroups <String[]>]
   [-MountUserDrive]
   [-UserDriveMaximumSize <Int64>]
   [-GroupManagedServiceAccount <String>]
   [-ScriptsToProcess <String[]>]
   [-RoleDefinitions <IDictionary>]
   [-RequiredGroups <IDictionary>]
   [-LanguageMode <PSLanguageMode>]
   [-ExecutionPolicy <ExecutionPolicy>]
   [-PowerShellVersion <Version>]
   [-ModulesToImport <Object[]>]
   [-VisibleAliases <String[]>]
   [-VisibleCmdlets <Object[]>]
   [-VisibleFunctions <Object[]>]
   [-VisibleExternalCommands <String[]>]
   [-VisibleProviders <String[]>]
   [-AliasDefinitions <IDictionary[]>]
   [-FunctionDefinitions <IDictionary[]>]
   [-VariableDefinitions <Object>]
   [-EnvironmentVariables <IDictionary>]
   [-TypesToProcess <String[]>]
   [-FormatsToProcess <String[]>]
   [-AssembliesToLoad <String[]>]
   [-Full]
   [<CommonParameters>]

Description

O New-PSSessionConfigurationFile cmdlet 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 Register-PSSessionConfiguration cmdlets or Set-PSSessionConfiguration .

O arquivo de configuração de sessão que New-PSSessionConfigurationFile cria é um arquivo de texto legível 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 .pssc arquivo.

Todos os parâmetros de New-PSSessionConfigurationFile são opcionais, exceto o parâmetro Path . Se um parâmetro for omitido, a chave correspondente no arquivo de configuração de sessão é comentada, exceto onde observado 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 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 New-PSSession cmdlet.

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 quaisquer 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. A partir do PowerShell 6.0, esse cmdlet só estava disponível na plataforma Windows. O PowerShell 7.3 disponibilizou esse cmdlet em todas as plataformas com suporte.

Exemplos

Exemplo 1: Criando e usando uma sessão NoLanguage

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

As etapas são as seguintes:

  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 Register-PSSessionConfiguration cmdlet.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force
$NoLanguageSession = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage
Invoke-Command -Session $NoLanguageSession -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.

Exemplo 2: Criando e usando uma sessão RestrictedLanguage

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

As etapas são as seguintes:

  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 Register-PSSessionConfiguration cmdlet.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode RestrictedLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name RestrictedLanguage -Force
$RestrictedSession = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage
Invoke-Command -Session $RestrictedSession -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: Alterando um arquivo de configuração de sessão

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 interno do ITTasks . O administrador deseja adicionar o módulo PSScheduledJob às sessões criadas usando a configuração de 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 arquivo de configuração de sessão que importa os módulos necessários. O Set-PSSessionConfiguration cmdlet 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.

Exemplo 4: Editando um arquivo de configuração de sessão

Este exemplo mostra como alterar uma configuração de sessão editando a cópia da configuração de sessão ativa do arquivo de configuração. Para modificar a cópia de configuração da 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 Select-String cmdlet 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 de 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 Verbose com Test-PSSessionConfigurationFile para exibir os erros detectados. O cmdlet retornará $True se nenhum erro for detectado no arquivo.

Exemplo 5: Criar um arquivo de configuração de exemplo

Este exemplo mostra um New-PSSessionConfigurationFile comando que usa todos os parâmetros do cmdlet. Ele é fornecido para mostrar o formato correto de entrada 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'
    RunAsVirtualAccount = $true
    RunAsVirtualAccountGroups = 'Backup Operators'
}
New-PSSessionConfigurationFile @configSettings
Get-Content SampleFile.pssc

@{

# Version number of the schema used for this document
SchemaVersion = '1.0.0.0'

# ID used to uniquely identify this document
GUID = '1caeff7f-27ca-4360-97cf-37846f594235'

# Author of this document
Author = 'User01'

# Description of the functionality provided by these settings
Description = 'This is a sample file.'

# Company associated with this document
CompanyName = 'Fabrikam Corporation'

# Copyright statement for this document
Copyright = '(c) Fabrikam Corporation. All rights reserved.'

# Session type defaults to apply for this session configuration. Can be 'RestrictedRemoteServer' (recommended), 'Empty', or 'Default'
SessionType = 'Default'

# Directory to place session transcripts for this session configuration
# TranscriptDirectory = 'C:\Transcripts\'

# Whether to run this session configuration as the machine's (virtual) administrator account
RunAsVirtualAccount = $true

# Groups associated with machine's (virtual) administrator account
RunAsVirtualAccountGroups = 'Backup Operators'

# Scripts to run when applied to a session
ScriptsToProcess = 'Get-Inputs.ps1'

# User roles (security groups), and the role capabilities that should be applied to them when applied to a session
# RoleDefinitions = @{ 'CONTOSO\SqlAdmins' = @{ RoleCapabilities = 'SqlAdministration' }; 'CONTOSO\SqlManaged' = @{ RoleCapabilityFiles = 'C:\RoleCapability\SqlManaged.psrc' }; 'CONTOSO\ServerMonitors' = @{ VisibleCmdlets = 'Get-Process' } }

# Language mode to apply when applied to a session. Can be 'NoLanguage' (recommended), 'RestrictedLanguage', 'ConstrainedLanguage', or 'FullLanguage'
LanguageMode = 'FullLanguage'

# Execution policy to apply when applied to a session
ExecutionPolicy = 'AllSigned'

# Version of the PowerShell engine to use when applied to a session
PowerShellVersion = '3.0'

# Modules to import when applied to a session
ModulesToImport = @{
    'GUID' = '50cdb55f-5ab7-489f-9e94-4ec21ff51e59'
    'ModuleName' = 'PSScheduledJob'
    'ModuleVersion' = '1.0.0.0' }, 'PSDiagnostics'

# Aliases to make visible when applied to a session
VisibleAliases = 'c*', 'g*', 'i*', 's*'

# Cmdlets to make visible when applied to a session
VisibleCmdlets = 'Get*'

# Functions to make visible when applied to a session
VisibleFunctions = 'Get*'

# Providers to make visible when applied to a session
VisibleProviders = 'FileSystem', 'Function', 'Variable'

# Aliases to be defined when applied to a session
AliasDefinitions = @{
    'Description' = 'Gets help.'
    'Name' = 'hlp'
    'Options' = 'AllScope'
    'Value' = 'Get-Help' }, @{
    'Description' = 'Updates help'
    'Name' = 'Update'
    'Options' = 'ReadOnly'
    'Value' = 'Update-Help' }

# Functions to define when applied to a session
FunctionDefinitions = @{
    'Name' = 'Get-Function'
    'Options' = 'ReadOnly'
    'ScriptBlock' = {Get-Command -CommandType Function} }

# Variables to define when applied to a session
VariableDefinitions = @{
    'Name' = 'WarningPreference'
    'Value' = 'SilentlyContinue' }

# Environment variables to define when applied to a session
EnvironmentVariables = @{
    'TESTSHARE' = '\\Test2\Test' }

# Type files (.ps1xml) to load when applied to a session
TypesToProcess = 'Types1.ps1xml', 'Types2.ps1xml'

# Format files (.ps1xml) to load when applied to a session
FormatsToProcess = 'CustomFormats.ps1xml'

# Assemblies to load when applied to a session
AssembliesToLoad = 'System.Web.Services', 'FSharp.Compiler.CodeDom.dll'

}

Parâmetros

-AliasDefinitions

Adiciona os aliases especificados às sessões que usam a configuração de sessão. Insira uma tabela de hash com as seguintes chaves:

  • Nome - Nome do alias. Essa chave é necessária.
  • Valor - O comando que o alias representa. Essa chave é necessária.
  • Descrição - Uma cadeia de caracteres de texto que descreve o alias. Essa chave é opcional.
  • Opções - Opções de alias. Essa chave é opcional. O valor padrão é None. Os valores aceitáveis para esse parâmetro são: None, ReadOnly, Constant, Private ou AllScope.

Por exemplo: @{Name='hlp';Value='Get-Help';Description='Gets help';Options='ReadOnly'}

Tipo:IDictionary[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-AssembliesToLoad

Especifica os assemblies para carregar nas sessões que usam a configuração de sessão.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Author

Especifica o autor da configuração da sessão ou do arquivo de configuração. O padrão é o usuário atual. O valor desse parâmetro é visível no arquivo de configuração de sessão, mas não é uma propriedade do objeto de configuração da sessão.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CompanyName

Especifica a empresa que criou a configuração da sessão ou o arquivo de configuração. O valor padrão é Desconhecido. O valor desse parâmetro é visível no arquivo de configuração de sessão, mas não é uma propriedade do objeto de configuração da sessão.

Tipo:String
Cargo:Named
Valor padrão:Unknown
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Especifica um copyright do arquivo de configuração da sessão. O valor desse parâmetro é visível no arquivo de configuração de sessão, mas não é uma propriedade do objeto de configuração da sessão.

Se você omitir esse parâmetro, New-PSSessionConfigurationFile o gerará uma instrução de direitos autorais usando o valor do parâmetro Author .

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Description

Especifica uma descrição da configuração da sessão ou do arquivo de configuração da sessão. O valor desse parâmetro é visível no arquivo de configuração de sessão, mas não é uma propriedade do objeto de configuração da sessão.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-EnvironmentVariables

Adiciona variáveis de ambiente à sessão. Insira uma tabela de hash na qual as chaves são nomes de variáveis de ambiente e os valores são valores de variáveis de ambiente.

Por exemplo: EnvironmentVariables=@{TestShare='\\Server01\TestShare'}

Tipo:IDictionary
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ExecutionPolicy

Especifica a política de execução de sessões que usam a configuração de sessão. Se você omitir esse parâmetro, o valor da chave ExecutionPolicy no arquivo de configuração da sessão será Restricted. Para obter informações sobre políticas de execução no PowerShell, consulte about_Execution_Policies.

Tipo:ExecutionPolicy
Valores aceitos:Unrestricted, RemoteSigned, AllSigned, Restricted, Default, Bypass, Undefined
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-FormatsToProcess

Especifica os arquivos de formatação (.ps1xml) executados em sessões que usam a configuração de sessão. O valor desse parâmetro deve ser um caminho completo ou absoluto dos arquivos de formatação.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Full

Indica que essa operação inclui todas as propriedades de configuração possíveis no arquivo de configuração da sessão.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-FunctionDefinitions

Adiciona as funções especificadas às sessões que usam a configuração de sessão. Insira uma tabela de hash com as seguintes chaves:

  • Nome - Nome da função. Essa chave é necessária.
  • ScriptBlock - Corpo da função. Insira um bloco de script. Essa chave é necessária.
  • Opções - Opções de função. Essa chave é opcional. O valor padrão é None. Os valores aceitáveis para esse parâmetro são: None, ReadOnly, Constant, Private ou AllScope.

Por exemplo: @{Name='Get-PowerShellProcess';ScriptBlock={Get-Process PowerShell};Options='AllScope'}

Tipo:IDictionary[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-GroupManagedServiceAccount

Configura sessões usando essa configuração de sessão para serem executadas no contexto da Conta de Serviço Gerenciado de Grupo especificada. A máquina em que essa configuração de sessão está registrada deve ter permissão para solicitar a senha gMSA para que as sessões sejam criadas com êxito. Esse campo não pode ser usado com o parâmetro RunAsVirtualAccount .

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Guid

Especifica um identificador exclusivo para o arquivo de configuração de sessão. Se você omitir esse parâmetro, New-PSSessionConfigurationFile o gerará um GUID para o arquivo. Para criar um novo GUID no PowerShell, digite New-Guid.

Tipo:Guid
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-LanguageMode

Determina quais elementos da linguagem do PowerShell são permitidos em sessões que usam essa configuração de sessão. Você pode usar esse parâmetro para restringir os comandos que usuários específicos podem executar no computador.

Os valores aceitáveis para esse parâmetro são:

  • FullLanguage - Todos os elementos de idioma são permitidos.
  • ConstrainedLanguage - Comandos que contêm scripts a serem avaliados não são permitidos. O modo ConstrainedLanguage restringe o acesso do usuário a tipos, objetos ou métodos do Microsoft .NET Framework.
  • NoLanguage - Os usuários podem executar cmdlets e funções, mas não têm permissão para usar nenhum elemento de linguagem, como blocos de script, variáveis ou operadores.
  • RestrictedLanguage - Os usuários podem executar cmdlets e funções, mas não têm permissão para usar blocos ou variáveis de script, exceto para as seguintes variáveis permitidas: $PSCulture, $PSUICulture, $True, $False, e $Null. Os usuários podem usar apenas os operadores de comparação básicos (-eq, -gt, -lt). Não são permitidas instruções de atribuição, referências de propriedade e chamadas de método.

O valor padrão do parâmetro LanguageMode depende do valor do parâmetro SessionType .

  • Vazio - NoLanguage
  • RestrictedRemoteServer - NoLanguage
  • Padrão - FullLanguage
Tipo:PSLanguageMode
Valores aceitos:FullLanguage, RestrictedLanguage, NoLanguage, ConstrainedLanguage
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ModulesToImport

Especifica os módulos e snap-ins que são importados automaticamente nas sessões que usam a configuração de sessão.

Por padrão, somente o snap-in Microsoft.PowerShell.Core é importado para sessões remotas, mas, a menos que os cmdlets sejam excluídos, os usuários podem usar os Import-Module cmdlets e Add-PSSnapin para adicionar módulos e snap-ins à sessão.

Cada módulo ou o snap-in no valor desse parâmetro pode ser representado por uma cadeia de caracteres ou como uma tabela de hash. Uma cadeia de caracteres de módulo consiste apenas no nome do módulo ou snap-in. Uma tabela de hash de módulo pode incluir chaves ModuleName, ModuleVersion e GUID . Somente a chave ModuleName é necessária.

Por exemplo, o seguinte valor consiste em uma cadeia de caracteres e uma tabela de hash. Qualquer combinação de cadeias de caracteres e tabelas de hash, em qualquer ordem, é válida.

'TroubleshootingPack', @{ModuleName='PSDiagnostics'; ModuleVersion='1.0.0.0';GUID='c61d6278-02a3-4618-ae37-a524d40a7f44'}

O valor do parâmetro ModulesToImport do Register-PSSessionConfiguration cmdlet tem precedência sobre o valor da chave ModulesToImport no arquivo de configuração da sessão.

Tipo:Object[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-MountUserDrive

Configura sessões que usam essa configuração de sessão para expor o User: PSDrive. As unidades de usuário são exclusivas para cada usuário conectado e permitem que os usuários copiem dados de e para pontos de extremidade do PowerShell, mesmo que o provedor do Sistema de Arquivos não esteja exposto. As raízes da unidade de usuário são criadas em $env:LOCALAPPDATA\Microsoft\PowerShell\DriveRoots\. Para cada usuário que se conecta ao ponto de extremidade, uma pasta é criada com o nome $env:USERDOMAIN\$env:USERNAME. Para computadores em grupos de trabalho, o valor de é o nome do $env:USERDOMAIN host.

O conteúdo na unidade do usuário persiste nas sessões do usuário e não é removido automaticamente. Por padrão, os usuários só podem armazenar até 50 MB de dados na unidade do usuário. Isso pode ser personalizado com o parâmetro UserDriveMaximumSize .

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Path

Especifica o caminho e o nome do arquivo de configuração da sessão. O arquivo deve ter uma extensão de nome de .pssc arquivo.

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-PowerShellVersion

Especifica a versão do mecanismo do PowerShell em sessões que usam a configuração de sessão. Os valores aceitáveis para este parâmetro são: 2,0 e 3,0. Se você omitir esse parâmetro, a chave PowerShellVersion será comentada e a versão mais recente do PowerShell será executada na sessão.

O valor do parâmetro PSVersion do cmdlet tem precedência sobre o valor da chave PowerShellVersion no arquivo de Register-PSSessionConfiguration configuração da sessão.

Tipo:Version
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RequiredGroups

Especifica regras de acesso condicional para usuários que se conectam a sessões que usam essa configuração de sessão.

Insira uma tabela de hash para compor sua lista de regras usando apenas 1 chave por tabela de hash, 'E' ou 'Ou', e defina o valor como uma matriz de nomes de grupos de segurança ou tabelas de hash adicionais.

Exemplo que exige que os usuários conectados sejam membros de um único grupo: @{ And = 'MyRequiredGroup' }

Exemplo que exige que os usuários pertençam ao grupo A, ou aos grupos B e C, para acessar o endpoint: @{ Or = 'GroupA', @{ And = 'GroupB', 'GroupC' } }

Tipo:IDictionary
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RoleDefinitions

Especifica o mapeamento entre grupos de segurança (ou usuários) e recursos de função. Os usuários terão acesso a todos os recursos de função que se aplicam à associação ao grupo no momento em que a sessão for criada.

Insira uma tabela de hash na qual as chaves são o nome do grupo de segurança e os valores são tabelas de hash que contêm uma lista de recursos de função que devem ser disponibilizados para o grupo de segurança.

Por exemplo: @{'Contoso\Level 2 Helpdesk Users' = @{ RoleCapabilities = 'Maintenance', 'ADHelpDesk' }}

Tipo:IDictionary
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RunAsVirtualAccount

Configura sessões usando essa configuração de sessão para serem executadas como a conta de administrador (virtual) do computador. Esse campo não pode ser usado com o parâmetro GroupManagedServiceAccount .

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RunAsVirtualAccountGroups

Especifica os grupos de segurança a serem associados à conta virtual quando uma sessão que usa a configuração de sessão é executada como uma conta virtual. Se omitida, a conta virtual pertencerá aos Administradores de Domínio em controladores de domínio e Administradores em todos os outros computadores.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SchemaVersion

Especifica a versão do esquema de arquivo de configuração de sessão. O valor padrão é "1.0.0.0".

Tipo:Version
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ScriptsToProcess

Adiciona os scripts especificados às sessões que usam a configuração de sessão. Digite os nomes de arquivo e caminho dos scripts. O valor desse parâmetro deve ser um caminho completo ou absoluto de nomes de arquivo de script.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SessionType

Especifica o tipo de sessão que é criada usando a configuração da sessão. O valor padrão é Default. Os valores aceitáveis para esse parâmetro são:

  • Vazio - Nenhum módulo é adicionado à sessão por padrão. Use os parâmetros desse cmdlet para adicionar módulos, funções, scripts e outros recursos à sessão. Essa opção foi projetada para você criar sessões personalizadas adicionando comandos selecionados. Se não adicionar comandos a uma sessão vazia, a sessão é limitada a expressões e não pode ser utilizada.
  • Padrão – adiciona o módulo Microsoft.PowerShell.Core à sessão. Esse módulo inclui o cmdlet que os usuários podem usar para importar outros módulos, a menos que você proíba Import-Module explicitamente esse cmdlet.
  • RestrictedRemoteServer. Inclui apenas as seguintes funções de proxy: Exit-PSSession, Get-Command, Get-FormatData, Get-Help, Measure-Object, Out-Default, e Select-Object. Use os parâmetros desse cmdlet para adicionar módulos, funções, scripts e outros recursos à sessão.
Tipo:SessionType
Valores aceitos:Empty, RestrictedRemoteServer, Default
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-TranscriptDirectory

Especifica o diretório para colocar transcrições de sessão para sessões usando essa configuração de sessão.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-TypesToProcess

Adiciona os arquivos de tipo especificado .ps1xml às sessões que usam a configuração da sessão. Insira o tipo nomes de arquivo. O valor desse parâmetro deve ser um caminho completo ou absoluto para o tipo de nomes de arquivo.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-UserDriveMaximumSize

Especifica o tamanho máximo das unidades de usuário expostas em sessões que usam essa configuração de sessão. Quando omitido, o tamanho padrão de cada User: raiz de unidade é de 50 MB.

Esse parâmetro deve ser usado com MountUserDrive.

Tipo:Int64
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-VariableDefinitions

Adiciona as variáveis especificadas às sessões que usam a configuração de sessão. Insira uma tabela de hash com as seguintes chaves:

  • Nome - Nome da variável. Essa chave é necessária.
  • Valor - Valor da variável. Essa chave é necessária.

Por exemplo: @{Name='WarningPreference';Value='SilentlyContinue'}

Tipo:Object
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-VisibleAliases

Limita os aliases na sessão aos especificados no valor desse parâmetro, além de quaisquer aliases definidos no parâmetro AliasDefinition . Há suporte para caracteres curinga. Por padrão, todos os aliases definidos pelo mecanismo do PowerShell e todos os aliases exportados pelos módulos ficam visíveis na sessão.

Por exemplo: VisibleAliases='gcm', 'gp'

Quando qualquer parâmetro Visible é incluído no arquivo de configuração da sessão, o PowerShell remove o Import-Module cmdlet e seu alias ipmo da sessão.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-VisibleCmdlets

Limita os cmdlets na sessão para aquelas especificadas no valor desse parâmetro. Caracteres curinga e nomes qualificados de módulo são suportados.

Por padrão, todos os cmdlets que os módulos na sessão exportam são visíveis na sessão. Use os parâmetros SessionType e ModulesToImport para determinar quais módulos e snap-ins são importados para a sessão. Se nenhum módulo em ModulesToImport expor o cmdlet, o módulo apropriado tentará ser carregado automaticamente.

Quando qualquer parâmetro Visible é incluído no arquivo de configuração da sessão, o PowerShell remove o Import-Module cmdlet e seu alias ipmo da sessão.

Tipo:Object[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-VisibleExternalCommands

Limita os binários, scripts e comandos externos que podem ser executados na sessão aos especificados no valor desse parâmetro. Há suporte para caracteres curinga.

Por padrão, nenhum comando externo é visível na sessão.

Quando qualquer parâmetro Visible é incluído no arquivo de configuração da sessão, o PowerShell remove o Import-Module cmdlet e seu alias ipmo da sessão.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-VisibleFunctions

Limita as funções na sessão àquelas especificadas no valor desse parâmetro, além de todas as funções definidas no parâmetro FunctionDefinition . Há suporte para caracteres curinga.

Por padrão, todos as funções que os módulos na sessão exportam são visíveis na sessão. Use os parâmetros SessionType e ModulesToImport para determinar quais módulos e snap-ins são importados para a sessão.

Quando qualquer parâmetro Visible é incluído no arquivo de configuração da sessão, o PowerShell remove o Import-Module cmdlet e seu alias ipmo da sessão.

Tipo:Object[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-VisibleProviders

Limita os provedores do PowerShell na sessão aos especificados no valor desse parâmetro. Há suporte para caracteres curinga.

Por padrão, todos os provedores que os módulos na sessão exportam são visíveis na sessão. Use os parâmetros SessionType e ModulesToImport para determinar quais módulos são importados para a sessão.

Quando qualquer parâmetro Visible é incluído no arquivo de configuração da sessão, o PowerShell remove o Import-Module cmdlet e seu ipmo alias da sessão.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

None

Esse cmdlet não retorna nenhuma saída.

Observações

  • 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 certificado, mas o parâmetro ModulesToImport não especificar o módulo Microsoft.PowerShell.Security que contém o provedor de certificado, o provedor de certificado não estará 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 Register-PSSessionConfiguration cmdlet copia o arquivo de configuração e salva uma cópia ativa do arquivo no subdiretório SessionConfig do $PSHOME diretório.

    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 a $PSHOME qualquer momento usando qualquer editor de texto. As alterações feitas afetam todas as novas sessões que usam a configuração de sessão, mas sessões não existentes.

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