1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2018, Wojciech Sciesinski <wojciech[at]sciesinski[dot]net> 5# Copyright: (c) 2017, Daniele Lazzari <lazzari@mailup.com> 6# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 7 8DOCUMENTATION = r''' 9--- 10module: win_psmodule 11short_description: Adds or removes a Windows PowerShell module 12description: 13 - This module helps to install Windows PowerShell modules and register custom modules repository on Windows-based systems. 14options: 15 name: 16 description: 17 - Name of the Windows PowerShell module that has to be installed. 18 type: str 19 required: yes 20 state: 21 description: 22 - If C(present) a new module is installed. 23 - If C(absent) a module is removed. 24 - If C(latest) a module is updated to the newest version. 25 type: str 26 choices: [ absent, latest, present ] 27 default: present 28 required_version: 29 description: 30 - The exact version of the PowerShell module that has to be installed. 31 type: str 32 minimum_version: 33 description: 34 - The minimum version of the PowerShell module that has to be installed. 35 type: str 36 maximum_version: 37 description: 38 - The maximum version of the PowerShell module that has to be installed. 39 type: str 40 allow_clobber: 41 description: 42 - If C(yes) allows install modules that contains commands those have the same names as commands that already exists. 43 type: bool 44 default: no 45 skip_publisher_check: 46 description: 47 - If C(yes), allows you to install a different version of a module that already exists on your computer in the case when a different one 48 is not digitally signed by a trusted publisher and the newest existing module is digitally signed by a trusted publisher. 49 type: bool 50 default: no 51 allow_prerelease: 52 description: 53 - If C(yes) installs modules marked as prereleases. 54 - It doesn't work with the parameters C(minimum_version) and/or C(maximum_version). 55 - It doesn't work with the C(state) set to absent. 56 type: bool 57 default: no 58 repository: 59 description: 60 - Name of the custom repository to use. 61 type: str 62 url: 63 description: 64 - URL of the custom repository to register. 65 - DEPRECATED, will be removed in a major release after C(2021-07-01), please use the 66 M(community.windows.win_psrepository) module instead. 67 type: str 68notes: 69 - PowerShell modules needed 70 - PowerShellGet >= 1.6.0 71 - PackageManagement >= 1.1.7 72 - PowerShell package provider needed 73 - NuGet >= 2.8.5.201 74 - On PowerShell 5.x required modules and a package provider will be updated under the first run of the win_psmodule module. 75 - On PowerShell 3.x and 4.x you have to install them before using the win_psmodule. 76seealso: 77- module: community.windows.win_psrepository 78author: 79- Wojciech Sciesinski (@it-praktyk) 80- Daniele Lazzari (@dlazz) 81''' 82 83EXAMPLES = r''' 84--- 85- name: Add a PowerShell module 86 community.windows.win_psmodule: 87 name: PowerShellModule 88 state: present 89 90- name: Add an exact version of PowerShell module 91 community.windows.win_psmodule: 92 name: PowerShellModule 93 required_version: "4.0.2" 94 state: present 95 96- name: Install or update an existing PowerShell module to the newest version 97 community.windows.win_psmodule: 98 name: PowerShellModule 99 state: latest 100 101- name: Install newer version of built-in Windows module 102 community.windows.win_psmodule: 103 name: Pester 104 skip_publisher_check: yes 105 state: present 106 107- name: Add a PowerShell module and register a repository 108 community.windows.win_psmodule: 109 name: MyCustomModule 110 repository: MyRepository 111 state: present 112 113- name: Add a PowerShell module from a specific repository 114 community.windows.win_psmodule: 115 name: PowerShellModule 116 repository: MyRepository 117 state: present 118 119- name: Remove a PowerShell module 120 community.windows.win_psmodule: 121 name: PowerShellModule 122 state: absent 123''' 124 125RETURN = r''' 126--- 127output: 128 description: A message describing the task result. 129 returned: always 130 sample: "Module PowerShellCookbook installed" 131 type: str 132nuget_changed: 133 description: True when Nuget package provider is installed. 134 returned: always 135 type: bool 136 sample: true 137repository_changed: 138 description: True when a custom repository is installed or removed. 139 returned: always 140 type: bool 141 sample: true 142''' 143