1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2020, Brian Scholer <@briantist>
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7DOCUMENTATION = r'''
8---
9module: win_psmodule_info
10short_description: Gather information about PowerShell Modules
11description:
12  - Gather information about PowerShell Modules including information from PowerShellGet.
13options:
14  name:
15    description:
16      - The name of the module to retrieve.
17      - Supports any wildcard pattern supported by C(Get-Module).
18      - If omitted then all modules will returned.
19    type: str
20    default: '*'
21  repository:
22    description:
23      - The name of the PSRepository the modules were installed from.
24      - This acts as a filter against the modules that would be returned based on the I(name) option.
25      - Modules that were not installed from a repository will not be returned if this option is set.
26      - Only modules installed from a registered repository will be returned.
27      - If the repository was re-registered after module installation with a new C(SourceLocation), this will not match.
28    type: str
29requirements:
30  - C(PowerShellGet) module
31seealso:
32  - module: community.windows.win_psrepository_info
33  - module: community.windows.win_psscript_info
34author:
35  - Brian Scholer (@briantist)
36'''
37
38EXAMPLES = r'''
39- name: Get info about all modules on the system
40  community.windows.win_psmodule_info:
41
42- name: Get info about the ScheduledTasks module
43  community.windows.win_psmodule_info:
44    name: ScheduledTasks
45
46- name: Get info about networking modules
47  community.windows.win_psmodule_info:
48    name: Net*
49
50- name: Get info about all modules installed from the PSGallery repository
51  community.windows.win_psmodule_info:
52    repository: PSGallery
53  register: gallery_modules
54
55- name: Update all modules retrieved from above example
56  community.windows.win_psmodule:
57    name: "{{ item }}"
58    state: latest
59  loop: "{{ gallery_modules.modules | map(attribute=name) }}"
60
61- name: Get info about all modules on the system
62  community.windows.win_psmodule_info:
63  register: all_modules
64
65- name: Find modules installed from a repository that isn't registered now
66  set_fact:
67    missing_repository_modules: "{{
68      all_modules
69      | json_query('modules[?repository!=null && repository==repository_source_location].{name: name, version: version, repository: repository}')
70      | list
71    }}"
72
73- debug:
74    var: missing_repository_modules
75'''
76
77RETURN = r'''
78modules:
79  description:
80    - A list of modules (or an empty list is there are none).
81  returned: always
82  type: list
83  elements: dict
84  contains:
85    name:
86      description:
87        - The name of the module.
88      type: str
89      sample: PSReadLine
90    version:
91      description:
92        - The module version.
93      type: str
94      sample: 1.2.3
95    guid:
96      description:
97        - The GUID of the module.
98      type: str
99      sample: 74c9fd30-734b-4c89-a8ae-7727ad21d1d5
100    path:
101      description:
102        - The path to the module.
103      type: str
104      sample: 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\PKI\PKI.psd1'
105    module_base:
106      description:
107        - The path that contains the module's files.
108      type: str
109      sample: 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\PKI'
110    installed_location:
111      description:
112        - The path where the module is installed.
113        - This should have the same value as C(module_base) but only has a value when the module was installed via PowerShellGet.
114      type: str
115      sample: 'C:\Program Files\WindowsPowerShell\Modules\posh-git\0.7.1'
116    exported_aliases:
117      description:
118        - The aliases exported from the module.
119      type: list
120      elements: str
121      sample:
122        - glu
123        - slu
124    exported_cmdlets:
125      description:
126        - The cmdlets exported from the module.
127      type: list
128      elements: str
129      sample:
130        - Get-Certificate
131        - Get-PfxData
132    exported_commands:
133      description:
134        - All of the commands exported from the module. Includes functions, cmdlets, and aliases.
135      type: list
136      elements: str
137      sample:
138        - glu
139        - Get-LocalUser
140    exported_dsc_resources:
141      description:
142        - The DSC resources exported from the module.
143      type: list
144      elements: str
145      sample:
146        - xWebAppPool
147        - xWebSite
148    exported_format_files:
149      description:
150        - The format files exported from the module.
151      type: list
152      elements: path
153      sample:
154        - 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\DnsClient\DnsCmdlets.Format.ps1xml'
155        - 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\DnsClient\DnsConfig.Format.ps1xml'
156        - 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\DnsClient\DnsClientPSProvider.Format.ps1xml'
157    exported_functions:
158      description:
159        - The functions exported from the module.
160      type: list
161      elements: str
162      sample:
163        - New-VirtualDisk
164        - New-Volume
165    exported_type_files:
166      description:
167        - The type files exported from the module.
168      type: list
169      elements: path
170      sample:
171        - 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\DnsClient\DnsCmdlets.Types.ps1xml'
172        - 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\DnsClient\DnsConfig.Types.ps1xml'
173        - 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\DnsClient\DnsClientPSProvider.Types.ps1xml'
174    exported_variables:
175      description:
176        - The variables exported from the module.
177      type: list
178      elements: str
179      sample:
180        - GitPromptScriptBlock
181    exported_workflows:
182      description:
183        - The workflows exported from the module.
184      type: list
185      elements: str
186    access_mode:
187      description:
188        - The module's access mode. See U(https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.moduleaccessmode)
189      type: str
190      sample: ReadWrite
191    module_type:
192      description:
193        - The module's type. See U(https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.moduletype)
194      type: str
195      sample: Script
196    procoessor_architecture:
197      description:
198        - The module's processor architecture. See U(https://docs.microsoft.com/en-us/dotnet/api/system.reflection.processorarchitecture)
199      type: str
200      sample: Amd64
201    author:
202      description:
203        - The author of the module.
204      type: str
205      sample: Warren Frame
206    copyright:
207      description:
208        - The copyright of the module.
209      type: str
210      sample: '(c) 2016 Warren F. All rights reserved.'
211    company_name:
212      description:
213        - The company name of the module.
214      type: str
215      sample: Microsoft Corporation
216    description:
217      description:
218        - The description of the module.
219      type: str
220      sample: Provides cmdlets to work with local users and local groups
221    clr_version:
222      description:
223        - The CLR version of the module.
224      type: str
225      sample: '4.0'
226    compatible_ps_editions:
227      description:
228        - The PS Editions the module is compatible with.
229      type: list
230      elements: str
231      sample:
232        - Desktop
233    dependencies:
234      description:
235        - The modules required by this module.
236      type: list
237      elements: str
238    dot_net_framework_version:
239      description:
240        - The .Net Framework version of the module.
241      type: str
242      sample: '4.6.1'
243    file_list:
244      description:
245        - The files included in the module.
246      type: list
247      elements: path
248      sample:
249        - 'C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.6.0\PSModule.psm1'
250        - 'C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.6.0\PSGet.Format.ps1xml'
251        - 'C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.6.0\PSGet.Resource.psd1'
252    help_info_uri:
253      description:
254        - The help info address of the module.
255      type: str
256      sample: 'https://go.microsoft.com/fwlink/?linkid=390823'
257    icon_uri:
258      description:
259        - The address of the icon of the module.
260      type: str
261      sample: 'https://raw.githubusercontent.com/powershell/psscriptanalyzer/master/logo.png'
262    license_uri:
263      description:
264        - The address of the license for the module.
265      type: str
266      sample: 'https://github.com/PowerShell/xPendingReboot/blob/master/LICENSE'
267    project_uri:
268      description:
269        - The address of the module's project.
270      type: str
271      sample: 'https://github.com/psake/psake'
272    repository_source_location:
273      description:
274        - The source location of the repository where the module was installed from.
275      type: str
276      sample: 'https://www.powershellgallery.com/api/v2'
277    repository:
278      description:
279        - The PSRepository where the module was installed from.
280        - This value is not historical. It depends on the PSRepositories that are registered now for the current user.
281        - The C(repository_source_location) must match the current source location of a registered repository to get a repository name.
282        - If there is no match, then this value will match C(repository_source_location).
283      type: str
284      sample: PSGallery
285    release_notes:
286      description:
287        - The module's release notes. This is a free text field and no specific format should be assumed.
288      type: str
289      sample: |
290        ## 1.4.6
291        - Update `HelpInfoUri` to point to the latest content
292
293        ## 1.4.5
294        - Bug fix for deadlock when getting parameters in an event
295
296        ## 1.4.4
297        - Bug fix when installing modules from private feeds
298    installed_date:
299      description:
300        - The date the module was installed.
301      type: str
302      sample: '2018-02-14T17:55:34.9620740-05:00'
303    published_date:
304      description:
305        - The date the module was published.
306      type: str
307      sample: '2017-03-15T04:18:09.0000000'
308    updated_date:
309      description:
310        - The date the module was last updated.
311      type: str
312      sample: '2019-12-31T09:20:02.0000000'
313    log_pipeline_execution_details:
314      description:
315        - Determines whether pipeline execution detail events should be logged.
316      type: bool
317    module_list:
318      description:
319        - A list of modules packaged with this module.
320        - This value is not often returned and the modules are not automatically processed.
321      type: list
322      elements: dict
323      contains:
324        name:
325          description:
326            - The name of the module.
327            - This may also be a path to the module file.
328          type: str
329          sample: '.\WindowsUpdateLog.psm1'
330        guid:
331          description:
332            - The GUID of the module.
333          type: str
334          sample: 82fdb72c-ecc5-4dfd-b9d5-83cf6eb9067f
335        version:
336          description:
337            - The minimum version of the module.
338          type: str
339          sample: '2.0'
340        maximum_version:
341          description:
342            - The maximum version of the module.
343          type: str
344          sample: '2.9'
345        required_version:
346          description:
347            - The exact version of the module required.
348          type: str
349          sample: '3.1.4'
350    nested_modules:
351      description:
352        - A list of modules nested with and loaded into the scope of this module.
353        - This list contains full module objects, so each item can have all of the properties listed here, including C(nested_modules).
354      type: list
355      elements: dict
356    required_modules:
357      description:
358        - A list of modules required by this module.
359        - This list contains full module objects, so each item can have all of the properties listed here, including C(required_modules).
360        - These module objects may not contain full information however, so you may see different results than if you had directly queried the module.
361      type: list
362      elements: dict
363    required_assemblies:
364      description:
365        - A list of assemblies that the module requires.
366        - The values may be a simple name or a full path.
367      type: str
368      sample:
369        - Microsoft.Management.Infrastructure.CimCmdlets.dll
370        - Microsoft.Management.Infrastructure.Dll
371    package_management_provider:
372      description:
373        - If the module was installed from PowerShellGet, this is the package management provider used.
374      type: str
375      sample: NuGet
376    power_shell_host_name:
377      description:
378        - The name of the PowerShell host that the module requires.
379      type: str
380      sample: Windows PowerShell ISE Host
381    power_shell_host_version:
382      description:
383        - The version of the PowerShell host that the module requires.
384      type: str
385      sample: '1.1'
386    power_shell_version:
387      description:
388        - The minimum version of PowerShell that the module requires.
389      type: str
390      sample: '5.1'
391    prefix:
392      description:
393        - The default prefix applied to C(Verb-Noun) commands exported from the module, resulting in C(Verb-PrefixNoun) names.
394      type: str
395    private_data:
396      description:
397        - Arbitrary private data used by the module. This is typically defined in the module manifest.
398        - This module limits the depth of the data returned for module types other than C(Script) and C(Manifest).
399        - The C(PSData) is commonly supplied and provides metadata for PowerShellGet but those fields are surfaced in top-level properties as well.
400      type: dict
401      sample:
402        PSData:
403          LicenseUri: https://example.com/module/LICENSE
404          ProjectUri: https://example.com/module/
405          ReleaseNotes: |
406            v2 - Fixed some bugs
407            v1 - First release
408          Tags:
409            - networking
410            - serialization
411    root_module:
412      description:
413        - The root module as defined in the manifest.
414        - This may be a module name, filename, or full path.
415      type: str
416      sample: WindowsErrorReporting.psm1
417    scripts:
418      description:
419        - A list of scripts (C(.ps1) files) that run in the caller's session state when the module is imported.
420        - This value comes from the C(ScriptsToProcess) field in the module's manifest.
421      type: list
422      sample:
423        - PrepareEnvironment.ps1
424        - InitializeData.ps1
425    tags:
426      description:
427        - The tags defined in the module's C(PSData) metadata.
428      type: list
429      elements: str
430      sample:
431        - networking
432        - serialization
433        - git
434        - dsc
435'''
436