New-PSRoleCapabilityFile

New-PSRoleCapabilityFile | Taking on PowerShell one cmdlet at a time | Weekly Blog

Share this post:

This is a part of an on-going blog series written by Adam Gordon. Each week, Adam will walk you through a PowerShell command, showing you when and how to use each one. This week, Adam covers New-PSRoleCapabilityFile.

When to use New-PSRoleCapabilityFile?

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 are 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 you run the cmdlet, the corresponding key in the session configuration file is commented-out, except where noted in the parameter description.

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.

What version of PowerShell am I using?

Get the PowerShell Version from your machine:

$PSVersionTable

This command shows you the PowerShell version information on your machine.

How to use New-PSRoleCapabilityFile?

Create a blank role capability file:

New-PSRoleCapabilityFile -Path “.\AdamITPTV.psrc”

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

Create a role capability file allowing users to restart services and any VDI computer:

$roleParameters = @{
Path = “.\VDIMaintenance.psrc”
Author = “Adam”
CompanyName = “ITPROTV”
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

This example creates a sample role capability file that enables users to restart services and computers that match a specific name pattern. Name filtering is defined by setting the –ValidatePattern parameter to the regular expression VDI\d+.

Learn last week’s command: New-PSSessionOption.

Need PowerShell training? Check out ITProTV’s PowerShell online IT training courses.