Aracılığıyla paylaş

PowerShell-Docs stil kılavuzu

Bu makalede, PowerShell-Docs içeriğine özgü stil yönergeleri sağlanır. Genel Bakış'ta özetlenen bilgilere dayalıdır.

Biçimlendirme komutu söz dizimi öğeleri

Öğeler bir cümlede kullanıldığında PowerShell dilinin öğelerini biçimlendirmek için aşağıdaki kuralları kullanın.

  • Doğru Pascal durumunda cmdlet'ler ve parametreler için her zaman tam adı kullanın

  • Yalnızca takma adı özellikle göstermeniz gerektiğinde kullanın.

  • PowerShell anahtar sözcüklerinin ve işleçlerinin tümü küçük harf olmalıdır

  • Aşağıdaki öğeler kalın metin kullanılarak biçimlendirilmelidir:

    • Tür adları

    • Sınıf adları

    • Özellik adları

    • Parametre adları

      • Varsayılan olarak, parametresini kısa çizgi ön eki olmadan kullanın.
      • Söz dizimini gösterirken parametre adını kısa çizgiyle birlikte kullanın. parametresini ters köşelere sarmalar.

      Örneğin:

      The parameter's name is **Name**, but it's typed as `-Name` when used on the command
line as a parameter.

  • Aşağıdaki öğeler, backticks (`) kullanılarak biçimlendirilmelidir:

    • Özellik ve parametre değerleri

    • Köşeli parantezli tarzı kullanan isimleri yazın - Örneğin: [System.Io.FileInfo]

    • Karakterlere isimleriyle atıfta bulunmak. Örneğin: Yıldız karakterini (*) joker karakter olarak kullanın.

    • Dil anahtar sözcükleri ve işleçleri

    • Cmdlet, fonksiyon ve script adları

    • Komut ve parametre kısaltmaları

    • Yöntem adları - Örneğin: ToString() yöntemi nesnenin dize gösterimini döndürür

    • Değişkenler

    • Yerel komutlar

    • Dosya ve dizin yolları

    • Satır içi komut söz dizimi örnekleri - Bkz. Kod örnekleri için Markdown

      Bu örnekte bazı backtick örnekleri gösterilmektedir:

      The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns
the output to the `$files` variable.

```powershell
$files = Get-ChildItem C:\Windows
```

      Bu örnekte satır içi komut söz dizimi gösterilmektedir:

      To start the spooler service on a remote computer named DC01, you type:
`sc.exe \\DC01 start spooler`.

      Dosya uzantısını dahil etmek, doğru komutun PowerShell'in komut önceliğine göre yürütülmesini sağlar.

Kod örnekleri için Markdown

Markdown iki farklı kod stilini destekler:

  • Kod yayılımı (satır içi) - tek bir backtick (`) karakteriyle işaretlenir. Tek başına blok yerine paragraf içinde kullanılır.
  • Kod blokları - üçlü tırnak işareti (```) dizeleriyle etrafı kuşatılmış çok satırlı bir blok. Kod blokları, arka uçları izleyen bir dil etiketine de sahip olabilir. Dil etiketi, kod bloğunun içeriği için sözdizim vurgulamasını etkinleştirir.

Tüm kod blokları bir kod çitinde yer almalıdır. Kod blokları için hiçbir zaman girinti kullanmayın. Markdown bu desene izin verir, ancak sorunlu olabilir ve önlenmelidir.

Kod bloğu, üç köşeli (```) kod çiti ile çevrili bir veya daha fazla kod satırıdır. Kod çiti işaretçileri, kod örneğinden önce ve sonra ayrı satırlarda yer almalıdır. Açma işaretçisi isteğe bağlı bir dil etiketine sahip olabilir. Dil etiketi, işlenen web sayfasında söz dizimi vurgulamasını etkinleştirir.

Desteklenen dil etiketlerinin tam listesi için merkezi katkıda bulunan kılavuzundaki Çitli kod blokları bölümüne bakın.

Yayımlama ayrıca kod bloğunun içeriğini panoya kopyalayabilen bir Kopyala düğmesi ekler. Bu, kod örneğini test etmeniz için kodu bir betiğe yapıştırmanızı sağlar. Ancak, tüm örneklerin yazıldı olarak çalıştırılması amaçlanmamıştır. Bazı kod blokları PowerShell kavramlarının temel çizimleridir.

