Aracılığıyla paylaş

Hakkında_Yorumlar

  • Makale

Kısa açıklama

PowerShell açıklamalarının nasıl kullanılacağını açıklar ve özel kullanım örneklerini listeler.

Uzun açıklama

Okunabilirliğe yardımcı olması için PowerShell kodunuzu açıklama eklemek veya yapılandırmak için açıklamalar yazabilirsiniz. Kodunuz çalıştırıldığında, açıklama metni PowerShell tarafından yoksayılır.

Açıklamalar, kodu okuyanlara önemli bağlam sağlar. Açıklamaları aşağıdaki amaçlarla kullanmalısınız:

  • Karmaşık kodu daha basit terimlerle açıklama
  • Belirli bir yaklaşımın neden seçildiğini açıklama
  • Dikkat edilmesi gereken uç durumları belgele
  • Destekleyici başvuru malzemelerinin bağlantılarını sağlayın

Bazı açıklamaların PowerShell'de özel bir anlamı vardır. bkz. Özel açıklamalar.

PowerShell açıklama stilleri

PowerShell iki açıklama stilini destekler:

  • Tek satırlı açıklamalar karma karakterle (#) başlar ve yeni bir satırla biter. # önünde açıklamanın parçası olmayan metinler (boşluk da dahil) bulunabilir. Sıkıştırılmamış kaynak koduyla aynı satıra yerleştirilen tek satırlı açıklamalar satır sonu açıklamaları olarak bilinir.

  • Açıklamaları engelle<# ile başlar ve #>ile biter. Blok açıklaması herhangi bir sayıda satıra yayılabilir ve sıkıştırılmamış kaynak kodundan önce, sonra veya ortasına eklenebilir. Blok içindeki tüm metinler, boşluk da dahil olmak üzere aynı açıklamanın bir parçası olarak değerlendirilir.

    Önemli

    Blok açıklamasına tek satırlı açıklamalar ekleyebilirsiniz. Ancak, blok açıklamalarını iç içe yerleştiremezsiniz. Blok açıklamalarını iç içe yerleştirmeye çalışırsanız, dış blok açıklaması karşılaşılan ilk #> noktasında biter.

Örnekler

Örnek 1: Tek satırlı açıklama

# This is a single-line comment.
# This is also a single-line comment.

Örnek 2: Açıklamayı engelle

<#
    This is a block comment.
    Text within the block is a part of the same comment.
Whitespace is unimportant in a block comment.
#>

Örnek 3: Satır sonu açıklaması

$var = 4 # This is an end-of-line comment

Örnek 4: Satır içi blok açıklaması

'Foo'; <# This is an inline block comment #> 'Bar'

Örnek 5: Tam örnek

<#
    .DESCRIPTION
    Demonstrates PowerShell's different comment styles.
#>
param (
    [string] $Param1, # End-of-line comment
    <# Inline block comment #> $Param2
)

$var = 1, <# Inline block comment #> 2, 2

# Single-line comment.
# Another single-line comment.
$var.Where(
    <# Arg1 note #> { $_ -eq 2 },
    <# Arg2 note #> 'First',
    <# Arg3 note #> 1
)

Özel açıklamalar

PowerShell, belirli kullanımları desteklemek için birkaç açıklama anahtar sözcüğü içerir.

Açıklama tabanlı yardım

İşlevler ve betikler için tek satırlı veya blok açıklamaları kullanarak açıklama tabanlı yardım içeriği yazabilirsiniz. Kullanıcılar Get-Help cmdlet'ini kullanarak bir işlev veya betik için açıklama tabanlı yardımı görüntüleyebilir. PowerShell, açıklama ve örnek kullanım gibi bilgileri sağlamak için kullanılabilecek 15 açıklama anahtar sözcüğü tanımlar.

<#
    .DESCRIPTION
    Comment-based help using a block comment.
#>
function Get-Function { }

# .DESCRIPTION
# Comment-based help using multiple single-line comments.
function Get-Function { }

Daha fazla bilgi için bkz:

#Requires

#Requires deyimi, geçerli PowerShell oturumu belirtilen önkoşulları karşılamadığı sürece bir betiğin çalışmasını engeller. #Requires betikteki herhangi bir satırda görünebilir, ancak konum fark etmeksizin aynı şekilde işlenir.

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0

param (
    [Parameter(Mandatory)]
    [string[]] $Path
)

Daha fazla bilgi için bkz. about_Requires.

İmza bloğu

Betikler, PowerShell yürütme ilkeleriyle uyumlu olacak şekilde imzalanabilir. İmzalandıktan sonra, betiğin sonuna bir imza bloğu eklenir. Bu blok, betik yürütülmeden önce PowerShell tarafından okunan birden çok tek satırlı yorum biçimindedir.

# SIG # Begin signature block
# ...
# SIG # End signature block

Daha fazla bilgi için bkz. about_Signing.

Shebang

Unix benzeri sistemlerde shebang (#!), betiği çalıştırmak için hangi kabuğun kullanılması gerektiğini belirtmek için betiğin başında kullanılan bir yönergedir. Shebang, PowerShell dilinin bir parçası değildir. PowerShell bunu normal bir açıklama olarak yorumlar. Shebang, işletim sistemi tarafından yorumlanır.

Aşağıdaki örnekte shebang, betik PowerShell olmayan bir bağlamdan çağrıldığında PowerShell'in betiği çalıştırmasını sağlar.

#!/usr/bin/env pwsh
Write-Host 'Begin script'

Kod düzenleyicisi bölge işaretçileri

Bazı kod düzenleyicileri, kodun bölümlerini daraltmanıza ve genişletmenize olanak sağlayan bölge işaretleyicilerini destekler. PowerShell için bölge işaretçileri, #region ile başlayıp #endregionile biten açıklamalardır. Bölge işaretçileri bir satırın başında olmalıdır. Bölge işaretçileri PowerShell ISE'de ve PowerShell uzantısıyla Visual Studio Code'da desteklenir. Bölge işaretçileri PowerShell dilinin bir parçası değildir. PowerShell bunları normal açıklamalar olarak yorumlar.

Daha fazla bilgi için Visual Studio Code'da Temel düzenleme belgelerinin Katlama bölümüne bakın.

Dize belirteçlerindeki açıklamalar

# ve <# #>'in, genişletilebilir veya özgün dize içinde özel bir anlamı yoktur. PowerShell karakterleri tam anlamıyla yorumlar.

PS> '# This is not interpreted as a comment.'
# This is not interpreted as a comment.

PS> "This is <# also not interpreted #> as a comment."
This is <# also not interpreted #> as a comment.

Ancak, bazı PowerShell özellikleri açıklama içeren dizelerle çalışacak şekilde tasarlanmıştır. Açıklamanın yorumlanması belirli özelliğe bağlıdır.

Normal ifade açıklamaları

PowerShell'deki normal ifadeler (regex), iki açıklama stilini destekleyen .NET regex altyapısını kullanır:

  • Satır içi açıklama ((?#))
  • Satır sonu açıklaması (#)

Regex açıklamaları, PowerShell'deki tüm regex tabanlı özellikler tarafından desteklenir. Örneğin:

PS> 'book' -match '(?# This is an inline comment)oo'
True

PS> 'book' -match '(?x)oo# This is an end-of-line comment'
True

PS> $regex = 'oo # This is an end-of-line comment'
PS> 'book' -split $regex, 0, 'IgnorePatternWhitespace'
b
k

Bir not

Satır sonu regex açıklaması için (?x) yapısı veya IgnorePatternWhitespace seçeneği gerekir.

Daha fazla bilgi için bkz:

JSON açıklamaları

PowerShell 6.0'dan başlayarak, ConvertFrom-Json cmdlet'i aşağıdaki JSON açıklama stillerini destekler:

  • Tek satırlı açıklama (//)
  • Açıklamayı engelle (/* */)

Bir not

Invoke-RestMethod cmdlet'i, alınan JSON verilerini otomatik olarak deserialize eder. PowerShell 6.0 ve üzeri sürümlerde, JSON verilerinde açıklamalara izin verilir.

Örneğin:

'{
    "Foo": "Bar" // This is a single-line comment
}' | ConvertFrom-Json

Foo
---
Bar

Uyarı

PowerShell 7.4 sürümünden başlayarak, Test-Json cmdlet'i artık açıklamalarla JSON'u desteklemez. JSON açıklama içeriyorsa bir hata döndürülür. 7.4 öncesi desteklenen sürümlerde Test-Json, JSON'ı açıklamalarla başarıyla ayrıştırıyor. PowerShell 7.5'te Test-Json, JSON açıklamalarını yoksayma seçeneği içerir.

CSV açıklamaları

Import-Csv ve ConvertFrom-Csv W3C Genişletilmiş Günlük biçimini destekler. Karma karakterle (#) başlayan satırlar açıklama olarak kabul edilir ve açıklama #Fields: ile başlayıp sütun adlarının sınırlandırılmış listesini içermediği sürece yoksayılır. Bu durumda, cmdlet bu sütun adlarını kullanır. Bu, Windows IIS ve diğer web sunucusu günlükleri için standart biçimdir. Daha fazla bilgi için bkz. Genişletilmiş Günlük Dosyası Biçimi.

@'
# This is a CSV comment
Col1,Col2
Val1,Val2
'@ | ConvertFrom-Csv

Col1 Col2
---- ----
Val1 Val2

Windows PowerShell 5.1'de, Export-Csv ve ConvertTo-Csv davranışı , tür bilgilerini açıklama biçiminde eklemektir. PowerShell 6.0'da başlayarak, varsayılan olarak açıklama dahil edilmez, ancak bu durum IncludeTypeInformation parametresi kullanılarak geçersiz kılınabilir.

[pscustomobject] @{ Foo = 'Bar' } | ConvertTo-Csv -IncludeTypeInformation

#TYPE System.Management.Automation.PSCustomObject
"Foo"
"Bar"

CSV verilerine bir #TYPE açıklaması eklendiğinde, seri durumdan çıkarılmış nesnelerin Import-Csv özelliğini ayarlamak için ConvertFrom-Csv ve pstypenames bu bilgileri kullanın.

class Test { $Foo = 'Bar' }
$test = [Test]::new()

$var = $test | ConvertTo-Csv -IncludeTypeInformation | ConvertFrom-Csv
$var.pstypenames

Test
CSV:Test

ConvertFrom-StringData yorumlar

Dize verileri içinde, ConvertFrom-StringData cmdlet'i # ile başlayan satırları açıklama olarak ele alır. Daha fazla bilgi için bkz:

Notlar

  • Blok açıklamaları iç içe yerleştirilemez. Aşağıdaki örnekte, Baz açıklamanın bir parçası değildir.

    <#
'Foo'
<# 'Bar' #>
'Baz'
#>

  • <# #> tek satırlı bir açıklama içinde özel bir anlamı yoktur. # blok açıklaması içinde özel bir anlamı yoktur.

  • Açıklama olarak ele alınabilmesi için, açıklama karakterinin açıklama olmayan belirtecin parçası olmaması gerekir. Aşağıdaki örnekte #Bar ve <#Bar#>Foo... belirtecinin bir parçasıdır. Bu nedenle, bunlar yorum olarak değerlendirilmez.

    PS> Foo#Bar
Foo#Bar: The term 'Foo#Bar' is not recognized as a name [...]

PS> Foo<#Bar#>
Foo<#Bar#>: The term 'Foo<#Bar#>' is not recognized as a name [...]