Skip to content

Latest commit

 

History

History
58 lines (52 loc) · 5.71 KB

how-to.md

File metadata and controls

58 lines (52 loc) · 5.71 KB

How-To

This document describes how to develop for Az.ManagedServiceIdentity.

Building Az.ManagedServiceIdentity

To build, run the build-module.ps1 at the root of the module directory. This will generate the proxy script cmdlets that are the cmdlets being exported by this module. After the build completes, the proxy script cmdlets will be output to the exports folder. To read more about the proxy script cmdlets, look at the README.md in the exports folder.

Creating custom cmdlets

To add cmdlets that were not generated by the REST specification, use the custom folder. This folder allows you to add handwritten .ps1 and .cs files. Currently, we support using .ps1 scripts as new cmdlets or as additional low-level variants (via ParameterSet), and .cs files as low-level (variants) cmdlets that the exported script cmdlets call. We do not support exporting any .cs (dll) cmdlets directly. To read more about custom cmdlets, look at the README.md in the custom folder.

Generating documentation

To generate documentation, the process is now integrated into the build-module.ps1 script. If you don't want to run this process as part of build-module.ps1, you can provide the -NoDocs switch. If you want to run documentation generation after the build process, you may still run the generate-help.ps1 script. Overall, the process will look at the documentation comments in the generated and custom cmdlets and types, and create .md files into the docs folder. Additionally, this pulls in any examples from the examples folder and adds them to the generated help markdown documents. To read more about examples, look at the README.md in the examples folder. To read more about documentation, look at the README.md in the docs folder.

Testing Az.ManagedServiceIdentity

To test the cmdlets, we use Pester. Tests scripts (.ps1) should be added to the test folder. To execute the Pester tests, run the test-module.ps1 script. This will run all tests in playback mode within the test folder. To read more about testing cmdlets, look at the README.md in the examples folder.

Packing Az.ManagedServiceIdentity

To pack Az.ManagedServiceIdentity for distribution, run the pack-module.ps1 script. This will take the contents of multiple directories and certain root-folder files to create a .nupkg. The structure of the .nupkg is created so it can be loaded part of a PSRepository. Additionally, this package is in a format for distribution to the PSGallery. For signing an Azure module, please contact the Azure PowerShell team.

Module Script Details

There are multiple scripts created for performing different actions for developing Az.ManagedServiceIdentity.

  • build-module.ps1
    • Builds the module DLL (./bin/Az.ManagedServiceIdentity.private.dll), creates the exported cmdlets and documentation, generates custom cmdlet test stubs and exported cmdlet example stubs, and updates ./Az.ManagedServiceIdentity.psd1 with Azure profile information.
    • Parameters: [Switch parameters]
      • -Run: After building, creates an isolated PowerShell session and loads Az.ManagedServiceIdentity.
      • -Test: After building, runs the Pester tests defined in the test folder.
      • -Docs: After building, generates the Markdown documents for the modules into the docs folder.
      • -Pack: After building, packages the module into a .nupkg.
      • -Code: After building, opens a VSCode window with the module's directory and runs (see -Run) the module.
      • -Release: Builds the module in Release configuration (as opposed to Debug configuration).
      • -NoDocs: Supresses writing the documentation markdown files as part of the cmdlet exporting process.
      • -Debugger: Used when attaching the debugger in Visual Studio to the PowerShell session, and running the build process without recompiling the DLL. This suppresses running the script as an isolated process.
  • run-module.ps1
    • Creates an isolated PowerShell session and loads Az.ManagedServiceIdentity into the session.
    • Same as -Run in build-module.ps1.
    • Parameters: [Switch parameters]
      • -Code: Opens a VSCode window with the module's directory.
        • Same as -Code in build-module.ps1.
  • generate-help.ps1
    • Generates the Markdown documents for the modules into the docs folder.
    • Same as -Docs in build-module.ps1.
  • test-module.ps1
    • Runs the Pester tests defined in the test folder.
    • Same as -Test in build-module.ps1.
  • pack-module.ps1
    • Packages the module into a .nupkg for distribution.
    • Same as -Pack in build-module.ps1.
  • generate-help.ps1
    • Generates the Markdown documents for the modules into the docs folder.
    • Same as -Docs in build-module.ps1.
    • This process is now integrated into build-module.ps1 automatically. To disable, use -NoDocs when running build-module.ps1.
  • export-surface.ps1
    • Generates Markdown documents for both the cmdlet surface and the model (class) surface of the module.
    • These files are placed into the resources folder.
    • Used for investigating the surface of your module. These are not documentation for distribution.
  • check-dependencies.ps1
    • Used in run-module.ps1 and test-module.ps1 to verify dependent modules are available to run those tasks.
    • It will download local (within the module's directory structure) versions of those modules as needed.
    • This script does not need to be ran by-hand.