Belgelerimizde kullanılan üç tür kod bloğu vardır:

  1. Söz dizimi blokları
  2. Açıklayıcı örnekler
  3. Yürütülebilir örnekler

Söz dizimi kod blokları

Söz dizimi kod blokları, bir komutun söz dizimi yapısını açıklamak için kullanılır. Kod çitinde dil etiketi kullanmayın. Bu örnek, cmdlet'in Get-Command tüm olası parametrelerini gösterir.

```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```

Bu örnekte for ifadesi genelleştirilmiş terimlerle açıklanmaktadır.

```
for (<init>; <condition>; <repeat>)
{<statement list>}
```

Açıklayıcı örnekler

Bir PowerShell kavramını açıklamak için açıklayıcı örnekler kullanılır. Siz mümkün olduğunca örneklerde PowerShell istemlerini kullanmaktan kaçının. Ancak, açıklayıcı örneklerin kopyalanıp yürütülmek üzere yapıştırılması amaçlanmamıştır. Bunlar en yaygın olarak anlaşılması kolay basit örnekler için kullanılır. PowerShell istemini ve örnek çıkışı ekleyebilirsiniz.

Aşağıda PowerShell karşılaştırma işleçlerini gösteren basit bir örnek verilmiştir. Bu durumda okuyucunun bu örneği kopyalayıp çalıştırmasını amaçlamıyoruz. Bu örnekte basitleştirilmiş bir istem dizesi olarak kullanıldığına PS> dikkat edin.

```powershell
PS> 2 -eq 2
True

PS> 2 -eq 3
False

PS> 1,2,3 -eq 2
2

PS> "abc" -eq "abc"
True

PS> "abc" -eq "abc", "def"
False

PS> "abc", "def" -eq "abc"
abc
```

Yürütülebilir örnekler

Karmaşık örnekler veya kopyalanıp yürütülmesi amaçlanan örnekler aşağıdaki blok stili işaretlemeyi kullanmalıdır:

```powershell
<Your PowerShell code goes here>
```

PowerShell komutları tarafından görüntülenen çıktı, söz dizimi vurgulamasını önlemek için bir Çıkış kodu bloğu içine alınmalıdır. Örneğin:

```powershell
Get-Command -Module Microsoft.PowerShell.Security
```

```Output
CommandType  Name                        Version    Source
-----------  ----                        -------    ------
Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security
```

Kod Output etiketi, söz dizimi vurgulama sistemi tarafından desteklenen resmi bir dil değildir. Ancak yayımlama sistemimiz Çıktı etiketini web sayfasındaki kod kutusu çerçevesine eklediğinden bu etiket kullanışlıdır. Çıkış kodu kutusunda söz dizimi vurgusu yoktur.

Kodlama stili kuralları

Kod örneklerinde satır devamlılığından kaçının

