Find-RoleCapability

Syntax

Find-RoleCapability
    [[-Name] <String[]>]
    [-ModuleName <String>]
    [-MinimumVersion <String>]
    [-MaximumVersion <String>]
    [-RequiredVersion <String>]
    [-AllVersions]
    [-AllowPrerelease]
    [-Tag <String[]>]
    [-Filter <String>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-Repository <String[]>]
    [<CommonParameters>]

Description

The Find-RoleCapability cmdlet searches registered repositories to find PowerShell role capabilities and modules.

For each role capability found by Find-RoleCapability, a PSGetRoleCapabilityInfo object is returned. PSGetRoleCapabilityInfo objects can be sent down the pipeline to the Install-Module or Save-Module cmdlets.

PowerShell role capabilities define which commands and applications are available to a user at a Just Enough Administration (JEA) endpoint. Role capabilities are defined by files with a .psrc extension.

Examples

Example 1: Find role capabilities

Find-RoleCapability finds role capabilities in each registered repository. To search a specific repository, use the Repository parameter.

Find-RoleCapability

Name             Version    ModuleName     Repository
----             -------    ----------     ----------
General-Lev1     1.0        JeaExamples    PSGallery
General-Lev2     1.0        JeaExamples    PSGallery
IIS-Lev1         1.0        JeaExamples    PSGallery
IIS-Lev2         1.0        JeaExamples    PSGallery

Example 2: Find role capabilities by name

Find-RoleCapability finds role capabilities by name. Use commas to separate an array of names.

Find-RoleCapability -Name General-Lev1, IIS-Lev2

Name             Version    ModuleName     Repository
----             -------    ----------     ----------
General-Lev1     1.0        JeaExamples    PSGallery
IIS-Lev2         1.0        JeaExamples    PSGallery

Example 3: Find and save a role capability's module

The Find-RoleCapability cmdlet finds a role capability and sends the object down the pipeline. Save-Module saves the role capability's module to a file system. Get-ChildItem displays the contents of the module's directory.

PS> Find-RoleCapability -Name General-Lev1 | Save-Module -Path C:\Test\Modules

PS> Get-ChildItem -Path C:\Test\Modules\JeaExamples\1.0\

    Directory: C:\Test\Modules\JeaExamples\1.0

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----          6/4/2019    16:37                RoleCapabilities
-a----          2/5/2019    18:46           1702 CreateRegisterPSSC.ps1
-a----          2/5/2019    18:46           7656 JeaExamples.psd1
-a----         10/1/2018    08:16            595 JeaExamples.psm1

Find-RoleCapability uses the Name parameter to specify the General-Lev1 role capability. The object is sent down the pipeline. Save-Module uses the Path parameter for the file system location to save the module. After the module is saved, Get-ChildItem specifies the module's Path and displays the contents of the JeaExamples module's directory.

Example 4: Find and install a role capability's module

Find-RoleCapability finds the module and sends the object down the pipeline. Install-Module installs the module. After the installation, use Get-InstalledModule to see the results.

Find-RoleCapability -Name General-Lev1 | Install-Module -Verbose

VERBOSE: Downloading 'https://www.powershellgallery.com/api/v2/package/JeaExamples/1.0.0'.
VERBOSE: Completed downloading 'https://www.powershellgallery.com/api/v2/package/JeaExamples/1.0.0'.
VERBOSE: Completed downloading 'JeaExamples'.
VERBOSE: InstallPackageLocal' - name='JeaExamples', version='1.0',
VERBOSE: Validating the 'JeaExamples' module contents
VERBOSE: Test-ModuleManifest successfully validated the module manifest file
VERBOSE: Module 'JeaExamples' was installed successfully to path

Get-InstalledModule

Find-RoleCapability uses the Name parameter to specify the General-Lev1 role capability. The object is sent down the pipeline. Install-Module uses the Verbose parameter to display status messages during the installation. After the install is finished, the Get-InstalledModule output confirms that the JeaExamples module was installed.

Parameters

-AllowPrerelease

-AllVersions

-Filter

-MaximumVersion

-MinimumVersion

-ModuleName

-Name

-Proxy

-ProxyCredential

-Repository

-RequiredVersion

-Tag

Inputs

Uri

PSCredential

Outputs

PSGetRoleCapabilityInfo

The Find-RoleCapability cmdlet returns a PSGetRoleCapabilityInfo object.

Notes

Related Links

• Get-ChildItem
• Get-InstalledModule
• Install-Module
• New-PSRoleCapabilityFile
• Save-Module