The Microsoft Entra PowerShell Developer Guide helps you develop and test Entra PowerShell cmdlets. It provides information on setting up your environment, implementing cmdlets, creating and running tests, and writing cmdlet documentation.
- Table of Contents
- Development Workflow
- Prerequisites
- Environment Setup
- Creating Cmdlets
- After Development
Welcome! We're glad you're here. We're about to give you an overview of what we need to do to add cmdlets to the Entra PowerShell module. This guide aims to ensure consistency and provide a better experience for customers. Here is an overview of the process.
flowchart LR
A((Start)) --> B["Get Started #9992;
(key concepts, naming, setup)"]
B["Get Started #9992;
(key concepts, naming, setup)"] --> C["Develop, test,
document ❴❵"]
C["Develop, test,
document ❴❵"] --> D[Review ✔]
D[Review ✔] --> E[Publish 🚀]
E[Publish 🚀] --> F(((End)))
D--changes-->C
| Stage | Description |
|---|---|
| Get Started | Familiarize yourself with cmdlet, modules, parameter, piping best practices, key concepts, naming conventions, testing, review processes, and other best practice guidelines. |
| Implementation | Set up the environment, develop cmdlet logic, create unit tests, and document cmdlets with examples. |
| Review | Submit changes by raising a pull request for review by the community and the Microsoft Entra PowerShell Engineering team. |
| Publish | We deploy approved changes in the next release train. |
The following prerequisites should be completed before contributing to the Entra PowerShell repository:
- Install Visual Studio code
- Install the latest version of Git
- Install the
platyPSmodule - Install PSScriptAnalyzer
- Install PowerShell 7
- Set the PowerShell execution policy to Unrestricted for the following versions of PowerShell:
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exeC:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exeC:\Program Files\PowerShell\{{version}}\pwsh.exe
If you don't have experience with Git and GitHub, some of the terminology and process can be confusing. Here is a guide to understanding the GitHub flow and here is a guide to understanding the basic Git commands.
To develop in the Entra PowerShell repository locally, you first need to create your own fork. For more information on how to fork, click here.
Once your fork of the Entra PowerShell repository has been created, you need to clone your fork to your local machine. To do so, run the following command:
git clone https://github.com/<YOUR GITHUB USERNAME>/entra-powershell.git
You now be able to create your own branches, commit changes, and push commits to your fork.
Note: we recommend adding the microsoftgraph/entra-powershell repository to your list of tracked repositories in Git. This allows you to easily pull changes from the microsoftgraph/entra-powershell repository. To do this, run the following command:
git remote add upstream https://github.com/microsoftgraph/entra-powershell.git
Then, to pull changes from the main branch in microsoftgraph/entra-powershell into your local working branch, run the following command:
git pull upstream main
The
mainbranch is for the next feature release and is actively developed with new features, documentation changes, performance improvements, and bug fixes.
Please check out the Cmdlet Best Practices document for more information on how to create cmdlets that follow the PowerShell guidelines.
For a significant number of changes or additions, a design review of your proposed PowerShell cmdlets may be necessary. We recommend submitting this review through a pull request with ample time for consideration. Before submitting a design review pull request, please ensure you have read the documents in the Entra PowerShell Design Guidelines folder.
Another scenario that might require a design review is resolving design conflicts to ensure consistency and predictability. For example, when adding business roles, it's important to clearly distinguish between Privileged Identity Management roles and catalog roles to minimize conflicts.
In the event of a persistent design conflict, the Entra PowerShell Governance Board will arbitrate and review the established guidelines. The board holds veto power, but all decisions are documented, including the options considered and the trade-offs involved
Your new cmdlet can reside in either of these folders.
| Folder name | Description |
|---|---|
| Customizations | For cmdlets ported from AzureAD module. See, Beta and v1.0 customization folders |
| Additional Functions | For new cmdlets. See, Beta and v1.0 additional functions folders |
Note: If unsure, choose Additional Functions folder.
The file name should be the same as the cmdlet name.
All cmdlets that are created must have accompanying help that is displayed when users execute the command Get-Help <your cmdlet>.
Each cmdlet has a markdown file that contains the help content that is displayed in PowerShell; these markdown files are created (and maintained) using the platyPS module.
For complete documentation, see cmdlet-reference-template in the cmdlet references documentation folder. See Beta and v1.0 cmdlet examples.
Place cmdlet reference .md files under:
Entra PowerShell uses a single source of truth for both Get-Help and public online documentation, stored in the docs folder.
All cmdlets MUST have unit tests. Developers are expected to write and run unit tests for their PowerShell code, ensuring that it behaves as expected and helping to prevent regressions. Entra PowerShell module use Pester framework. Place cmdlet reference .md files under:
- Beta cmdlet tests folder
- v1.0 cmdlet tests folder
Note:
- Ensure your pull request has tests to verify it works as expected. Pull requests without proper tests will not be accepted.
- Ensure all tests pass. The full test suite must run.
Once all of your cmdlets have been created and the appropriate tests have been added, you can open a pull request in the Entra PowerShell repository to have your cmdlets added to the next release. Please make sure to read CONTRIBUTING.md for more information on how to open a pull request, clean up commits, make sure appropriate files have been added/changed, and more.
Tag your pull request with Ready For Review label.
The Entra PowerShell team will regularly publish the module, including all changes, to the official PowerShell gallery as outlined in our official documentation.
Significant contributions are credited in the misc/acknowledgements file. You might be asked to make these updates on behalf of the Entra PowerShell Engineer who accepts your pull request.