Skip to content

Installation#

PSDocs for Azure supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates.

Running within CI#

Continue reading creating your pipeline to learn more.

Installing locally#

PSDocs for Azure can be installed locally from the PowerShell Gallery using PowerShell. You can also use this option to install on CI workers that are not natively supported.

The following platforms are supported:

  • Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater.
  • PowerShell 7.1 or greater on MacOS, Linux, and Windows.

PSDocs for Azure requires the PSDocs PowerShell module. The required version of PSDocs will automatically be installed along-side PSDocs for Azure.

Installing PowerShell#

PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default. For a list of platforms that PowerShell 7.1 is supported on and install instructions see Get PowerShell.

Getting the modules#

Module

PSDocs for Azure can be installed or updated from the PowerShell Gallery. Use the following command line examples from a PowerShell terminal to install or update PSDocs for Azure.

To install PSDocs for Azure for the current user use:

Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -Scope CurrentUser

To update PSDocs for Azure for the current user use:

Update-Module -Name 'PSDocs.Azure' -Repository PSGallery -Scope CurrentUser

This will automatically install compatible versions of all dependencies.

To install PSDocs for Azure for all users (requires admin/ root permissions) use:

Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -Scope AllUsers

To update PSDocs for Azure for all users (requires admin/ root permissions) use:

Update-Module -Name 'PSDocs.Azure' -Repository PSGallery -Scope AllUsers

This will automatically install compatible versions of all dependencies.

Pre-release versions#

To use a pre-release version of PSDocs for Azure add the -AllowPrerelease switch when calling Install-Module, Update-Module, or Save-Module cmdlets.

Tip

To install pre-release module versions, the latest version of PowerShellGet may be required.

# Install the latest PowerShellGet version
Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force

Building from source#

Source

PSDocs for Azure is provided as open source on GitHub. To build PSDocs for Azure from source code:

  1. Clone the GitHub repository.
  2. Run ./build.ps1 from a PowerShell terminal in the cloned path.

This build script will compile the module and documentation then output the result into out/modules/PSDocs.Azure.

Development dependencies#

The following PowerShell modules will be automatically install if the required versions are not present:

  • PlatyPS
  • Pester
  • PSScriptAnalyzer
  • PowerShellGet
  • PackageManagement
  • InvokeBuild

These additional modules are only required for building PSDocs for Azure.

Additionally .NET Core SDK v3.1 is required. .NET Core will not be automatically downloaded and installed. To download and install the latest SDK see Download .NET Core 3.1.

Limited access networks#

If you are on a network that does not permit Internet access to the PowerShell Gallery, download the required PowerShell modules on an alternative device that has access. PowerShell provides the Save-Module cmdlet that can be run from a PowerShell terminal to do this.

The following command lines can be used to download the required modules using a PowerShell terminal. After downloading the modules, copy the module directories to devices with restricted Internet access.

To save PSDocs for Azure for offline use:

$modules = @('PSDocs', 'PSDocs.Azure')
Save-Module -Name $modules -Path '.\modules'

This will save PSDocs for Azure and all dependencies into the modules sub-directory.

To save PSDocs for Azure development module dependencies for offline use:

$modules = @('PSDocs', 'PlatyPS', 'Pester', 'PSScriptAnalyzer',
  'PowerShellGet', 'PackageManagement', 'InvokeBuild')
Save-Module -Name $modules -Repository PSGallery -Path '.\modules';

This will save required developments dependencies into the modules sub-directory.

Last update: 2022-05-19