New-PSRoleCapabilityFile
Cria um arquivo que define um conjunto de recursos a serem expostos por meio de uma configuração de sessão.
Sintaxe
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 arquivo de funcionalidade é um arquivo de texto legível que contém uma tabela de hash de propriedades e valores de configuração de 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 de sessão será comentada, exceto quando indicado 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 da sessão será comentada.
Para usar o arquivo de funcionalidade 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).
Esse cmdlet foi introduzido no Windows PowerShell 5.0.
Exemplos
Exemplo 1: Criar um arquivo de funcionalidade de função em branco
Este exemplo cria um novo arquivo de funcionalidade 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 configurações.
New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"Exemplo 2: Criar um arquivo de funcionalidade de função que permita que os usuários reiniciem serviços e qualquer computador VDI
Este exemplo cria um arquivo de funcionalidade de função de exemplo que permite que os usuários reiniciem serviços e computadores que correspondam 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 às sessões que usam o arquivo de capacidade de funçã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 a serem carregados nas sessões que usam o arquivo de funcionalidade de funçã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 usuário que criou o arquivo de capacidade de função.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-CompanyName
Identifica a empresa que criou o arquivo de capacidade de função. O valor padrão é Desconhecido.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Copyright
Especifica um direito autoral para o arquivo de funcionalidade de função. Se você omitir esse parâmetro, New-PSRoleCapabilityFile 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 para o arquivo de capacidade de função.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-EnvironmentVariables
Especifica as variáveis de ambiente para sessões que expõem esse arquivo de capacidade de funçã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 |
-FormatsToProcess
Especifica os arquivos de formatação (.ps1xml) que são executados em sessões que usam o arquivo de funcionalidade de funçã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 |
-FunctionDefinitions
Adiciona as funções especificadas às sessões que expõem a funcionalidade da funçã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 |
-Guid
Especifica um identificador exclusivo para o arquivo de funcionalidade de função. Se você omitir esse parâmetro, New-PSRoleCapabilityFile o gerará um GUID para o arquivo. Para criar um novo GUID no PowerShell, digite [guid]::NewGuid().
| Tipo: | Guid |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | 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 usado no valor desse parâmetro pode ser representado por uma string ou por uma tabela de hash. Uma string de módulo consiste apenas no nome do módulo. 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"}
| Tipo: | Object[] |
| 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 capacidade da função. O arquivo deve ter uma extensão de nome de .psrc arquivo.
| Tipo: | String |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-ScriptsToProcess
Especifica scripts a serem adicionados às sessões que usam o arquivo de capacidade de função. Digite os nomes de arquivo e caminho dos scripts. O valor desse parâmetro deve ser um caminho completo ou absoluto dos 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 |
-TypesToProcess
Especifica os arquivos de tipo (.ps1xml) a serem adicionados às sessões que usam o arquivo de funcionalidade de função. Insira o tipo nomes de arquivo. O valor desse parâmetro deve ser um caminho completo ou absoluto do tipo nomes de arquivo.
| Tipo: | String[] |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-VariableDefinitions
Especifica variáveis a serem adicionadas às sessões que usam o arquivo de funcionalidade de funçã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 aliases 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, 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 funcionalidade de funçã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 |
-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, New-PSRoleCapabilityFile tentará 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.
| 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 deste 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.
| Tipo: | String[] |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-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 FunctionDefinitions . Há suporte para caracteres curinga.
Por padrão, todas as funções exportadas por 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.
| 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 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.
| Tipo: | String[] |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | True |
