New-PSRoleCapabilityFile
Cria um arquivo que define um conjunto de recursos a serem expostos por meio de uma configuração de sessão.
Syntax
New-PSRoleCapabilityFile
[-Path] <String>
[-Guid <Guid>]
[-Author <String>]
[-Description <String>]
[-CompanyName <String>]
[-Copyright <String>]
[-ModulesToImport <Object[]>]
[-VisibleAliases <String[]>]
[-VisibleCmdlets <Object[]>]
[-VisibleFunctions <Object[]>]
[-VisibleExternalCommands <String[]>]
[-VisibleProviders <String[]>]
[-ScriptsToProcess <String[]>]
[-AliasDefinitions <IDictionary[]>]
[-FunctionDefinitions <IDictionary[]>]
[-VariableDefinitions <Object>]
[-EnvironmentVariables <IDictionary>]
[-TypesToProcess <String[]>]
[-FormatsToProcess <String[]>]
[-AssembliesToLoad <String[]>]
[<CommonParameters>] Description
O New-PSRoleCapabilityFile cmdlet cria um arquivo que define um conjunto de recursos do usuário que podem ser expostos por meio de arquivos de configuração de sessão. Isso inclui determinar quais cmdlets, funções e scripts estão disponíveis para os usuários. O ficheiro de capacidade é 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 arquivo tem uma extensão de nome de arquivo .psrc e pode ser usado por mais de uma configuração de sessão.
Todos os parâmetros de New-PSRoleCapabilityFile são opcionais, exceto o parâmetro Path , que especifica o caminho para o arquivo. Se você não incluir um parâmetro ao executar o cmdlet, a chave correspondente no arquivo de configuração da sessão será comentada, exceto quando anotado na descrição do parâmetro. Por exemplo, se você não incluir o parâmetro AssembliesToLoad , essa seção do arquivo de configuração de sessão será comentada.
Para usar o arquivo de capacidade de função em uma configuração de sessão, primeiro coloque o arquivo em uma subpasta RoleCapabilities de uma pasta de módulo válida do PowerShell. Em seguida, faça referência ao arquivo pelo nome no campo RoleDefinitions em um arquivo de Configuração de Sessão do PowerShell (.pssc).
Este cmdlet foi introduzido no Windows PowerShell 5.0.
Exemplos
Exemplo 1: Criar um arquivo de recurso de função em branco
Este exemplo cria um novo arquivo de capacidade de função que usa os valores padrão (em branco). O arquivo pode ser editado posteriormente em um editor de texto para alterar essas definições de configuração.
New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"Exemplo 2: Criar um arquivo de capacidade de função permitindo que os usuários reiniciem serviços e qualquer computador VDI
Este exemplo cria um arquivo de recurso de função de exemplo que permite aos usuários reiniciar serviços e computadores que correspondem a um padrão de nome específico. A filtragem de nomes é definida definindo o parâmetro ValidatePattern como a expressão VDI\d+regular.
$roleParameters = @{
Path = ".\Maintenance.psrc"
Author = "User01"
CompanyName = "Fabrikam Corporation"
Description = "This role enables users to restart any service and restart any VDI computer."
ModulesToImport = "Microsoft.PowerShell.Core"
VisibleCmdlets = "Restart-Service", @{
Name = "Restart-Computer"
Parameters = @{ Name = "ComputerName"; ValidatePattern = "VDI\d+" }
}
}
New-PSRoleCapabilityFile @roleParametersParâmetros
-AliasDefinitions
Adiciona os aliases especificados a sessões que usam o arquivo de capacidade de função. Introduza uma tabela hash com as seguintes chaves:
- Nome. Nome do alias. Esta chave é necessária.
- Valor. O comando que o alias representa. Esta chave é necessária.
- Descrição. Uma cadeia de caracteres de texto que descreve o alias. Esta chave é opcional.
- Opções. Opções de alias. Esta chave é opcional. O valor predefinido é None. Os valores aceitáveis para este parâmetro são: None, ReadOnly, Constant, Private ou AllScope.
Por exemplo: @{Name="hlp";Value="Get-Help";Description="Gets help";Options="ReadOnly"}
| Type: | IDictionary[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AssembliesToLoad
Especifica os assemblies a serem carregados nas sessões que usam o arquivo de capacidade de função.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Author
Especifica o usuário que criou o arquivo de recurso de função.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CompanyName
Identifica a empresa que criou o arquivo de capacidade de função. O valor padrão é Unknown.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Copyright
Especifica um direito autoral para o arquivo de recurso de função. Se você omitir esse parâmetro, New-PSRoleCapabilityFile gerará uma declaração de direitos autorais usando o valor do parâmetro Author .
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Description
Especifica uma descrição para o arquivo de capacidade de função.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnvironmentVariables
Especifica as variáveis de ambiente para sessões que expõem esse arquivo de recurso de função. Introduza uma tabela hash em que as chaves são os nomes de variáveis de ambiente e os valores são os valores variáveis de ambiente.
Por exemplo: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FormatsToProcess
Especifica os arquivos de formatação (.ps1xml) que são executados em sessões que usam o arquivo de recurso de função.
O valor desse parâmetro deve ser um caminho completo ou absoluto dos arquivos de formatação.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FunctionDefinitions
Adiciona as funções especificadas a sessões que expõem a capacidade de função. Introduza uma tabela hash com as seguintes chaves:
- Nome. Nome da função. Esta chave é necessária.
- ScriptBlock. Corpo da função. Insira um bloco de script. Esta chave é necessária.
- Opções. Opções de função. Esta chave é opcional. O valor predefinido é None. Os valores aceitáveis para este parâmetro são: são None, ReadOnly, Constant, Private ou AllScope.
Por exemplo:
@{Name="Get-PowerShellProcess";ScriptBlock={Get-Process PowerShell};Options="AllScope"}
| Type: | IDictionary[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Guid
Especifica um identificador exclusivo para o arquivo de capacidade de função. Se você omitir esse parâmetro, New-PSRoleCapabilityFile gerará um GUID para o arquivo. Para criar um novo GUID no PowerShell, digite [guid]::NewGuid().
| Type: | Guid |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ModulesToImport
Especifica os módulos que são importados automaticamente para sessões que usam o arquivo de capacidade de função. Por padrão, todos os comandos nos módulos listados são visíveis. Quando usado com VisibleCmdlets ou VisibleFunctions, os comandos visíveis dos módulos especificados podem ser restritos.
Cada módulo utilizado no valor deste parâmetro pode ser representado por uma cadeia ou por uma tabela hash. Uma cadeia de caracteres de módulo consiste apenas no nome do módulo. Uma tabela de hash de módulo pode incluir chaves ModuleName, ModuleVersion e GUID . Apenas a chave ModuleName é necessária.
Por exemplo, o seguinte valor consiste numa cadeia e numa tabela hash. Qualquer combinação de cadeias e tabelas hash, em qualquer ordem, é válida.
"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Path
Especifica o caminho e o nome do arquivo de recurso da função. O arquivo deve ter uma .psrc extensão de nome de arquivo.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ScriptsToProcess
Especifica scripts a serem adicionados a sessões que usam o arquivo de capacidade de função. Insira o caminho e os nomes de arquivo dos scripts. O valor desse parâmetro deve ser um caminho completo ou absoluto dos nomes de arquivo de script.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TypesToProcess
Especifica arquivos de tipo (.ps1xml) para adicionar a sessões que usam o arquivo de capacidade de função. Insira os nomes dos arquivos do tipo. O valor desse parâmetro deve ser um caminho completo ou absoluto do tipo filenames.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VariableDefinitions
Especifica variáveis a serem adicionadas a sessões que usam o arquivo de capacidade de função. Introduza uma tabela hash com as seguintes chaves:
- Nome. Nome da variável. Esta chave é necessária.
- Valor. Valor da variável. Esta chave é necessária.
Por exemplo: @{Name="WarningPreference";Value="SilentlyContinue"}
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VisibleAliases
Limita os aliases na sessão aos aliases especificados no valor desse parâmetro, além de quaisquer aliases definidos no parâmetro AliasDefinition . Caracteres curinga são suportados. Por padrão, todos os aliases definidos pelo mecanismo do PowerShell e todos os aliases exportados pelos módulos são visíveis na sessão.
Por exemplo, para limitar os aliases disponíveis a gm e gcm, use esta sintaxe: VisibleAliases="gcm", "gp"
Quando qualquer parâmetro Visible é incluído no arquivo de capacidade de função, o PowerShell remove o Import-Module cmdlet e seu ipmo alias da sessão.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-VisibleCmdlets
Limita os cmdlets na sessão aos especificados no valor desse parâmetro. Há suporte para caracteres curinga e nomes qualificados de módulo.
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, New-PSRoleCapabilityFile tente carregar o módulo apropriado.
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.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-VisibleExternalCommands
Limita os binários, scripts e comandos externos que podem ser executados na sessão aos especificados no valor desse parâmetro.
Por padrão, nenhum comando externo é visível nesta 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.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VisibleFunctions
Limita as funções na sessão àquelas especificadas no valor desse parâmetro, além de quaisquer funções definidas no parâmetro FunctionDefinitions . Caracteres curinga são suportados.
Por padrão, todas as funções exportadas pelos módulos na sessão são visíveis nessa 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.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-VisibleProviders
Limita os provedores do PowerShell na sessão aos especificados no valor desse parâmetro. Caracteres curinga são suportados.
Por padrão, todos os provedores exportados por um módulo na sessão 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.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
Ligações Relacionadas
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários