Public/Get-PAPlugin.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
function Get-PAPlugin {
    [CmdletBinding(DefaultParameterSetName='Basic')]
    param(
        [Parameter(ParameterSetName='Basic', Position=0)]
        [Parameter(ParameterSetName='Help', Position=0, Mandatory)]
        [Parameter(ParameterSetName='Guide', Position=0, Mandatory)]
        [Parameter(ParameterSetName='Params', Position=0, Mandatory)]
        [ValidateScript({Test-ValidPlugin $_ -ThrowOnFail})]
        [string]$Plugin,
        [Parameter(ParameterSetName='Help', Mandatory)]
        [switch]$Help,
        [Parameter(ParameterSetName='Guide', Mandatory)]
        [switch]$Guide,
        [Parameter(ParameterSetName='Params', Mandatory)]
        [switch]$Params
    )

    # return the list of plugin details if a specific plugin wasn't specified
    if ([String]::IsNullOrWhiteSpace($Plugin)) {
        $script:Plugins.Values | Sort-Object Name
        return
    }

    $pluginDetail = $script:Plugins.$Plugin

    if ('Basic' -eq $PSCmdlet.ParameterSetName) {
        # return specific plugin details
        return $pluginDetail
    }

    # dot source the plugin
    . $pluginDetail.Path

    # get a reference to the associated add command
    if ('dns-01' -eq $pluginDetail.ChallengeType) {
        $cmd = Get-Command Add-DnsTxt
    } else {
        $cmd = Get-Command Add-HttpChallenge
    }

    if ('Params' -eq $PSCmdlet.ParameterSetName) {

        # define the set of parameter names to ignore
        $ignoreParams = @('RecordName','TxtValue','Domain','Token','Body') + [Management.Automation.PSCmdlet]::CommonParameters +
            [Management.Automation.PSCmdlet]::OptionalCommonParameters

        # Now we want to make a flattened list of parameters that are tagged with
        # their associated parameter set data to enable our custom output formatting
        $paramFlatList = foreach ($set in $cmd.ParameterSets) {

            $setParams = $set.Parameters | Where-Object {
                $_.Name -notin $ignoreParams -and
                $true -notin $_.Attributes.ValueFromRemainingArguments
            }

            $setParams | ForEach-Object {

                $setName = $set.Name
                if ($setName -eq '__AllParameterSets') {
                    $setName = '(Default)'
                }

                [pscustomobject]@{
                    PSTypeName = 'PoshACME.PluginParameter'
                    ParameterSet = $setName
                    IsDefault = $set.IsDefault
                    Parameter = $_.Name
                    ParameterType = $_.ParameterType
                    IsMandatory = $_.IsMandatory
                }
            }
        }
        return $paramFlatList
    }

    elseif ('Guide' -eq $PSCmdlet.ParameterSetName) {
        # Currently opening a browser this way only works on Windows, but we're
        # tracking this issue for potentially better cross-platform solutions in
        # the future.
        # https://github.com/PowerShell/PowerShell/issues/7201

        $url = "https://github.com/rmbolger/Posh-ACME/blob/main/Posh-ACME/Plugins/$($pluginDetail.Name)-Readme.md"

        try {
            # launch the browser to the guide
            Start-Process $url
        } catch {
            # just return the URL
            $url
        }
        return
    }

    elseif ('Help' -eq $PSCmdlet.ParameterSetName) {

        if ('dns-01' -eq $pluginDetail.ChallengeType) {
            Get-Help Add-DnsTxt
        } else {
            Get-Help Add-HttpChallenge
        }
        return
    }



    <#
    .SYNOPSIS
        Show plugin details, help, or launch the online guide.
 
    .DESCRIPTION
        With no parameters, this function will return a list of built-in validation plugins and their details.
 
        With a Plugin specified, this function will return that plugin's details, help, or launch the online guide depending on which switches are specified.
 
    .PARAMETER Plugin
        The name of a validation plugin.
 
    .PARAMETER Help
        If specified, display the help contents for the specified plugin.
 
    .PARAMETER Guide
        If specified, launch the default web browser to the specified plugin's online guide. This currently only works on Windows and will simply display the URL on other OSes.
 
    .PARAMETER Params
        If specified, returns the plugin-specific parameter sets associated with this plugin.
 
    .EXAMPLE
        Get-PAPlugin
 
        Get the list of available validation plugins
 
    .EXAMPLE
        Get-PAPlugin Route53 -Guide
 
        Launch the user's default web browser to the online guide for the specified plugin.
 
    .LINK
        Project: https://github.com/rmbolger/Posh-ACME
 
    .LINK
        New-PACertificate
 
    .LINK
        Publish-Challenge
 
    #>

}