Skip to content

[DO NOT MERGE] TEST AZP RUN TRIGGER #28436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[DO NOT MERGE] TEST AZP RUN TRIGGER #28436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
17c7f9c
Fix formatting and clarity issues in troubleshooting CI documentation
ReaNAiveD Aug 21, 2025
d993553
Improve clarity and formatting in 'Announcing New Module Az' document…
ReaNAiveD Aug 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 37 additions & 40 deletions documentation/announcing-az-module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,60 +1,58 @@
# Announcing New Module 'Az'
In August 2018 we released a new module, 'Az' which combines the functionality of the AzureRM and AzureRM.Netcore modules. Az goes to version 1.0 on 12/18/2018. Az runs on both Windows PowerShell 5.1 and PowerShell 7. 'Az' ensures that the Windows PowerShell and PowerShell 7 cmdlets for managing Azure resources will always be in sync and up to date. In addition, Az will simplify and regularize the naming of Azure cmdlets, and the organization of Azure modules. Az is intended as a replacement for the AzureRM.Netcore and AzureRM modules.
In August 2018, we released a new module called 'Az' that combines the functionality of the AzureRM and AzureRM.Netcore modules. Az reached version 1.0 on December 18, 2018, and runs on both Windows PowerShell 5.1 and PowerShell 7. The 'Az' module ensures that Windows PowerShell and PowerShell 7 cmdlets for managing Azure resources are always in sync and up to date. Additionally, Az simplifies and regularizes the naming of Azure cmdlets and the organization of Azure modules. Az is intended as a replacement for the AzureRM.Netcore and AzureRM modules.

