Yardım almak! PowerShell Komut Dosyalarında Yorum Tabanlı Yardımı Kullanma

Elbette PowerShell betiklerinizde zaten yorumları kullanıyorsunuz ve kesinlikle siz de yorumlanmamış betiklerden rahatsız olmuşsunuzdur.

PowerShell betiklerindeki yorumlar belirli süreçleri doğrudan kodda belgelemeyi mümkün kılar. Ayrıca, örneğin bir işlevin başka özelliklerle genişletilmesi gerekiyorsa kod parçacıklarına ek notlar eklenebilir.

Ancak bu saf bilgi içeriğinin ötesinde, PowerShell'deki yorumlar doğru kullanıldığında işlevlerinizle ilgili yardım makaleleri için kullanılabilir. Bu makalede, Get-Help aracılığıyla komut dosyası bilgilerini almak için meta verileri nasıl kullanacağınızı göstereceğim.

Yoruma Dayalı Yardım Anahtar Kelimeleri

Projemizin sihirli sözcüğü Yorum Tabanlı Yardım'dır.

Adından da anlaşılacağı gibi, bu yöntem yorumlar aracılığıyla yardım bilgisi oluşturmamıza olanak tanır. . Bu yorumların doğru şekilde düzenlenmesi ve biçimlendirilmesi gerekir; tam olarak nasıl yapılacağını bu bölümde öğreneceksiniz.

Prensip olarak iki türe ayırabiliriz: İşlevler ve Komut Dosyaları için. İlki bir katman daha derine iner ve meta verilerle sağlamak istediğimiz işlevlerle başlar. Ancak kodunuz işlevlerde hazırlanmadıysa, bu bilgilerin yer aldığı tam bir komut dosyası sağlamak da mümkündür.

Tam kullanımlarına bakmadan önce, Yorum Tabanlı Yardım için tüm anahtar kelimeleri burada listeliyorum:

KEYWORD

İŞLEV

SYNOPSIS

Komut dosyasının veya işlevin kısa açıklaması

DESCRIPTION

Kodun ayrıntılı açıklaması

PARAMETER

Kullanılan bir parametrenin açıklaması. Anahtar kelime birkaç kez kullanılıyor (parametre başına 1x). Parametre anahtar kelimeden sonra ek olarak adlandırılmalıdır!

INPUTS

Bir işlem hattı aracılığıyla işleve aktarılabilecek olası nesnelerin açıklaması.

OUTPUTS

Fonksiyonun çıkış değerleri

NOTES

Kod hakkında ek bilgi

LINK

İlgili çevrimiçi yardımın URL'si (varsa)

Bu yazının kapsamı dışına çıkmamak adına listelemeyi en sık kullanılan anahtar kelimelerle sınırlandıracağım. Microsoft Dokümanlar'da daha fazla anahtar kelime bulabilirsiniz.

Not: Komut dosyası başlık bilgisi, komut dosyalarının ScriptRunner yazılım platformunda kullanımında da önemli bir rol oynar. Bununla ilgili daha fazla bilgiyi buradan edinebilirsiniz: ScriptRunner'da kullanıma yönelik PowerShell Komut Dosyası Başlıkları ve Parametreleri.

Yorum Tabanlı Yardımı Kullanma

Yukarıda listelenen anahtar kelimeler kodda belirli bir formatta belirtilmiştir. Bu aşağıdakine benziyor:

PowerShell Komut Dosyası Başlığında Yardım Anahtar Kelimeleri ve İçeriğinin Gösterimi

Anahtar kelimelerin başında bir nokta bulunur; karşılık gelen metin, anahtar kelimenin altına yerleştirilir. Anahtar kelime bloğu “<##> ” kullanılarak yorumlanır.

Yorum Tabanlı Komut Dosyaları ve İşlevler, Yorum bloğunun farklı yerleştirilmesi açısından farklılık gösterir. İşlevler için bloğu işlev adının altına yerleştirmek en iyisidir. Diğer olasılıklar, bloğu doğrudan işlevin önüne (boş satır olmadan) veya işlev gövdesinin sonuna yerleştirmektir.

Komut dosyaları bilgiyle donatılacaksa, Yorum bloğu doğrudan ayarlanır kodun başında - mantıksal olarak bu, kısmi bölümler hakkında değil, bir bütün olarak komut dosyası hakkında da bilgi içerir.

Yorum Tabanlı Yardımın Örneği ve Kullanımı

Aşağıda, belirli bir dizinin tüm dizin ve dosya nesnelerini belirli bir hiyerarşi derinliğine kadar çıktı olarak veren bir fonksiyon aracılığıyla Yorum Tabanlı Yardımın pratikte nasıl kullanılabileceğini göstereceğiz.

PowerShell bu işlevselliği zaten sağlıyor; aşağıdaki örnek yalnızca anlama amaçlıdır.

Örnek işlev

Artık amaç, bir yardım makalesinde açıklamalar, örnekler ve parametre bilgileri aracılığıyla işlevselliği açıklamaktır.

İşlev başlığındaki meta veriler

Bu kodda artık bütünsel bir yardım yorumu yazıldı. Bu bilgiye ilişkin bir Yardım Edin çağrısında artık konsolda aşağıdaki çıktıyı alıyoruz:

Get-Help Get-ChildItemDepth çıktısı

-Examples parametresi, mevcut tüm örneklerin çıktısını almak için de kullanılabilir:

Komut dosyasında saklanan örneklerin çıktısı

İpucu: PowerShell'in en iyi uygulamalarına göre oluşturulmuş daha fazla komut dosyası örneği için ScriptRunner ActionPack'lerimize göz atın.

Çözüm

Prensip olarak Yorum Tabanlı Yardımın BT departmanlarına büyük faydalar sağladığı söylenebilir. Yalnızca kendiniz oluşturduğunuz işlevlere hızlı bir genel bakış elde etmekle kalmaz, aynı zamanda iş arkadaşlarınızın temel işlevleri tahmin etmek için çok sayıda kod satırıyla uğraşmalarına gerek kalmaz.

Sınırlı uzunluğundan dolayı, komut dosyası adı, ayrıntılı bilgiye girmeden, bir komut dosyasının işlevi hakkında yalnızca kaba bir gösterge verebilir. Yardım oluşturmanın bu yolu aynı zamanda kodun harici olarak belgelenmesi ihtiyacını da ortadan kaldırır.

Bu yardım bölümlerinin kullanılmasını açıkça gerektiren temel bir politika veya davranış kuralları varsa, Pester modülünü şiddetle önerebilirim. Her sürümden önce kodun yardım makalelerinin olup olmadığını kontrol edecek şekilde yapılandırılabilir. Her parametrenin bir açıklaması olup olmadığını bile kontrol edebilirsiniz.