Find-DscResource

Reference

Module:: PowerShellGet

Finds Desired State Configuration (DSC) resources.

Syntax

Find-DscResource
    [[-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-DscResource cmdlet searches registered repositories to find DSC resources contained in modules. By default Find-DscResource searches all registered repositories.

For each module found by Find-DscResource, a PSGetDscResourceInfo object is returned. PSGetDscResourceInfo objects can be sent down the pipeline to the Install-Module cmdlet. Install-Module installs the module.

Examples

Example 1: Find all DSC resources

Find-DscResource returns DSC resources from registered repositories. To search a specific repository, use the Repository parameter.

Find-DscResource

Name                           Version    ModuleName                     Repository
----                           -------    ----------                     ----------
Carbon_Privilege               2.8.1      Carbon                         PSGallery
Carbon_ScheduledTask           2.8.1      Carbon                         PSGallery
Carbon_Service                 2.8.1      Carbon                         PSGallery
PackageManagement              1.4        PackageManagement              PSGallery
PackageManagementSource        1.4        PackageManagement              PSGallery
PSModule                       2.1.4      PowerShellGet                  PSGallery
PSRepository                   2.1.4      PowerShellGet                  PSGallery
xArchive                       8.7.0.0    xPSDesiredStateConfiguration   PSGallery
xDSCWebService                 8.7.0.0    xPSDesiredStateConfiguration   PSGallery
xEnvironment                   8.7.0.0    xPSDesiredStateConfiguration   PSGallery

Example 2: Find a DSC resource by name

Find-DscResource locates DSC resources by name. Use commas to separate an array of resource names.

Find-DscResource -Name xWebsite, xWebApplication, xWebSiteDefaults

Name               Version    ModuleName            Repository
----               -------    ----------            ----------
xWebApplication    2.6.0.0    xWebAdministration    PSGallery
xWebsite           2.6.0.0    xWebAdministration    PSGallery
xWebSiteDefaults   2.6.0.0    xWebAdministration    PSGallery

Find-DscResource uses the Name parameter to find the specified array of DSC resources.

Example 3: Find a DSC resource and install it

Find-DscResource locates a DSC resource and sends the object down the pipeline to be installed. After the installation, use Get-InstalledModule to view the results.

Multiple resources from the same module can be sent down the pipeline to the Install-Module. Install-Module attempts to only install the module once.

Find-DscResource -Name xWebsite | Install-Module

Find-DscResource uses the Name parameter to find the resource named xWebsite. The object is sent down the pipeline to the Install-Module cmdlet. Install-Module installs the xWebAdministration module for the resource.

Example 4: Find all DSC resources in a module

Find-DscResource finds all the DSC resources contained in a specified module. By default, the current version is displayed. To display other versions, use the AllVersions or RequiredVersions parameters.

Find-DscResource -ModuleName xWebAdministration

Name                                Version    ModuleName              Repository
----                                -------    ----------              ----------
WebApplicationHandler               2.6.0.0    xWebAdministration      PSGallery
xIisFeatureDelegation               2.6.0.0    xWebAdministration      PSGallery
xIisHandler                         2.6.0.0    xWebAdministration      PSGallery
xIisLogging                         2.6.0.0    xWebAdministration      PSGallery

Find-DscResource uses the ModuleName parameter to specify the xWebAdministration and find the DSC resources contained in the module. The current version of each resource is displayed.

Example 5: Find a DSC resource by tag and required version

DSC resources can be located using the parameters Tag and RequiredVersion. Tag displays the current version of every resource that contains the specified tag in the repository. RequiredVersion needs the ModuleName parameter and the Name parameter is optional. The Name and ModuleName parameters limit the output. Use the AllVersions parameter to display a DSC resource's available versions.

Find-DscResource -ModuleName xWebAdministration -Tag DSC -RequiredVersion 1.20

Name                    Version    ModuleName             Repository
----                    -------    ----------             ----------
xIisFeatureDelegation   1.20.0.0   xWebAdministration     PSGallery
xIisHandler             1.20.0.0   xWebAdministration     PSGallery
xIisLogging             1.20.0.0   xWebAdministration     PSGallery
xIisMimeTypeMapping     1.20.0.0   xWebAdministration     PSGallery

Example 6: Find a resource by using a filter

Find-DscResource finds all resources and uses the Filter parameter to specify the results by Domain. The Filter parameter finds the filter value in the object's description or module name. Use the Select-Object cmdlet to view an object's properties.

Find-DscResource -Filter Domain

Name                    Version    ModuleName                 Repository
----                    -------    ----------                 ---------
xComputer               4.1.0.0    xComputerManagement        PSGallery
Computer                6.4.0.0    ComputerManagementDsc      PSGallery
xDSCDomainjoin          1.1        xDSCDomainjoin             PSGallery
xDisk                   1.0        xDisk                      PSGallery
xDSCFirewall            1.6.21     xDSCFirewall               PSGallery
dmAwsTagInstance        1.0.1      domainAwsDSCResources      PSGallery

Parameters

-AllowPrerelease

Includes resources marked as a prerelease in the results.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-AllVersions

The AllVersions parameter displays each of a DSC resource's available versions. You can't use the AllVersions parameter with the MinimumVersion, MaximumVersion, or RequiredVersion parameters.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Filter

Finds resources based on the PackageManagement provider's search syntax. For example, specify words to search for within the ModuleName and Description properties.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumVersion

Specifies the maximum version of the resource to include in results. The MaximumVersion and the RequiredVersion parameters can't be used in the same command.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MinimumVersion

Specifies the minimum version of the resource to include in results. The MinimumVersion and the RequiredVersion parameters can't be used in the same command.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ModuleName

Specifies a module that contains the DSC resource.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

Specifies the name of a resource. The default is all resources. Use commas to separate an array of resource names.

Type:	String[]
Position:	0
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Proxy

Specifies a proxy server for the request, rather than a direct connection to the internet resource.

Type:	Uri
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ProxyCredential

Specifies a user account with permission to use the proxy server specified in the Proxy parameter.

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Repository

Specifies a repository to search for resources. Use commas to separate an array of repository names.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RequiredVersion

Specifies the module's exact version number to include in the results. The RequiredVersion and the MinimumVersion parameters can't be used in the same command.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Tag

Specifies tags that categorize modules in a repository. Use commas to separate an array of tags.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Outputs

PSGetDscResourceInfo

Find-DscResource returns a PSGetDscResourceInfo object.

Notes

Important

As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS 1.2:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

For more information, see the announcement in the PowerShell blog.

Find-DscResource

Syntax

Description

Examples

Example 1: Find all DSC resources

Example 2: Find a DSC resource by name

Example 3: Find a DSC resource and install it

Example 4: Find all DSC resources in a module

Example 5: Find a DSC resource by tag and required version

Example 6: Find a resource by using a filter

Parameters

-AllowPrerelease

-AllVersions

-Filter

-MaximumVersion

-MinimumVersion

-ModuleName

-Name

-Proxy

-ProxyCredential

-Repository

-RequiredVersion

-Tag

Outputs

Notes

Feedback

Additional resources

Find-DscResource

Syntax

Description

Examples

Example 1: Find all DSC resources

Example 2: Find a DSC resource by name

Example 3: Find a DSC resource and install it

Example 4: Find all DSC resources in a module

Example 5: Find a DSC resource by tag and required version

Example 6: Find a resource by using a filter

Parameters

-AllowPrerelease

-AllVersions

-Filter

-MaximumVersion

-MinimumVersion

-ModuleName

-Name

-Proxy

-ProxyCredential

-Repository

-RequiredVersion

-Tag

Outputs

Notes

Related Links

Feedback

Additional resources