Açıklayıcı PowerShell Yorumları Nasıl Oluşturulur?

PowerShell'e yeni gelen biri komut dosyası yazmaya başladığında genellikle koda odaklanır. Sonuçta, bazı şeylerin gerçekleşmesini sağlayan şey koddur! Çalıştırılabilir kod elbette önemlidir, ancak bu kadar çok kod yazdığınızda ne yaptığını unutursanız ne olur? Bu, PowerShell yorumlarının gelebileceği zamandır.

Bir takımdaysanız yazdığınız kodu anlıyorlar mı? PowerShell yorumları yardımcı olabilir.

Betiklere açıklayıcı ve bilgilendirici PowerShell yorumları yazmak, biz insanların kodun amacını, sonucu anlamamıza yardımcı olur ve belki de aynı anda karşılaşılan uç durumları açıklar.

Bu makalede, PowerShell'deki farklı yorum türlerini, hangilerini kullanacağınızı ve bunları komut dosyalarınızda etkili bir şekilde nasıl kullanacağınızı öğreneceksiniz.

Tek Satırlı PowerShell Yorumlarını Kullanma

Hiç bir kod yazdınız ve onu haftalar veya aylar sonra gözden geçirmek zorunda kaldınız mı? Muhtemelen. Bunu çok sonra mı anladın? Belki de değil. Keşke kodunuza bazı yararlı yorumlar bırakmış olsaydınız!

Çoğu programlama dilinde yorum yapma kavramı bulunur. PowerShell bir istisna değildir. PowerShell'de arkadaşınız #. Aynı satırda hashtag'i (#) takip eden her şey PowerShell tarafından yorumlanmış kod olarak yok sayılır.

Aşağıdaki örnek kod bir komut dosyasından bir alıntıdır ve ne yaptığını öğrenmek için ilk satırdaki PowerShell komut dosyası yorumuna başvurabilirsiniz. Bir PowerShell uzmanıysanız muhtemelen bu pasajın ne yaptığını yorum yapmadan belirtebilirsiniz.

# Get all files with TXT extension, show the name of each file and then delete them.
Get-ChildItem *.TXT | ForEach-Object {
    Write-Output $_.FullName
    Remove-Item $_.FullName
}

Peki ya aşağıdakine benzer kısa bir komutla karşılaştığınızda?

"{0},{1}" -f [bool](gm -input (1..20) -name count), (1..20).count

Yorum eklemek size veya sonunda kodunuzu okuyacak olan herkese harika bir hizmet sağlayacaktır. Aşağıda görebileceğiniz gibi terse komutunun üstüne yorum eklemek kodun anlaşılmasında büyük fark yaratacaktır.

#Check whether the object has a property named "count". Then, return true or false.
"{0},{1}" -f [bool](gm -input (1..20) -name count), (1..20).count

PowerShell Blok Yorumlarını/Çok Satırlı Yorumları Kullanma

Önceki bölümde bir yorumun # karakteriyle başladığını öğrendiniz. Birden fazla yorum satırı oluşturmanıza engel yok. Aslında PowerShell 2.0'dan önce çok satırlı yorumlar oluşturmanın tek yolu, birden çok satırlık tek satırlı yorum oluşturmaktı.

Yorumları kısa ve öz tutmak iyidir ancak bazı senaryolar, PowerShell yorum bloğu olarak da adlandırılabilecek bir PowerShell çok satırlı yorumu kullanılmasını gerektirir.

PowerShell'deki bir yorum bloğu <# ile başlar ve #> ile biter. Aşağıda bir yorum bloğunun ne zaman uygulanabileceğine ilişkin bazı örnekler verilmiştir.

Uzun Bir Yorumu Birden Çok Satıra Bölme

Bazen bir senaryoda uzun bir yorumun olması kaçınılmazdır. Bu uzun yorumlar, ekrandaki mevcut çerçevenizin çok ötesine geçebilir. Böyle bir durumda yorum satırının tamamını okumak için yatay olarak kaydırmaya devam etmeniz gerekecektir.

Örneğin, aşağıdaki gibi uzun, tek satırlık bir yorum yerine:

# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display. And when that happens, you will need to keep on scrolling horizontally to read the entire comment line.

Neden bunu aşağıdaki gibi okunması daha kolay olan çok satırlı bir yoruma dönüştürmüyorsunuz:

<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>

Açıklayıcı Metin Ekleme

Hiç bir komut dosyası indirdiniz veya yazdınız mı ve onu rastgele veya açıklayıcı olmayan bir adla kaydettiniz mi? Biliyorum!

Ne olduğunu öğrenmek için betiği açtığınızda, betiğin ne için olduğu, onu kimin oluşturduğu ve ne zaman oluşturulduğu gibi yararlı ayrıntıların içinde listelenmesi kesinlikle güzel olurdu.

PowerShell'deki blok yorumu, komut dosyalarınıza açıklayıcı metin eklemek için kullanışlıdır. Bu şekilde, betiğin amacı zaten verilmiştir ve ayrıca betiği kullanırken uyarıları veya dikkat edilmesi gereken şeyleri eklemenin harika bir yoludur.

Aşağıda, betiğin ne olduğunu, en son ne zaman güncellendiğini açıklayan ve ayrıca betiği çalıştırırken ne yapılmaması gerektiğine dair bir uyarı gösteren bir blok yorumu örneği bulunmaktadır.

<# Using this script will export the email addresses of all mailboxes in the Exchange organization.

WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL.

Last update: Feb 16, 2020
#>

Gereksinimleri ve Adımları Belgelemek

Betiğinizin belirli bir yürütme yöntemi varsa veya çalıştırılması için özel gereksinimleri varsa, yorumları engellemek betiğinizin veya işlevinizin içinde belgelenmesine yardımcı olacaktır.

Aşağıda blok yorumlarını kullanarak bir gereksinimi ve adımları belgelemenin bir örneği verilmiştir.

<#
This function requires an encrypted credential XML file that will be used
to authenticate with Office 365.

If you don't have this yet, follow these steps.

1. Open PowerShell
2. Run this command - 'Get-Credential | Export-CliXml .\credential.XML'
3. Make sure to save the XML file inside the same folder as the script.

NOTE: The credential XML file will only work on the same computer and the same account
used to generate it.
#>

Mevcut Kodun Yorumlanması

Yorumlar yalnızca yorum eklemek amacıyla kullanılmaz. Ayrıca mevcut kod satırlarını tek satıra dönüştürebilir veya yorumları engelleyebilirsiniz.

Belki kendinizi komut dosyalarını test ederken veya hata ayıklarken bulursunuz. Kod yorumlandığında, PowerShell bu kodun çalışma zamanı sırasında yürütülmesini atlar.

Örneğin, Active Directory'deki kullanıcıların listesini alan bir komut dosyanız var ve bu liste, Set-AdUserforeach döngüsü kullanılarak işleniyor. > cmdlet'i seçin.

<#
This script will get all AD users matching the filter
and each user's department name will be changed to 'Finance'.
#>
$adUsers = Get-ADUser -Filter *
foreach ($user in $adUsers) {
    Write-Output "$($user.Name) - Department name will be changed to 'Finance'"
    Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'
}

Ancak foreach döngüsünü henüz Set-AdUser satırını çalıştırmadan test etmek istiyorsanız, söz konusu satırı şu şekilde yorumlamanız yeterlidir:

foreach ($user in $adUsers) {
    Write-Output "$($user.Name) - Department name will be changed to 'Finance'"
    #Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'
}

Artık komut dosyası, her kullanıcının departman adını değiştirmeden güvenli bir şekilde test edilebilir.

İPUCU: Visual Studio Code'da, “CTRL + /” klavye kısayoluna basarak bir satıra veya birden fazla satıra yorum yapabilirsiniz.

Artık, birden çok satıra yorum eklemek istiyorsanız, her satırın başına bir # koyma seçeneğiniz vardır veya <# #> içine birden çok satır ekleyebilirsiniz. bloğu aşağıdaki örnekte gösterildiği gibi. Gördüğünüz gibi foreach döngüsünün tamamı blok yorumuna dönüştürüldü.

$adUsers = Get-ADUser -Filter *
<# foreach ($user in $adUsers) {
    Write-Output "$($user.Name) - Department name will be changed to 'Finance'"
    Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'
} #>

