Läs på engelska

Dela via

Guide för Azure PowerShell-dokumentformat

  • Artikel

Den här artikeln fokuserar på konceptuellt Azure PowerShell-innehåll och referensinnehåll som är tillgängligt på följande GitHub-lagringsplatser:

Version

Till skillnad från de flesta Microsoft Learn-dokumentationen underhålls Azure PowerShell-innehållet i azure-docs-powershell lagringsplats för flera versioner som stöds. Mer information om versioner som stöds finns i Azure PowerShell-supportlivscykel.

Om en artikel refererar till cmdletar från en förhandsversionsmodul måste modulen installeras uttryckligen såvida inte modulen AzPreview redan är installerad. Det beror på att endast allmänt tillgängliga moduler (GA) ingår i modulen Az PowerShell.

Viktigt

Använd inte kommandon från modulen AzureRM PowerShell i artiklar. AzureRM är föråldrad.

Förutsättningar

Placera alltid förhandskraven för Azure-tjänsten först, följt av Azure PowerShell- och Azure Cloud Shell-instruktioner. För exempel, "Du måste ha Microsoft.Authorization/roleAssignments/write behörighet för att slutföra instruktionerna i den här handledningen" bör vara det första steget.

Om alla kommandon inte är kompatibla med Cloud Shell instruerar du användaren att installera Az PowerShell-modulen lokalt. Inkludera följande text i ett H2-kravavsnitt.

markdown 
- This tutorial requires that you run Azure PowerShell locally:
  - [Install the latest version of the Az PowerShell module](/powershell/azure/install-azure-powershell).
  - Connect to your Azure account using the
    [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) cmdlet.

Formatera syntaxelement i ett stycke

Följ stilguiden för PowerShell-Docs och Editors checklista för formatering av kommandosyntaxelement i Azure PowerShell-dokumentationen.

Länka inte till cmdlet-dokumentationen när du nämner cmdlet-namn i ett stycke. Omge i stället cmdlet-namnet med backticks, som är ett format för inbäddad kod (``). Lägg till ett referensavsnitt längst ned på sidan. Lista cmdlet-namnen i referensavsnittet och länka till deras associerade referensartikel. Till exempel:

markdown 
This is an example of using the `Connect-AzAccount` and `Get-AzVM` cmdlets within a
paragraph.

## References

- [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount)
- [Get-AzVM](/powershell/module/az.compute/get-azvm)

Anteckning

Formatera inte text inom hakparenteserna för en hyperlänk. Mer information om hur du länkar till Azure PowerShell-innehåll finns i Länka till andra dokument.

Parameterordning

Parametrar för en Azure PowerShell-cmdlet bör visas i den ordning som definieras av cmdlet-hjälpen. En cmdlet kan ha flera sätt att tillhandahålla nödvändiga parametrar. När detta sker, följ parameteruppsättningen för den användning som du demonstrerar. Connect-AzAccount är ett exempel på en cmdlet med flera sätt att anropa den.

Variabler

Undvik att återanvända variabler över flera kodblock.

Läsaren kan slutföra artikelstegen i olika sessioner. Om du använder variabler mellan kodblock kan det orsaka fel om de inte har angetts korrekt. Om du måste använda variablerna mellan stegen gör du klart att variabler återanvänds i senare steg.

Randomisera lösenord för nya resurser

Om du skapar en resurs som har ett lösenord associerat med den inte använda ett hårdkodat lösenord. Att kontrollera lösenord i versionskontrollsystem, även exempel, är en säkerhetsrisk.

Om Azure-resurserna i artikeln kräver ett lösenord för oformaterad text använder du Read-Host för att tillåta användare att definiera sitt lösenord. Parametern MaskInput förhindrar att lösenordet registreras i PowerShells historik.

PowerShell 
$password = Read-Host 'Enter a Password' -MaskInput

Undvik namngivningskonflikter

Vissa Azure-resurser, till exempel Azure Container Registry och Key Vault, har resurser knutna till domännamn. Dessa resurser måste ha ett globalt unikt namn. Därför använder du ett slumpmässigt värde som en del av namn när unikhet krävs. Om du inte gör det kan skript inte skapa nödvändiga resurser när flera personer kör dem. Slumpmässighet förhindrar inte konflikter, men kan minimera den.

Använd Get-Random för att lägga till ett slumptal i ett namn, till exempel:

PowerShell 
$newAcrName = "myacr-$(Get-Random)"

Interaktiva kodfragment

När du ska använda interaktiva kodfragment

Om Cloud Shell stöder varje Azure PowerShell-kommando i artikeln taggar du kodblocken med azurepowershell-interactive för att lägga till knappen Öppna Cloud Shell i kodfragmenten:

```azurepowershell-interactive
Get-AzResourceGroup | Select-Object -Property ResourceGroupName, Location
```

När DU INTE ska använda interaktiva kodfragment

Använd inte azurepowershell-interactive om artikeln innehåller några Azure PowerShell-kommandon som inte fungerar i Cloud Shell. Använd endast azurepowershell. Cmdleten Install-AzAksCliTool stöds till exempel inte i Cloud Shell:

Azure PowerShell 
Install-AzAksCliTool

Om du blandar funktionella Cloud Shell-kommandon med kommandon som inte fungerar i Cloud Shell riskerar du att frustrera kunder när bara vissa kommandon fungerar. Håll dig i stället till azurepowershell språktaggen för alla kodblock för att undvika förvirring.

Eftersom användarna redan är autentiserade när de loggar in på Cloud Shell ska du inte använda taggen azurepowershell-interactive för kodblock som bara innehåller Connect-AzAccount. Använd azurepowershell språktaggen i stället.

Uppdatera AzureRM till Az PowerShell-modulen

Se Migrera Azure PowerShell från AzureRM till Az för information om hur du uppdaterar kommandon som använder AzureRM PowerShell-modulen till Az PowerShell-modulen.