Anteckning
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Konsekvent och lämplig användning av fet stil, kursiv stil och kod för textelement förbättrar läsbarheten och förhindrar att texten missförstås. Om ett textformateringselement inte omfattas av den här vägledningen kan du läsa Microsoft Writing Style Guide. Följande artiklar innehåller detaljerad vägledning om textformatering:
Gränssnittselement
Gränssnittselement, som menyalternativ, dialognamn och namn på textrutor, ska vara i fetstil.
Så här: I Solution Explorer högerklickar du på projektnoden och väljer sedan Lägg till>nytt objekt.
Inte så här: Högerklicka på projektnoden i Solution Explorer och välj sedan Lägg till > nytt objekt.
Git-lagringsplats och grennamn
Använd fet text för Git-lagringsplatsen eller grennamn när du väljer eller anger dem i instruktionerna.
Så här: Från grenmenyn väljer du main.
Inte så här: Från grenmenyn, välj "main".
Introduktioner av nya termer
Använd kursiv text för att introducera en ny term tillsammans med en definition eller förklaring. Kursivera den nya termen första gången du använder den och använd sedan vanlig text för definitionen eller förklaringen.
Så här: En app körs i en App Service-plan i App Service. En App Service-plan definierar en uppsättning beräkningsresurser som en webbapp körs på.
Inte så här: I App Service körs en app i en "App Service-plan". En App Service-plan definierar en uppsättning beräkningsresurser som en webbapp ska köras på.
Kodstil
Använd kodstil för:
- Kodelement som till exempel metodnamn, egenskapsnamn och nyckelord.
- SQL-kommandon
- Namn på NuGet-paket
- Kommandoradskommandon*
- Namn på tabeller och kolumner i databaser
- Resursnamn som inte ska lokaliseras (till exempel namn på virtuella datorer)
- Webbadresser som du inte vill ska vara klickbara
Varför? Vissa formatmallar anger fetstil för många av dessa textelement. De flesta artiklar är dock lokaliserade, och kodstilen anger för översättaren att den delen av texten som lämnas oöversatt.
Kodformatet kan vara infogat (omgivet av ") eller inhägnat kodblock (omgivet av "") som sträcker sig över flera rader. Sätt längre kodfragment och sökvägar i inhägnade kodblock.
* Använd snedstreck i filsökvägar i kommandoradskommandon om de stöds på alla plattformar. Använd omvänt snedstreck för att illustrera kommandon som körs i Windows, när endast omvänt snedstreck stöds. Till exempel fungerar snedstreck på .NET CLI på alla plattformar, så du använder dotnet build foldername/filename.csproj
i stället dotnet build foldername\filename.csproj
för .
Exempel på infogat format
-
Så här: Som standard tolkar Entity Framework en egenskap som har namnet
Id
ellerClassnameID
som den primära nyckeln. - Inte så här: Som standard tolkar Entity Framework en egenskap som har namnet ID eller ClassnameID som den primära nyckeln.
-
Så här: Paketet
Microsoft.EntityFrameworkCore
har stöd för körning av EF Core. - Inte så här: Paketet Microsoft.EntityFrameworkCore har stöd för körning av EF Core.
Exempel på inhägnade kodblock
Så här: Inga kommandon skickas till databasen via uttryck som bara ändrar en
IQueryable
, till exempel följande kod:```csharp var students = context.Students.Where(s => s.LastName == "Davolio") ```
Inte så här: Inga kommandon skickas till databasen med instruktioner som bara ändrar en IQueryable, till exempel var students = kontext. Students.Where(s => s.LastName == "Davolio").
Så här: För att till exempel köra skriptet
Get-ServiceLog.ps1
i mappenC:\Scripts
skriver du:```powershell C:\Scripts\Get-ServiceLog.ps1 ```
Inte så här: För att till exempel köra skriptet Get-ServiceLog.ps1 i mappen C:\Scripts skriver du: "C:\Scripts\Get-ServiceLog.ps1."
Alla inhägnade kodblock måste ha en godkänd språktagg. Du hittar en lista med stöd språktaggar som stöds i Så här inkluderar du kod i dokument.
Platshållare
I stycketext eller procedursteg använder du kursiv stil för platshållartext som användarna kommer att ersätta med sin egen information.
Så här: Ange lösenord
Inte så här: Ange "lösenord"
Så här: Ange -plösenord
Inte så här: Ange -p lösenord
Om du vill att användaren ska ersätta en del av en indatasträng med sina egna värden använder du platshållartext markerad med vinkelparenteser (mindre än <
och större än >
tecken).
Alternativ 1: Använd kodformatering för att omge platshållarordet eller den omfattande frasen. Du kan till exempel använda enkla backticks för infogad kodformatering för en enda fras eller trippel-ticks för kodstängd formatering.
`az group delete -n <ResourceGroupName>`
Återges som:
az group delete -n <ResourceGroupName>
eller
Alternativ 2: Använd ett omvänt snedstreck \
för att undkomma vinkelparentestecken i Markdown, till exempel \<
och \>
. Även om endast den första flykten på den vänstra vinkelparentesen \<
krävs, fungerar det för att undvika den avslutande hakparentesen \>
för konsekvens. Den renderade HTML-koden visar inte escape-tecknet för läsaren:
az group delete -n \<ResourceGroupName\>
Återges som:
az group delete -n <ResourceGroupName> (ta bort resursgruppen)
Informera läsaren om platshållaren: Förklara för läsaren i texten som föregår platshållarexempel att texten inom parentes måste tas bort och ersättas med verkliga värden. Vi rekommenderar användning av kursiv stil för användarindata. Du kan formatera kursiv stil inom vinkelparenteserad infogad kod:
I följande exempel ersätter du platshållartexten
<ResourceGroupName>
med ditt eget resursgruppsnamn.
Varning
Microsoft Learn-webbplatsen återger <inte platshållartext> som använder vinkelparenteser i fall där hakparenteserna inte är korrekt undantagna eller om texten inte är kodformaterad. Microsoft Learn-kompileringsprocessen tolkar platshållarfrasen< som en HTML-tagg som kan vara farlig för läsarens webbläsare och flaggar >den som en otillåten html-tagg. Du ser ett förslag i byggrapporten och platshållarordet återges inte i Microsoft Learn-sidans utdata när det händer.
Om du vill undvika innehållsförlust på platshållare använder du code
formatering eller escape-tecken (\<
\>
) enligt beskrivningen tidigare.
Vi avråder från att använda klammerparenteser { } som syntaktiska platshållare. Läsare kan blanda ihop klammerparenteser med samma notation som används i:
- Ersättningsbar text
- Formatsträngar
- Stränginterpolering
- Textmallar
- Liknande programmeringskonstruktioner
Hölje och avstånd: Du kan separera platshållarnamn med bindestreck ("kebabfall") eller med understreck, eller så kan du göra det med hjälp av Pascal-skiftläge. Ett kebabfall kan generera syntaxfel och understreck kan vara i konflikt med understreck. Användning av versaler kan komma i konflikt med namngivna konstanter på många språk, men det kan också dra uppmärksamhet till platshållarnamnet.
<Resource-Group-Name>
eller<ResourceGroupName>
Rubriker
Använd inte ett infogat format som kursivt, fetstilt eller infogat kodformat på rubriker.
Varför? Rubriker har sina egna stilar, och om du blandar andra format skapas inkonsekvenser.
Så här: Importera paketet Microsoft.NET.Sdk.Functions
Inte så här: Importera paketet Microsoft.NET.Sdk.Functions
Länktext
Använd inte infogade format som kursiv eller fet stil för att länka text.
Varför? Användare ser hyperlänktext och identifierar dem som textelement med klickbara länkar. Om du till exempel formaterar en länk som kursiv kan det dölja det faktum att texten är en länk.
- Så här: NuGet-paketet Microsoft.NET.Sdk.Functions genererar den function.json filen.
Inte så här: NuGet-paketet Microsoft.NET.Sdk.Functions genererar den function.json filen.
Tangenter och kortkommandon
Följ de här riktlinjerna när du hänvisar till tangenter eller tangentkombinationer:
- Skriv den första bokstaven i namn på tangenter med en versal.
- Omge nyckelnamnen med
<kbd>
och</kbd>
HTML-taggarna. - Använd "+" för att koppla nycklar som användaren väljer samtidigt.
Exempel på nycklar och kortkommandon
- Detta: Välj Alt+Ctrl+S.
- Inte så här: Tryck på ALT+CTRL+S.
-
Inte så här: Tryck på
ALT+CTRL+S
.
Undantag
Konsekventa formatriktlinjer skapar en tillförlitlig kundupplevelse och förenklar redigeringsprocessen. Undantag från dessa riktlinjer måste övervägas noga.
Om undantaget innebär att du använder ett alternativt textformat som normalt kräver kod kontrollerar du att det är OK att översätta texten i lokaliserade versioner av artikeln. I situationer där du vill förhindra lokalisering utan att använda kodstil kan du läsa Strängar som inte ska lokaliseras.