İPUCU: Visual Studio Code'da, bir veya birden fazla kod satırını vurgulayıp “ALT +SHIFT + A” klavye kısayoluna basarak da bir yorum bloğu oluşturabilirsiniz.

Yoruma Dayalı Yardım

Komut dosyalarınızın veya işlevlerinizin daha profesyonel görünmesini istediğinizde, yoruma dayalı yardım ekleyerek bunu yapabilirsiniz. Yoruma dayalı yardım, bir blok yorumun içine alınmış anahtar kelimeler ve metinlerden oluşan bir koleksiyondur.

Yoruma Dayalı Yardım anahtar kelimesi ve sözdizimi hakkında daha fazla bilgi edinmek için - Yoruma Dayalı Yardım Hakkında - sayfasını ziyaret edin.

Aşağıdaki örnek kod, yorum tabanlı yardım içeren Get-WhatTimeIsItNow.ps1 adlı bir komut dosyasını gösterir.

<#
.SYNOPSIS

Short description of the script.

DESCRIPTION

Long description of the script

.EXAMPLE

PS C:\> Get-WhatTimeIsItNow.ps1

Explanation of what the example does

.INPUTS

Inputs (if any)

.OUTPUTS

Output (if any)

.NOTES

General notes
#>

Get-Date -Format t

Yoruma dayalı, komut dosyalarınız için Get-Help desteğini etkinleştirir. Bu, Get-Help