Compartilhar via

New-PSRoleCapabilityFile

  • Referência
Módulo:
Microsoft.PowerShell.Core

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 cmdlet New-PSRoleCapabilityFile cria um arquivo que define um conjunto de recursos de 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 por humanos 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 para o parâmetro Path, que especifica o caminho do 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 de 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 um RoleCapabilities subpasta 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 .pssc (Configuração de Sessão do PowerShell).

Este 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). Posteriormente, o arquivo pode ser editado 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 permitindo 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 para a expressão regular VDI\d+.

$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 @roleParameters

Parâmetros

-AliasDefinitions

Adiciona os aliases especificados às sessões que usam o arquivo de funcionalidade 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 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

-CompanyName

Identifica a empresa que criou o arquivo de funcionalidade 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, gerará uma instrução de direitos autorais usando o valor do parâmetro autor do .

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

-EnvironmentVariables

Especifica as variáveis de ambiente para sessões que expõem esse arquivo de funcionalidade de função. Insira uma tabela de hash na qual as chaves são os nomes das variáveis de ambiente e os valores são os valores da variável 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) 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 a sessões que expõem a funcionalidade de 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 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 funcionalidade de função. Por padrão, todos os comandos nos módulos listados são visíveis. Quando usados 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 cadeia de caracteres ou por uma tabela de hash. Uma cadeia de caracteres de módulo consiste apenas no nome do módulo. Uma tabela de hash de módulo pode incluir ModuleName, ModuleVersione chaves de GUID. Somente a chave ModuleName é necessária.

Por exemplo, o valor a seguir 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 funcionalidade da função. O arquivo deve ter uma extensão de nome de arquivo .psrc.

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 a sessões que usam o arquivo de funcionalidade 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.

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

-TypesToProcess

Especifica arquivos de tipo (.ps1xml) a serem adicionados às sessões que usam o arquivo de funcionalidade de função. Insira os nomes de arquivo de tipo. O valor desse parâmetro deve ser um caminho completo ou absoluto dos nomes de arquivo de tipo.

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 a 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.
  • Opções. Opções de variável. 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="WarningPreference";Value="SilentlyContinue";Options="AllScope"}

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 a esses 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 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 funcionalidade de função, o PowerShell remove o cmdlet Import-Module 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 aos especificados no valor desse parâmetro. Há suporte para caracteres curinga e Nomes Qualificados do Módulo.

Por padrão, todos os cmdlets que os módulos na exportação de sessão estã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 no ModulesToImport expor o cmdlet, New-PSRoleCapabilityFile tentar carregar o módulo apropriado.

Quando qualquer parâmetro Visible é incluído no arquivo de configuração de sessão, o PowerShell remove o cmdlet Import-Module 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 externos, scripts e comandos que podem ser executados na sessão aos especificados no valor desse parâmetro.

Por padrão, nenhum comando externo está visível nesta sessão.

Quando qualquer parâmetro Visible é incluído no arquivo de configuração de sessão, o PowerShell remove o cmdlet Import-Module 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:False

-VisibleFunctions

Limita as funções na sessão às especificadas no valor desse parâmetro, além de quaisquer funções que você definir 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 de sessão, o PowerShell remove o cmdlet Import-Module 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 exportados por um módulo na sessão ficam 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 de sessão, o PowerShell remove o cmdlet Import-Module 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