Megosztás a következőn keresztül:

Szövegformázási útmutató

  • Cikk

A félkövér, dőlt és kód stílusok megfelelő és egységes használata hozzájárul a szöveg jobb olvashatóságához, és segít a félreértések elkerülésében is.

Félkövér

A felhasználói felület különféle elemeinél, például menün belüli kiválasztásoknál, párbeszédablakok nevénél vagy beviteli mezőknél használjon félkövér formázást.

Példák

  • Ez: A Megoldáskezelőben kattintson a jobb gombbal a projektcsomópontra, majd válassza az Új elem hozzáadása >lehetőséget.
  • Nem így van: A Megoldáskezelőben kattintson a jobb gombbal a projektcsomópontra, majd válassza az Új elem hozzáadása > lehetőséget.
  • Nem így van: A Megoldáskezelőben kattintson a jobb gombbal a projektcsomópontra, majd válassza az Új elem hozzáadása >lehetőséget.

Dőlt

Használjon dőlt formázást a következőkhöz:

  • Olyan új kifejezések bevezetésénél, amelyeket definícióval vagy magyarázattal is ellát.
  • Fájlnevek, mappanevek, elérési útvonalak.
  • Felhasználói bevitel.

Példák

  • Így helyes: Az App Service-ben az alkalmazások egy App Service-csomagban futnak. Az App Service-csomag az alkalmazás futtatásához használható számítási erőforrásokat határozza meg.
  • Nem így van: A App Service egy alkalmazás "App Service csomagban" fut. A App Service-csomag számítási erőforrások készletét határozza meg egy webalkalmazás futtatásához.
  • Így helyes: Cserélje a HttpTriggerCSharp.cs kódját a következő kódra.
  • Így nem helyes: Cserélje a HttpTriggerCSharp.cs kódját a következő kódra.
  • Így helyes: Névként adja meg a ContosoUniversity értéket, majd válassza a Hozzáadás lehetőséget.
  • Így nem helyes: Névként adja meg a „ContosoUniversity” értéket, majd válassza a Hozzáadás lehetőséget.

Kód stílus

A kód stílust használja a következőkhöz:

  • Kódrészleteknél, például metódusok és tulajdonságok nevei vagy nyelvi kulcsszavak.
  • SQL parancsok
  • NuGet-csomagok nevei
  • Parancssori parancsok*
  • Adatbázisok tábláinak és oszlopainak a nevei
  • Nem honosítandó erőforrásnevek (például virtuális gépek nevei)
  • Nem kattinthatónak szánt URL-ek nevei

Miért? A régebbi stílusú útmutatók ezen szövegelemek közül számos esetében félkövér formázást határoznak meg. A legtöbb cikket azonban honosítják, és a kód stílus arra utasítja a fordítót, hogy a szöveg egy részét hagyja lefordítatlanul.

