Skip to content

Latest commit

 

History

History
193 lines (129 loc) · 9.24 KB

module-best-practices.md

File metadata and controls

193 lines (129 loc) · 9.24 KB
Raw

Module Best Practices

Module Metadata

Module Naming

Unless otherwise stated, the name of the module should be similar to that of provider called in the cmdlets. For example, if the cmdlets in a module called the Microsoft.Compute provider, then the module should be named Az.Compute.

Module Manifest

The module manifest file, found in the format of Az.MyService.psd1, contains all necessary metadata information about a module, and can be initially generated using the New-ModuleManifest cmdlet.

Below is sample Az.MyService.psd1 file that can be used as a template for new .psd1 files as well. Press the "Click to expand" text below to reveal the file:

Click to expand 

#
# Module manifest for module 'Az.MyService'
#
# Generated by: Microsoft Corporation
#
# Generated on: 3/11/2019
#

@{

# Script module or binary module file associated with this manifest.
# RootModule = ''

# Version number of this module.
ModuleVersion = '0.1.0'

# Supported PSEditions
CompatiblePSEditions = 'Core', 'Desktop'

# ID used to uniquely identify this module
GUID = '{{ GENERATE A RANDOM GUID TO USE HERE }}'

# Author of this module
Author = 'Microsoft Corporation'

# Company or vendor of this module
CompanyName = 'Microsoft Corporation'

# Copyright statement for this module
Copyright = 'Microsoft Corporation. All rights reserved.'

# Description of the functionality provided by this module
Description = ''

# Minimum version of the PowerShell engine required by this module
PowerShellVersion = '5.1'

# Name of the PowerShell host required by this module
# PowerShellHostName = ''

# Minimum version of the PowerShell host required by this module
# PowerShellHostVersion = ''

# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
DotNetFrameworkVersion = '4.7.2'

# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# CLRVersion = ''

# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''

# Modules that must be imported into the global environment prior to importing this module
RequiredModules = @(@{ModuleName = 'Az.Accounts'; ModuleVersion = '1.4.0'; })

# Assemblies that must be loaded prior to importing this module
RequiredAssemblies = '.\Microsoft.Azure.Management.MyService.dll'

# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()

# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()

# Format files (.ps1xml) to be loaded when importing this module
FormatsToProcess = '.\MyService.format.ps1xml'

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
NestedModules = '.\Microsoft.Azure.PowerShell.Cmdlets.MyService.dll'

# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = @()

# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = 'Get-AzMyServiceResource', 'New-AzMyServiceResource',
               'Remove-AzMyServiceResource', 'Update-AzMyServiceResource'

# Variables to export from this module
# VariablesToExport = @()

# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = @()

# DSC resources to export from this module
# DscResourcesToExport = @()

# List of all modules packaged with this module
# ModuleList = @()

# List of all files packaged with this module
# FileList = @()

# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{

    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = 'Azure','ResourceManager','ARM'

        # A URL to the license for this module.
        LicenseUri = 'https://aka.ms/azps-license'

        # A URL to the main website for this project.
        ProjectUri = 'https://github.com/Azure/azure-powershell'

        # A URL to an icon representing this module.
        # IconUri = ''

        # ReleaseNotes of this module
        ReleaseNotes = ''

        # Prerelease string of this module
        # Prerelease = ''

        # Flag to indicate whether the module requires explicit user acceptance for install/update
        # RequireLicenseAcceptance = $false

        # External dependent modules of this module
        # ExternalModuleDependencies = @()

    } # End of PSData hashtable

 } # End of PrivateData hashtable

# HelpInfo URI of this module
# HelpInfoURI = ''

# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''

}

Below is a table with some information about important fields of the module manifest file:

Field Detail
ModuleVersion This should not be touched unless otherwise specified to do so. Preview modules are noted by this version being 0.x.x, or with the preview prefix specified in the Prerelease field at the bottom of the file. All other versions should signal that the module is stable.
Description This should be updated to include information about the service, as well as a link to any corresponding service docs found on https://learn.microsoft.com.
RequiredModules This should only contain a module dependency on the Az.Accounts module, unless otherwise noted. The version should be the latest version of Az.Accounts (found in the Az.Accounts.psd1 file).
RequiredAssemblies This should only contain assemblies that the module needs to run all of the cmdlets successfully. At a minimum, the service's SDK should be included in this list. Any other additional modules should be verified by the Azure PowerShell team. No external service team SDK should be included in this field.
FormatsToProcess This should contain any formatting files that are used by the module to alter the display of cmdlets' output.
NestedModules This should contain any assembly built with your project that contains cmdlet code. There is usually only one assembly found in this field unless the module contains multiple services.
CmdletsToExport All cmdlets found in the module should be listed in this field.
AliasesToExport All aliases found in the module should be listed in this field.
Tags This should only include service-specific words or phrases to help users find the module in the PowerShell Gallery. There should be no spaces in any of the tags added to this field; any tags with spaces will cause publishing to PowerShell Gallery to fail.
ReleaseNotes This should not be touched unless otherwise specified to do so. This field will be updated as a part of the release process for the module.
Prerelease This should be set to preview if generating a preview version of a stable module. This will append a -preview string to the end of the module version.

Module Dependencies

Common Assemblies

Every module's .csproj file must import the Common.Netcore.Dependencies.targets file to ensure that the correct version of each common assembly is referenced by the module. These assemblies are packaged with the Az.Accounts module and are loaded into a PowerShell session when Az.Accounts is imported (which is also done automatically when importing the service module).

Some of the assemblies included in this .targets file:

  • Microsoft.Azure.PowerShell.Clients.*
  • Microsoft.Rest.ClientRuntime
  • Microsoft.Rest.ClientRuntime.Azure
  • Newtonsoft.Json

SDK Assemblies

A module should have a dependency on only its SDK and no other service's SDK; if a module takes a dependency on another service's SDK, this can introduce conflicting assembly versions between the version of the SDK referenced by the service team's module and the external service team's module, which will result in assembly loading issues for the user in PowerShell.

If an external service's SDK is required by a module, the Azure PowerShell team must be consulted to resolve this issue. In most cases, the issue is resolved by grabbing a snapshot of the service's SDK and putting it in the azure-powershell-common repository, which can then be referenced by any module. This allows the service team to continue shipping with their own SDK without worrying about external service teams from taking a dependency on the same SDK and introducing these potential assembly loading issues.

Other Assemblies

All other assemblies referenced by a module should be verified by the Azure PowerShell team to ensure that they aren't introducing additional dependencies that will clash with packages already being shipped.