The document is for those, who are familiar with SDK-based modules and want to give a try with auto-gen modules. The content will contain the comparation between these two kinds of modules from architecture, cmdlets differences, and onboard process, etc.
Highlight parameters differences in auto-gen modules as below.
- No Set-* cmdlets, Set-* is replaced by New-* and Update-*
- Add [-SubscriptionId <String[]>] parameter for get-* cmdlets and add for [-SubscriptionId ] parameter for the others
- Do not support breaking change warning yet
- Pipeline
- Do not support to pipe in parent resource
- Unify two types (through -InputObject and -ResourceId) of pipeline into one -InputObject, Users could either pipe in the resourceId or resource object
- Design review
- Get a released management SDK for Dotnet
- Implement cmdlets in C# based on management SDK for Dotnet
- Implement testcases
- Generate docs, and populate them with examples
- Create a PR in main branch for code review
- Design review
- Write a readme.md as the autorest.powershell configuration for the module, and normally, it should contains
- links to swaggers in azure-rest-api-specs (should pin to specific version through commit id to avoid potential breaking changes)
- A reference to readme.azure.noprofile.md to inline common configurations
- Module specific configurations, e.g. module-version, title, subject-prefix...
- directive
- customization
- Implement testcases
- Generate docs and populate them with examples
- Create a PR in generation branch for code review
- Azure team members will help merge code from generation branch to main branch
Since the cmdlets are handcrafted by developers, no special customization mechanism is required.
Customization could be done through three ways.
- Through directive in readme.md, please see directives.md for details
- Through PowerShell script, please see customization.md for details
- Through C# code
If your module relies on some other modules, you will need to rely on dotnet SDK of these modules, which could put in your module if only your module depends on them or in Az.Accouts they are some common modules required by several modules.
Generally speaking, hero scenarios are implemented through customization through PowerShell script above. Regarding to third party dependencies, there are two ways to handle it.
- Add the swaggers of the dependencies to readme.md either directly or by adding related helpers defined src/helpers if they are common shared modules
- Rely on related Azure PowerShell modules, in this case, it is better you could add the logic to check whether the modules you rely on have installed or not
Docs are generated through playPS, please see platyPS for details. And developers should populate generated docs with examples.
Autorest.powershell will generate example stubs in the examples folder, which should be populated by the developers manually. When building, examples in the examples folder will be automatically merged into docs.
Tests are written in C# code.
Tests are written in PowerShell script. And we will leverage PowerShell test framework Pester.
We are still working on bringing data plane to auto-gen.