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