A kódstílus lehet beágyazott (') vagy bekerített kódblokkok ('' körülvéve), amelyek több sorra terjednek ki. A hosszabb kódrészleteket és elérési útvonalakat körülhatárolt kódtömbökben jelenítse meg.

* A parancssori parancsokban használjon perjeleket a fájlelérési utakban, ha azok minden platformon támogatottak. Fordított perjelekkel szemléltetheti a Windows rendszeren futó parancsokat, ha csak fordított perjelek támogatottak. A perjelek például minden platformon működnek a .NET CLI-n, ezért a helyett a parancsot kellene használnia dotnet build foldername/filename.csprojdotnet build foldername\filename.csproj.

Beágyazott stílusokat használó példák

  • Így helyes: Alapértelmezés szerint az Entity Framework az Id vagy a ClassnameID nevű tulajdonságot elsődleges kulcsként értelmezi.
  • Így nem helyes: Alapértelmezés szerint az Entity Framework az Id vagy ClassnameID nevű tulajdonságot elsődleges kulcsként értelmezi.
  • Így helyes: A Microsoft.EntityFrameworkCore csomag futásidejű támogatást biztosít az EF Core számára.
  • Így nem helyes: A Microsoft.EntityFrameworkCore csomag futásidejű támogatást biztosít az EF Core számára.

Példák körülhatárolt kódblokkokra

  • Így helyes: Az adatbázisba nem lesznek parancsok küldve olyan kifejezések használatakor, amelyek csupán egy IQueryable-t módosítanak, mint például az alábbi kód:

        ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```

  • Nem így van: A rendszer nem küld parancsokat az adatbázisnak olyan utasítások alapján, amelyek egyszerűen módosítanak egy IQueryable-t, például var students = context. Students.Where(s => s.LastName == "Davolio").

  • Így helyes: Ha például a Get-ServiceLog.ps1 szkriptet szeretné a C:\Scripts könyvtárban futtatni, írja be az alábbi szöveget:

        ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```

  • Így nem helyes: Ha például a Get-ServiceLog.ps1 szkriptet szeretné futtatni a C:\Scripts könyvtárban, akkor ezt írja be: "C:\Scripts\Get-ServiceLog.ps1."

  • Az összes körülhatárolt kódrészletnek jóváhagyott nyelvcímkével kell rendelkeznie. A támogatott nyelvcímkék listáját lásd: Kód beágyazása dokumentumokba.

Helyőrzők

Ha azt szeretné, hogy a felhasználó lecserélje egy bemeneti sztring egy részét a saját értékeire, használjon szögletes zárójelekkel jelölt helyőrző szöveget (karakternél <> kisebb és nagyobb).

1. lehetőség: Használjon kódformázást a helyőrző szó vagy az azt magában foglaló kifejezés körül. Használhat például egy backticks "-t egy szövegközi kódformázáshoz egyetlen kifejezéshez, vagy tripla osztásjeleket "" a kódkerítésű formázáshoz.

`az group delete -n <ResourceGroupName>`

Renderelés:

az group delete -n <ResourceGroupName>

vagy

2. lehetőség: Használjon fordított perjelet \ a Markdown szögletes zárójelkarakterek ( például \< és \>) feloldásához. Bár csak a bal oldali szögletes zárójel \< első feloldása szükséges, a záró szögletes zárójel \> elhagyása a konzisztencia szempontjából is működik. A renderelt HTML nem jeleníti meg a feloldó karaktert az olvasónak:

az group delete -n \<ResourceGroupName\>

Renderelés:

az group delete -n <ResourceGroupName>

Tájékoztassa az olvasót a helyőrzőről: Az ilyen helyőrző példákat megelőző szövegben magyarázza el az olvasónak, hogy a szögletes zárójelben lévő szöveget el kell távolítani, és valós értékekkel kell helyettesíteni. Javasoljuk, hogy a felhasználói bevitelhez dőlt betűs formázást használjon. A dőlt betűket szögletes zárójeles beágyazott kódban formázhatja:

Az alábbi példában cserélje le a helyőrző szöveget <ResourceGroupName> a saját erőforráscsoport-nevére.

Figyelemfelhívás

A Microsoft Learn webhely nem jeleníti meg <a szögletes zárójeleket használó helyőrző> szöveget olyan esetekben, amikor a szögletes zárójelek nincsenek megfelelően feloldva, vagy a szöveg nem kódformátumú. A Microsoft Learn buildelési folyamata a <helyőrző> kifejezést HTML-címkeként értelmezi, amely veszélyes lehet az olvasó böngészőjére, és letiltott html-címkeként jelöli meg. Megjelenik egy javaslat a buildjelentésben, és a helyőrző szó nem jelenik meg a Microsoft Learn lap kimenetében, amikor ez történik.

A helyőrzők tartalomvesztésének elkerülése érdekében használjon code formázást vagy feloldó karaktereket (\<\>) a korábban leírtak szerint.

Nem javasoljuk a kapcsos zárójelek { } használatát szintaktikai helyőrzőkként. Az olvasók összekeverhetik a kapcsos zárójeles helyőrzőket a következőben használt jelöléssel:

  • Cserélhető szöveg
  • Sztringek formázása
  • Sztringinterpoláció
  • Szövegsablonok
  • Hasonló programozási szerkezetek

Burkolat és térköz: Elválaszthatja a helyőrzőneveket kötőjelekkel ("kebab-eset") vagy aláhúzásjelekkel, vagy Pascal-esettel. A Kebab-eset szintaktikai hibákat okozhat, és az aláhúzások ütközhetnek az aláhúzással. Az all-caps számos nyelven ütközhet a nevesített állandókkal, de felhívhatja a figyelmet a helyőrző nevére is.

<Resource-Group-Name> vagy <ResourceGroupName>

Címsorok és hivatkozásszövegek

Ne alkalmazzon beágyazott stílust, például dőlt vagy félkövér stílust a címsorokra vagy hivatkozásszövegekre.

Miért?

Az emberek a hiperhivatkozások szokásos megjelenése alapján ismerik fel, hogy mely szövegrész kattintható hivatkozás. Ha például dőlt betűsre formáz egy hivatkozást, azzal elfedheti azt a tényt, hogy a szöveg hivatkozás. A címsorok saját stílussal rendelkeznek, így zavaró lehet, ha másféle stílust is felhasznál bennük.

Példák címsorokra és hivatkozásszövegre

  • Ez: A function.json fájlt a Microsoft.NET.Sdk.Functions NuGet-csomag hozza létre.

  • Nem így van: A function.json fájlt a Microsoft.NET.Sdk.Functions NuGet-csomag hozza létre.

  • Így helyes:

    ### The Microsoft.NET.Sdk.Functions package

  • Így nem helyes:

    ### The *Microsoft.NET.Sdk.Functions* package

Billentyűk és billentyűparancsok

Billentyűkre vagy billentyűkombinációkra való hivatkozáskor kövesse az alábbi konvenciókat:

  • A billentyűk neveinek első betűje legyen nagybetű.
  • Vegye körül a kulcsneveket és </kbd> a <kbd> HTML-címkéket.
  • A "+" billentyűkombinációval összekapcsolhatja a felhasználó által egyidejűleg kiválasztott kulcsokat.

Példák billentyűkre és billentyűparancsokra

  • Ez: Válassza az Alt+ CtrlSbillentyűkombinációt+.
  • Így nem helyes: Nyomja le az ALT+CTRL+S billentyűkombinációt.
  • Így nem helyes: Nyomja le az ALT+CTRL+S billentyűkombinációt.

Kivételek

A stílusirányelvek nem merev szabályok. Olyan kontextusban, ahol az olvashatóság rovására mennek, járjon el másként. Egy többnyire kódrészleteket tartalmazó HTML-táblázat például túlzsúfoltnak tűnhet, ha mindenütt kód stílust alkalmaz benne. Ebben a kontextusban félkövér stílust is választhat.

Ha ott alkalmaz helyettesítő stílust, ahol normális esetben a kód stílus indokolt, ügyeljen rá, hogy ez nem okoz problémát a cikk honosított verzióiban fordítandó szövegében. A kód stílus ugyanis az egyetlen olyan stílus, amely automatikusan megakadályozza a fordítást. Olyan helyzetekben, amelyekben a kód stílusa nélkül szeretné megakadályozni a honosítást, lásd: Nem honosított sztringek.