PowerShell kod örneklerinde satır devamlılığı karakterlerini (`) kullanmaktan kaçının. Arka uç karakterlerini görmek zordur ve satırın sonunda fazladan boşluklar varsa sorunlara neden olabilir.

  • Çeşitli parametreleri olan cmdlet'ler için satır uzunluğunu azaltmak için PowerShell sıçramasını kullanın.
  • PowerShell'in doğal satır sonu fırsatlarından, boru (|) karakterleri, açma ayraçları ({), parantezler (() ve köşeli ayraçlardan ([) sonra olduğu gibi, yararlanın.

Örneklerde PowerShell istemlerini kullanmaktan kaçının

İstem dizesinin kullanılması önerilmez ve komut satırı kullanımını göstermek için kullanılan senaryolarla sınırlı olmalıdır. Bu örneklerin çoğu için istem dizesi olmalıdır PS>. Bu istem işletim sistemine özgü göstergelerden bağımsızdır.

Örneklerde komut istemini değiştiren komutları veya görüntülenen yolun senaryo açısından önemli olduğunu göstermek için yönlendirmeler gereklidir. Aşağıdaki örnekte, Kayıt Defteri sağlayıcısı kullanılırken istemin nasıl değiştiği gösterilmektedir.

PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir

    Hive: HKEY_CURRENT_USER\System

Name                   Property
----                   --------
CurrentControlSet
GameConfigStore        GameDVR_Enabled                       : 1
                       GameDVR_FSEBehaviorMode               : 2
                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}
                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}
                       GameDVR_HonorUserFSEBehaviorMode      : 0
                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

Örneklerde takma ad kullanmayın

Diğer adı özellikle belgelemediğiniz sürece tüm cmdlet'lerin ve parametrelerin tam adını kullanın. Cmdlet ve parametre adları doğru Pascal Kası adlarını kullanmalıdır.

Örneklerde parametreleri kullanma

Konumsal parametreleri kullanmaktan kaçının. Karışıklık olasılığını azaltmak için, parametre konumlu olsa bile parametre adını bir örnekte eklemeniz gerekir.

Cmdlet başvuru makalelerini biçimlendirme

Cmdlet başvuru makaleleri belirli bir yapıya sahiptir. PlatyPS bu yapıyı tanımlar. PlatyPS, Markdown'da PowerShell modülleri için cmdlet yardımı oluşturur. Markdown dosyalarını düzenledikten sonra, PlatyPS, Get-Help cmdleti tarafından kullanılan MAML yardım dosyalarını oluşturabilir.

PlatyPS, cmdlet başvurusu için belirli bir yapı bekleyen bir şemaya sahiptir. PlatyPS şema belgesi bu yapıyı açıklar. Şema ihlalleri, katkınızı kabul etmeden önce düzeltilmesi gereken derleme hatalarına neden olur.

  • ATX üst bilgi yapılarından hiçbirini kaldırmayın. PlatyPS belirli bir üst bilgi kümesini belirli bir sırada bekler.
  • H2 INPUTS ve OUTPUTS üst bilgilerinin bir H3 türü olmalıdır. Cmdlet giriş almazsa veya bir değer döndürmezse H3 değerini kullanın None .
  • Satır içi kod aralıkları herhangi bir paragrafta kullanılabilir.
  • Çitle çevrili kod blokları yalnızca ÖRNEKLER bölümünde kullanılabilir.

PlatyPS şemasında , ÖRNEKLER bir H2 üst bilgisidir. Her örnek bir H3 üst bilgisidir. Bir örnekte şema, kod bloklarının paragraflarla ayrılmasına izin vermez. Şema yalnızca aşağıdaki yapıya izin verir:

### Example X - Title sentence

0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

Her örneği numaralayıp kısa bir başlık ekleyin.

Örneğin:

### Example 1: Get cmdlets, functions, and aliases

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.

```powershell
Get-Command
```

### Example 2: Get commands in the current session

```powershell
Get-Command -ListImported
```

About_ dosyalarını biçimlendirme

About_* dosyalar Markdown'da yazılır, ancak düz metin dosyaları olarak gönderilir. Markdown'ı düz metne dönüştürmek için Pandoc kullanırız. About_* dosyaları, PowerShell'in tüm sürümlerinde ve yayımlama araçlarıyla en iyi uyumluluk için biçimlendirilir.

Temel biçimlendirme yönergeleri:

  • Paragraf satırlarını 80 karakterle sınırlandırma

  • Kod bloklarını 76 karakterle sınırla

  • Blok alıntılarını ve uyarıları 78 karakterle sınırlayın

  • Bu özel meta karakterleri \kullanırken ,$ ve <:

    • Bir başlık içinde, bu karakterlerin başına \ karakteri eklenerek kaçılmalıdır veya tırnak işaretleri (`) kullanılarak kod yayları içine alınmalıdır.

    • Bir paragrafın içinde bu karakterler kod aralıklarına yerleştirilmelidir. Örneğin:

      ### The purpose of the \$foo variable

The `$foo` variable is used to store ...

  • Markdown tabloları

    • Makaleler için About_* tablolar 76 karaktere sığmalıdır
      • İçerik 76 karakter sınırına sığmıyorsa, bunun yerine madde işareti listelerini kullanın
    • Her satırda açma ve kapatma | karakterlerini kullanma

Sonraki adımlar

Editör kontrol listesi

  • Last updated on