PowerShell Logo Small

New-PSRoleCapabilityFile



This is the built-in help made by Microsoft for the command 'New-PSRoleCapabilityFile', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Creates a file that defines a set of capabilities to be exposed through a session configuration.

SYNTAX


New-PSRoleCapabilityFile [-Path] <String> [-AliasDefinitions [<IDictionary[]>]] [-AssembliesToLoad [<String[]>]] [-Author [<String>]] [-CompanyName [<String>]] [-Copyright
[<String>]] [-Description [<String>]] [-EnvironmentVariables [<IDictionary>]] [-FormatsToProcess [<String[]>]] [-FunctionDefinitions [<IDictionary[]>]] [-Guid [<Guid>]]
[-ModulesToImport [<Object[]>]] [-ScriptsToProcess [<String[]>]] [-TypesToProcess [<String[]>]] [-VariableDefinitions [<Object>]] [-VisibleAliases [<String[]>]]
[-VisibleCmdlets [<Object[]>]] [-VisibleExternalCommands [<String[]>]] [-VisibleFunctions [<Object[]>]] [-VisibleProviders [<String[]>]] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


The New-PSRoleCapabilityFile cmdlet creates a file that defines a set of user capabilities that can be exposed through session configuration files; this includes determining
which cmdlets, functions, and scripts will be available to users. The capability file is a human-readable text file that contains a hash table of session configuration
properties and values. The file has a .psrc file name extension, and can be used by more than one session configuration.


All the parameters of New-PSRoleCapabilityFile are optional except for the Path parameter, which specifies the file path for the file. If you do not include a parameter when
running the cmdlet, the corresponding key in the session configuration file will be commented-out, except where noted in the parameter description. For example, if you do
not include the AssembliesToLoad parameter then that section of the session configuration file will be commented out.


To use the role capability file in a session configuration, first place the file in a RoleCapabilities subfolder of a valid PowerShell module folder, then reference the file
by name in the RoleDefinitions field in a PowerShell Session Configuration (.pssc) file.


This cmdlet was introduced in Windows PowerShell 5.0.



<

RELATED LINKS

Get-PSSessionCapability

REMARKS

<

Examples


Example 1

PS C:\> New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"



This command creates a new role capability file using the default (blank) values. The file can later be edited in a text editor to change these configuration settings.






Example 2

PS C:\> New-PSRoleCapabilityFile -Path ".\Maintenance.psrc" -Author "User01" -CompanyName "Fabrikam Corporation" -Description "This role capability 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+" }}



This command creates a sample role capability file that enables users to restart any service and to restart any computer that has a hostname beginning with the string value
"VDI" followed by a number (for example, VDI01, VDI02). Name filtering is carried out by setting the ValidatePattern parameter to the regular expression "VDI\d+".