Az currently ships in Cloud Shell, and can be found on the PowerShell Gallery [here](https://www.powershellgallery.com/packages/Az/)
Az currently ships in Cloud Shell and can be found on the [PowerShell Gallery](https://www.powershellgallery.com/packages/Az/).

Az is a new module, and reorganizing and simplifying cmdlet names involves breaking changes, so we have [added features to Az to make it easier to transition to the simplified, normalized names in your existing scripts](#migrating-from-azurerm).
Since Az is a new module and reorganizing and simplifying cmdlet names involves breaking changes, we have [added features to Az to make it easier to transition to the simplified, normalized names in your existing scripts](#migrating-from-azurerm).

## New Features
- Windows PowerShell 5.1 and PowerShell 7 support in the same module
- PowerShell 7 and Windows PowerShell cmdlets are always in sync and up to date with latest Azure capabilities
- Shortened and normalized cmdlet names - all cmdlets use the noun prefix 'Az'
- Simplified and normalized module organization - data plane and management plane cmdlets in the same module for each service
- Enhanced authentication for Netcore
* Self-renewing Service Principal Authentication
* Service Principal Certificate Authentication (in the future)
- Enable/Disable-AzureRmAlias cmdlets to manage compatibility with scripts based on AzureRM
- Windows PowerShell 5.1 and PowerShell 7 support in the same module
- PowerShell 7 and Windows PowerShell cmdlets are always in sync and up to date with the latest Azure capabilities
- Shortened and normalized cmdlet names - all cmdlets use the noun prefix 'Az'
- Simplified and normalized module organization - data plane and management plane cmdlets in the same module for each service
- Enhanced authentication for .NET Core
- Self-renewing Service Principal Authentication
- Service Principal Certificate Authentication (planned for future release)
- `Enable-AzureRmAlias` and `Disable-AzureRmAlias` cmdlets to manage compatibility with scripts based on AzureRM

## Supported Platforms
- PowerShell 5.1 with .Net Framework 4.7.2 or later [Windows only]
- PowerShell 7 - Windows, Linux, macOS
- PowerShell 5.1 with .NET Framework 4.7.2 or later [Windows only]
- PowerShell 7 - Windows, Linux, macOS

## Timeline

| Date | Feature |
-------|----------
|------|---------|
| **August 2018** | Initial Release |
| **November 2018** | Functional parity with AzureRM |
| **December 2018** | Az 1.0 Release |
| **January 2019** | New Authentication mechanisms for Windows PowerShell
| | - Username + password authentication
| **January 2019** | New Authentication mechanisms for Windows PowerShell |
| | - Username + password authentication |
| | - Web browser control authentication |



## AzureRM Module Support
AzureRM will continue to be supported, and important bugs will be fixed, but new development and new Azure capabilities will be shipped only in Az starting December 2018.

## Authentication Changes
- ADAL has limited support for the "not recommended" user credential non-interactive auth flow.
- Connect-AzAccount in Az 1.0 will not accept PSCredential, but will support this for Windows PowerShell only in Az 1.1.0 (January 15, 2019)
- Here are a couple issues that describe why ADAL has limited this support
- [Azure ActiveDirectory UserPasswordCredential doesn't support .NET core](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/issues/482#issuecomment-262256236)
- [Connect-AzureRmAccount with user credential login does not work in Az](https://github.com/Azure/azure-powershell/issues/7430#issuecomment-426480499)
- ADAL has limited support for the "not recommended" user credential non-interactive authentication flow.
- `Connect-AzAccount` in Az 1.0 will not accept `PSCredential`, but will support this for Windows PowerShell only in Az 1.1.0 (January 15, 2019)
- Here are a couple of issues that describe why ADAL has limited this support:
- [Azure ActiveDirectory UserPasswordCredential doesn't support .NET core](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/issues/482#issuecomment-262256236)
- [Connect-AzureRmAccount with user credential login does not work in Az](https://github.com/Azure/azure-powershell/issues/7430#issuecomment-426480499)

- Service Principal improvements
- Self-renewing Service Principal Authentication
- Service Principal Certificate Authentication (in the future)
- Device Auth Flow
- Future Improvements
- [Interactive user credential login in az](https://github.com/Azure/azure-powershell/issues/7358)
- Service Principal improvements:
- Self-renewing Service Principal Authentication
- Service Principal Certificate Authentication (planned for future release)
- Device Authentication Flow
- Future Improvements:
- [Interactive user credential login in Az](https://github.com/Azure/azure-powershell/issues/7358)


## Migrating From AzureRM

To make it easier for existing scripts to migrate from AzureRM to Az, we have provided cmdlets to create aliases that map the cmdlet names in AzureRM into the appropriate cmdlets in Az. When the aliases are enabled, any script that uses AzureRM cmdlet names should run against Az without modification.
To make it easier for existing scripts to migrate from AzureRM to Az, we have provided cmdlets to create aliases that map the cmdlet names in AzureRM to the appropriate cmdlets in Az. When the aliases are enabled, any script that uses AzureRM cmdlet names should run against Az without modification.

Note: Connect-AzAccount aka Connect-AzureRmAccount no does not ```PSCredential``` in version 1.0, but will in version 1.1. See [Authentication Changes](#authentication-changes) for more details
**Note:** Connect-AzAccount aka Connect-AzureRmAccount no does not ```PSCredential``` in version 1.0, but will in version 1.1. See [Authentication Changes](#authentication-changes) for more details

```powershell
PS C:\> Enable-AzureRmAlias
Expand All @@ -63,7 +61,7 @@ PS C:\> Enable-AzureRmAlias
will enable AzureRM aliases in the Az module for the current PowerShell session. For your convenience, we have added a ```Scope``` parameter that will automatically set up the AzureRM aliases in Az for every PowerShell session:

```powershell
PC C:\> Enable-AzureRmAlias -Scope CurrentUser
PS C:\> Enable-AzureRmAlias -Scope CurrentUser
```

Sets up AzureRM cmdlet name aliases in the Az module for all sessions started by the current user, while
Expand Down Expand Up @@ -148,7 +146,7 @@ For scripts that import modules directly, or use ```#Requires``` statements to s
| AzureRM.RedisCache | Az.RedisCache |
| AzureRM.Relay | Az.Relay |
| AzureRM.Reservations | Az.Reservations |
| AzureRM.Resources | Az. Resources |
| AzureRM.Resources | Az.Resources |
| ~~AzureRM.Scheduler~~ | **REMOVED** |
| AzureRM.Search | Az.Search |
| AzureRM.Security | Az.Security |
Expand All @@ -168,27 +166,26 @@ For scripts that import modules directly, or use ```#Requires``` statements to s

### Installing Az and AzureRM Side-by-Side

Az and AzureRM cannot be imported side-by-side into the same PowerShell session. If you do not want to migrate your scripts from AzureRM to Az right away, there are two main options:
Az and AzureRM cannot be imported side-by-side into the same PowerShell session. If you do not want to migrate your scripts from AzureRM to Az right away, there are two main options:
- Install Az in PowerShell 7, and leave AzureRM in Windows PowerShell
- Install Az and AzureRM side-by-side in Windows PowerShell and ensure scripts do not mix the modules

#### Install Az in PowerShell 7
You can follow the instructions in [Installing PowerShell 7 on Windows](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-core-on-windows
) to install PowerShell 7, then use ```Install-Module Az``` in PowerShell 7 to acquire the Az module. Since Windows PowerShell and PowerShell 7 can exist side-by-side and do not share module directories, this will effectively isolate the two modules.
You can follow the instructions in [Installing PowerShell 7 on Windows](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-core-on-windows) to install PowerShell 7, then use `Install-Module Az` in PowerShell 7 to acquire the Az module. Since Windows PowerShell and PowerShell 7 can exist side-by-side and do not share module directories, this will effectively isolate the two modules.

#### Install Az and AzureRM Side-by-Side
If you need to have both modules installed:
- Do not use the Enable-AzureRmAlias cmdlet with -Scope CurrentUser or LocalMachine
- When installing Az on a machine with AzureRM previously installed, you must specify ```AllowClobber``` in the Install-Module cmdlet invocation.
- When installing Az on a machine with AzureRM previously installed, you must specify `AllowClobber` in the Install-Module cmdlet invocation.

```powershell
PS C:\> Install-Module -Name Az -AllowClobber
```

##### Interactive Usage
You cannot load Az and AzureRM modules in the same PowerShell session, but they can be used in separate sessions as follows
- In AzureRM session: ```Import-Module AzureRM```
- In Az session: Begin the session with ```Enable-AzureRmAlias```, which will prevent inadvertently loading AzureRM modules. Alternately, you can use cmdlets with Az noun prefix, and avoid using cmdlets with Azure or AzureRm noun
You cannot load Az and AzureRM modules in the same PowerShell session, but they can be used in separate sessions as follows:
- In AzureRM session: `Import-Module AzureRM`
- In Az session: Begin the session with `Enable-AzureRmAlias`, which will prevent inadvertently loading AzureRM modules. Alternately, you can use cmdlets with Az noun prefix, and avoid using cmdlets with Azure or AzureRm noun

##### Usage in Scripts

Expand Down
78 changes: 39 additions & 39 deletions documentation/troubleshoot-ci.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,101 +1,101 @@
# Troubleshooting CI build failures
# Troubleshooting CI Build Failures

In case "default" CI job for your PR failed, click "Details" and analyze, messages there are usually helpful.
When the "default" CI job for your pull request fails, click "Details" to analyze the failure. The error messages there are usually helpful.

Find and open **msbuild.err** from build artifacts to see summarized error message. List of possible failures is below.
Find and open **msbuild.err** from the build artifacts to see a summarized error message. A list of possible failures is provided below.

To get even more detailed data click "Console Output" and look for keywords like "Fail", etc.
To get more detailed information, click "Console Output" and search for keywords like "Fail", "Error", etc.

## Help generation failure
## Help Generation Failure

### Message
### Error Message

> c:\workspace\powershell\build.proj(278,5): error MSB3073: The command ""C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" -NonInteractive -NoLogo -NoProfile -Command "$ProgressPreference = 'SilentlyContinue';. c:\workspace\powershell\tools\\**GenerateHelp.ps1** -ValidateMarkdownHelp -GenerateMamlHelp -BuildConfig Debug -FilteredModules 'Az.Network;Az.Profile' "" exited with code -1.

This means there are issues with your help files.
This error indicates there are issues with your help files.

### Reasons:
### Common Causes

- Cmdlet was changed while .md help files were not regenerated [this way](development-docs/help-generation.md) or there is no help files at all.
- Help files were re-generated, however they weren't filled with real data. I.e. help generator leaves templates like this `"{{Description there}}"` and they need to be manually filled by developer with descriptions, examples, etc.
- Cmdlets were modified but the corresponding .md help files were not regenerated [following this process](development-docs/help-generation.md), or there are no help files at all.
- Help files were regenerated but not properly filled with actual content. The help generator leaves template placeholders like `"{{Description here}}"` that need to be manually updated by the developer with descriptions, examples, etc.

### Solution

Regenerate MD help files [this way](development-docs/help-generation.md) and update "{{\*}}" placeholders
Regenerate MD help files [following this process](development-docs/help-generation.md) and update all "{{\*}}" placeholders with appropriate content.

## Help generation failure (online version url)
## Help Generation Failure (Online Version URL)

### Message
### Error Message

> Online version in the header of the file is incorrect.

### Reasons
### Common Causes

This means the online version url in the header of the help document is either incorrect or missing.
This error occurs when the online version URL in the header of the help document is either incorrect or missing.

### Solution

The url should exactly match the schema `https://learn.microsoft.com/en-us/powershell/module/az.{modulename}/{cmdlet-name}`, all in lower case.
The URL should follow the exact schema: `https://learn.microsoft.com/en-us/powershell/module/az.{modulename}/{cmdlet-name}`, with all text in lowercase.

### Example
> https://learn.microsoft.com/en-us/powershell/module/az.keyvault/new-azkeyvault

## Code analysis failures
## Code Analysis Failures

### Message
### Error Message

> c:\workspace\powershell\build.proj(597,5): error MSB3073: The command "c:\workspace\powershell\artifacts\\**StaticAnalysis.exe** -p c:\workspace\powershell\artifacts\Debug -r c:\workspace\powershell\artifacts -m Az.Network" exited with code 255.c:\workspace\powershell\build.proj(609,5): error : StaticAnalysis has failed. Please follow the instructions on this doc: [https://github.com/Azure/azure-powershell/blob/main/documentation/Debugging-StaticAnalysis-Errors.md](Debugging-StaticAnalysis-Errors.md)

### Reasons
### Common Causes

Something that is considered as unacceptable was added with your PR e.g. breaking change, incorrect signature, etc.
This error occurs when your pull request introduces something considered unacceptable, such as breaking changes, incorrect signatures, etc.

### Solution

According to the [link above](Debugging-StaticAnalysis-Errors.md) you would need to investigate .csv files in the build artifacts.
Follow the [instructions in the link above](Debugging-StaticAnalysis-Errors.md) to investigate the .csv files in the build artifacts.

There are several ways to act:
You have several options to address these issues:

1. In case your changes in the listed files are unintentional, just roll them back.
1. **Unintentional changes**: If your changes in the listed files were unintentional, simply roll them back.

2. In case changes could be improved without affecting functionality (e.g. signature is incorrect, but you could adjust it to suit requirements), try to fix.
2. **Improvable changes**: If the changes can be improved without affecting functionality (e.g., incorrect signature that can be adjusted to meet requirements), fix the issues.

3. In case messages in csv files describe expected changes, add them to [exclusions](Debugging-StaticAnalysis-Errors.md#breaking-changes).
3. **Expected changes**: If the messages in the csv files describe expected changes, add them to the [exclusions](Debugging-StaticAnalysis-Errors.md#breaking-changes).

### Example:
### Example

One of the often reasons are BreakingChangesIssues.
One common reason for failures is BreakingChangesIssues.

If collected Breaking Changes issues are expected (e.g. cmdlet was really changed), you would need to update Exclusions file [like this](Debugging-StaticAnalysis-Errors.md#breaking-changes) to bypass CI build.
If the collected Breaking Changes issues are expected (e.g., a cmdlet was intentionally changed), you'll need to update the exclusions file [as described here](Debugging-StaticAnalysis-Errors.md#breaking-changes) to bypass the CI build.

## Test failures
## Test Failures

### Message
### Error Message

> **Test failures occurred, check the files in artifacts/Test**

### Reasons
### Common Causes

One or more tests failed
One or more tests have failed during the build process.

### Solution

See test reports in artifacts/Test and fix failures related to your changes.
Review the test reports in the artifacts/Test directory and fix any failures related to your changes.

In case you see more failures, please contact test owning team. Common way is to find a person who edited the cmdlet or test last. Networking tests are also marked with header like this to simplify team search: `[Trait(Category.Owner, Category.TeamAlias)]`
If you encounter additional failures not related to your changes, please contact the team that owns those tests. A common approach is to identify the person who last edited the cmdlet or test. Networking tests are also marked with headers like `[Trait(Category.Owner, Category.TeamAlias)]` to help identify the responsible team.

## Test failures (.psd1 of other modules not found)
## Test Failures (Missing .psd1 Files from Other Modules)

### Message
### Error Message

> Exception:System.IO.FileNotFoundException: The specified module 'D:\a\1\s\artifacts\Debug\Az.Network\Az.Network.psd1' was not loaded because no valid module file was found in any module directory.

### Reasons
### Common Causes

This is because your test cases are using cmdlets from other module, but it was not built by CI.
This error occurs when your test cases use cmdlets from other modules, but those modules were not built by the CI process.

### Solution

Add the missing module's csproj to your module's .sln file. For example this is how `Compute.sln` references `Network.csproj`:
Add the missing module's .csproj file to your module's .sln file. For example, here's how `Compute.sln` references `Network.csproj`:
https://github.com/Azure/azure-powershell/blob/58ded2ba3e0a5f7da0d1ffed9e0adb986986ab6f/src/Compute/Compute.sln#L11

Loading