Repository files navigation

This repository serves two purposes and they are independent:

1. A source code directory,src, to host your extension source code.
2. An index.json where you can add your extension and make it available through Azure CLI.

For documentation on authoring an extension, seeExtension Documentation

• The index is atsrc/index.json.
• Modify the index by creating a PR.
• All extensions added to the indexare public and will be available toall CLI users.
• The index is synced tohttps://aka.ms/azure-cli-extension-index-v1 every few minutes.
• Your extension source code does not have to be in this repository to be available in the index.
• If you don't want your extension to be part of the index, you can still host it externally and request users to install withaz extension add --source https://contoso.com/mywheel.whl.
  • Users will not be able to add your extension by name, it will not be listed in theaz extension list-available command and to update to a new version of your extension, the user has to first remove the currently installed extension and then add the new version.

Add your extension to the index to make it available in these CLI commands:

• az extension add --name NAME - Allows users to add an extension by name
• az extension list-available - Allows users to list the available extensions in the index
• az extension update --name NAME - Allows users to update an extension

• Extension source code goes into thesrc directory.
• You can place your source code in this repository by creating a PR.
• Once CI is green and it has been approved, the PR can be merged.
• SDKs generated fromAutoRest often do not pass CI static-checking. If they are vendored inside the extension, exclude them from static checking by placing them in the folder:src/<extension root>/azext_*/vendored_sdks.
• Ensure that you include an appropriate owner for your extension in.github/CODEOWNERS.
• Your extension artifact (i.e..whl) will not live in this repository. You can publish your extension to PyPI or somewhere else such as Azure Storage.
• If you want your extension to appear in the index.json, modify the index.

There is a pipeline to automatically build, upload and publish extension wheels.

Once your PR is merged into master branch, a new PR will be created to updatesrc/index.json automatically.

The precondition is to put your code inside this repo and upgrade the version in the PR but not to modifysrc/index.json.

If you want to host the source code in your dedicated repo, you have to upload the WHL file and update thesrc/index.json manually.

For detail, please visitPublish section in Azure CLI Extension Authoring.

If you useazdev extension update-index the command will calculate the SHA256 digest for you. For more information visithttps://github.com/Azure/azure-cli-dev-tools.

As a fallback:

MacOS

shasum -a 256 path_to_whl.whl

Windows / PowerShell

Get-FileHash path_to_whl.whl -Algorithm SHA256

Note: Hash should be in lowercase in index.json otherwise CI will fail.

Theazdev extension update-index command can be used to simplify the process of updating the index file. Runazdev extension update-index <URL> where URL is the fully-qualified URL to your published extension WHL. This will gather the appropriate metadata and add an entry for your extension to the index. For more information visithttps://github.com/Azure/azure-cli-dev-tools.

As a fallback:

The metadata needed to be filled is a combination of the contents present in:

• metadata.json located in your unzipped extension artifact (.whl file) in the<package>-<version>.dist-info directory. This metadata is garnered from thesetup.py folder.
• azext_metadata.json (if it exists) under your extension.

Note that CI will fail if this metadata does not match the contents of your published extension.

This project welcomes contributions and suggestions. Most contributions require you to agree to aContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant usthe rights to use your contribution. For details, visithttps://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to providea CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructionsprovided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQ orcontactopencode@microsoft.com with any additional questions or comments.