Aracılığıyla paylaş

Gerekli Geliştirme Yönergeleri

Cmdlet'lerinizi yazarken aşağıdaki yönergelere uyması gerekir. Bunlar, cmdlet'leri tasarlama yönergelerine ve cmdlet kodunuzu yazma yönergelerine ayrılmıştır. Bu yönergelere uymazsanız, cmdlet'leriniz başarısız olabilir ve kullanıcılarınız cmdlet'lerinizi kullanırken kötü bir deneyime sahip olabilir.

Bu Konu kapsamında

Tasarım Yönergeleri

Kod Yönergeleri

Tasarım Yönergeleri

Cmdlet'lerinizi ve diğer cmdlet'lerinizi kullanma arasında tutarlı bir kullanıcı deneyimi sağlamak için cmdlet'ler tasarlarken aşağıdaki yönergelere uyması gerekir. Sizin durumunuz için geçerli bir Tasarım kılavuzu bulurken, benzer yönergeler için Kod yönergelerine bakabilirsiniz.

Yalnızca Onaylanan Fiilleri Kullan (RD01)

Cmdlet özniteliğinde belirtilen fiil, cmdlet özniteliği tarafından sağlanan tanınan fiil kümesinden Windows PowerShell. Yasaklanmış eş anlamlılardan biri değildir. Cmdlet fiillerini belirtmek için aşağıdaki sabit listelerle tanımlanan sabit dizeleri kullanın:

Onaylanan fiil adları hakkında daha fazla bilgi için bkz. Cmdlet Fiilleri.

Kullanıcıların keşfedilebilir ve beklenen cmdlet adları kümesine ihtiyacı vardır. Kullanıcının bir cmdlet'in ne yaptığına ilişkin hızlı bir değerlendirme yapmak ve sistemin özelliklerini kolayca keşfetmek için uygun fiili kullanın. Örneğin, aşağıdaki komut satırı komutu sistem üzerinde adları "start" ile başlayan tüm komutların listesini alır: get-command start-* . Cmdlet'lerinizi diğer cmdlet'lerden ayırt etmek için cmdlet'lerinizin içinde yer alan adaları kullanın. adı, işlemi gerçekleştirecek kaynağı gösterir. İşlem fiil ile temsil eder.

Cmdlet Adları: Kullanılamayan Karakterler (RD02)

Cmdlet'leri adlarken aşağıdaki özel karakterlerden birini kullanma.

Karakter Name
# sayı işareti
, Virgül
() Parantez
{} Parantez
[] Parantez
& Ampersand
- kısa çizgi Not: Kısa çizgi, fiilden ayrım yapmak için kullanılabilir, ancak tekil veya fiil içinde kullanılamaz.
/ eğik çizgi işareti
\ ters eğik çizgi
$ dolar işareti
^ düzeltme işareti
; Noktalı virgül
: Kolon
" çift tırnak işareti
' tek tırnak işareti
<> açılı ayraçlar
| dikey çubuk
? soru işareti
@ at sign
` geri onay işareti (vurgu vurgusu)
* yıldız işareti
% yüzde işareti
+ artı işareti
= eşittir işareti
~ Til -de

Kullanılamaz Parametre Adları (RD03)

Windows PowerShell tüm cmdlet'lere yönelik ortak bir parametre kümesi ve belirli durumlarda eklenen ek parametreler sağlar. Kendi cmdlet'lerinizi tasarlarken şu adları kullanılamaz: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction ve Verbose. Bu parametreler hakkında daha fazla bilgi için bkz. Ortak Parametre Adları.

Destek Onayı İstekleri (RD04)

Sistemi değiştiren bir işlem gerçekleştiren cmdlet'ler için, onay isteğinde bulunarak System.Management.Automation.Cmdlet.ShouldProcess* yöntemini çağırarak ve özel durumlarda System.Management.Automation.Cmdlet.ShouldContinue* yöntemini çağırmaları gerekir. (System.Management.Automation.Cmdlet.ShouldContinue* yöntemi yalnızca System.Management.Automation.Cmdlet.ShouldProcess* yöntemi çağrıldıktan sonra çağrıl olmalıdır.)

Bu çağrıları yapmak için cmdlet'in Cmdlet özniteliğinin anahtar sözcüğünü ayarerek onay SupportsShouldProcess isteklerini desteklediğini belirtmesi gerekir. Bu özniteliği ayarlama hakkında daha fazla bilgi için bkz. Cmdlet Öznitelik Bildirimi.

Not

cmdlet sınıfının Cmdlet özniteliği, cmdlet'in System.Management.Automation.Cmdlet.ShouldProcess* yöntemine yapılan çağrıları desteklediğini ve cmdlet'in System.Management.Automation.Cmdlet.ShouldProcess* yöntemine çağrıyı başarısız olduğunu gösteriyorsa, kullanıcı sistemi beklenmedik şekilde değiştirebilir.

Herhangi bir sistem değişikliği için System.Management.Automation.Cmdlet.ShouldProcess* yöntemini kullanın. Kullanıcı tercihi ve WhatIf parametresi System.Management.Automation.Cmdlet.ShouldProcess* yöntemini kontrol ediyor. Buna karşılık, System.Management.Automation.Cmdlet.ShouldContinue* çağrısı tehlikeli olabilecek değişiklikler için ek bir denetim gerçekleştirir. Bu yöntem herhangi bir kullanıcı tercihi veya parametresi tarafından WhatIf denetlenz. Cmdlet'iniz System.Management.Automation.Cmdlet.ShouldContinue* yöntemini çağırıyorsa, bu iki yönteme yapılan çağrıları atlayan ve işlemine devam edecek bir parametreye sahip Force olmalıdır. Bu, cmdlet'inizin etkileşimli olmayan betiklerde ve konaklarda kullanımına izin verir.

Cmdlet'leriniz bu çağrıları destekliyorsa, kullanıcı eylemin gerçekten gerçekleştirilip gerçekleştirilecek olmadığını belirler. Örneğin, Stop-Process cmdlet'i System, Winlogon ve Spoolsv işlemleri de dahil olmak üzere bir dizi kritik işlemi durdurmadan önce System.Management.Automation.Cmdlet.ShouldContinue* yöntemini çağırıyor.

Bu yöntemleri destekleme hakkında daha fazla bilgi için bkz. Onay İstenen.

Etkileşimli Oturumlar için Destek Zorlama Parametresi (RD05)

Cmdlet'iniz etkileşimli olarak kullanılıyorsa, istemler veya giriş satırlarını okuma gibi etkileşimli eylemleri geçersiz kılmak için her zaman bir Force parametresi girin. Bu, cmdlet'inizin etkileşimli olmayan betiklerde ve konaklarda kullanımına izin verir. Aşağıdaki yöntemler etkileşimli bir konak tarafından uygulanıyor olabilir.

Belge Çıkış Nesneleri (RD06)

Windows PowerShell işlem hattına yazılan nesneleri kullanır. Kullanıcıların her cmdlet tarafından döndürülen nesnelerden yararlanması için, döndürülen nesneleri belgeleniz ve bu döndürülen nesnelerin üyelerinin ne için kullanıldıklarını belgeleniz gerekir.

Kod Yönergeleri

Cmdlet kodu yazarken aşağıdaki yönergelere uyması gerekir. Sizin durumunuz için geçerli olan bir Kod kılavuzu bulurken benzer yönergeler için Tasarım yönergelerine bakabilirsiniz.

Cmdlet veya PSCmdlet Sınıflarından Türet (RC01)

Bir cmdlet, System.Management.Automation.Cmdlet veya System.Management.Automation.PSCmdlet temel sınıfından türet gerekir. System.Management.Automation.Cmdlet sınıfından türeten cmdlet'ler, çalışma zamanının Windows PowerShell bağımlı değildir. Bunlar doğrudan herhangi bir Microsoft .NET Framework çağrılabilirsiniz. System.Management.Automation.PSCmdlet sınıfından türeten cmdlet'ler, çalışma zamanının Windows PowerShell bağlıdır. Bu nedenle, bir çalışma alanı içinde yürütülür.

Uygulayan tüm cmdlet sınıfları ortak sınıflar olmalıdır. Bu cmdlet sınıfları hakkında daha fazla bilgi için bkz. Cmdlet'e Genel Bakış.

Cmdlet Özniteliğini Belirtme (RC02)

Bir cmdlet'in Windows PowerShell için, .NET Framework sınıfı Cmdlet özniteliğiyle birlikte olmalıdır. Bu öznitelik, cmdlet'in aşağıdaki özelliklerini belirtir.

  • cmdlet'ini tanımlayan fiil ve ad çifti.

  • Birden çok parametre kümesi belirtilirken kullanılan varsayılan parametre kümesi. Varsayılan parametre kümesi, hangi parametre Windows PowerShell belirlemek için yeterli bilgiye sahip değilken kullanılır.

  • Cmdlet'in System.Management.Automation.Cmdlet.ShouldProcess* yöntemine yapılan çağrıları destekleyip desteklemediğini gösterir. Bu yöntem, cmdlet sistemde değişiklik öncesinde kullanıcıya bir onay iletisi görüntüler. Onay isteklerinin nasıl olduğu hakkında daha fazla bilgi için bkz. Onay İsteği.

  • Onay iletisiyle ilişkili eylemin etki düzeyini (veya önem derecelerini) belirtebilirsiniz. Çoğu durumda, varsayılan Orta değeri kullanılmalıdır. Etki düzeyinin kullanıcıya görüntülenen onay isteklerini nasıl etkilediği hakkında daha fazla bilgi için bkz. Onay İstenen.

cmdlet özniteliğinin nasıl bildir olduğu hakkında daha fazla bilgi için bkz. CmdletAttribute Bildirimi.

Giriş İşleme Yöntemini Geçersiz Kılma (RC03)

Cmdlet'in Windows PowerShell için aşağıdaki giriş işleme yöntemlerinden en az birini geçersiz kmalıdır.

System.Management.Automation.Cmdlet.BeginProcessing Bu yöntem bir kez çağrılır ve ön işleme işlevselliği sağlamak için kullanılır.

System.Management.Automation.Cmdlet.ProcessRecord Bu yöntem birden çok kez çağrılır ve kayıta göre kayıt işlevi sağlamak için kullanılır.

System.Management.Automation.Cmdlet.EndProcessing Bu yöntem bir kez çağrılır ve son işleme işlevselliği sağlamak için kullanılır.

OutputType Özniteliğini Belirtme (RC04)

OutputType özniteliği (Windows PowerShell 2.0'da tanıtıldı), cmdlet'inizin işlem hattına döndüren .NET Framework türünü belirtir. Cmdlet'lerinin çıkış türünü belirterek, cmdlet'iniz tarafından döndürülen nesneleri diğer cmdlet'ler tarafından daha fazla keşfedilebilir hale gelirsiniz. Cmdlet sınıfını bu öznitelikle dekore etmek hakkında daha fazla bilgi için bkz. OutputType Öznitelik Bildirimi.

Çıkış Nesnelerinde Tanıtıcıları Tutma (RC05)

Cmdlet'iniz, System.Management.Automation.Cmdlet.WriteObject* yöntemine geçirilen nesnelere hiçbir tanıtıcı tutmaz. Bu nesneler işlem hattında bir sonraki cmdlet'e geçirildi veya bir betik tarafından kullanılıyor. Nesnelerin tanıtıcılarını korursanız, her nesnenin sahibi iki varlık olur ve bu da hatalara neden olur.

Hataları Sağlam Bir Şekilde Ele Al (RC06)

Yönetim ortamı, yönetmekte olduğunu sistemde doğal olarak algılar ve önemli değişiklikler yapar. Bu nedenle, cmdlet'lerinin hataları doğru işlemesi çok önemlidir. Hata kayıtları hakkında daha fazla bilgi için bkz. Windows PowerShell Raporlama.

System.Management.Automation.ErrorRecord nesnesi de kullanıcı için hataları gruplandıran bir hata kategorisi gerektirir. Kullanıcı, kabuk değişkeninin değerini CategoryView olarak ayarerek $ErrorView kategoriye göre hataları görüntülebilirsiniz. Olası kategoriler System.Management.Automation.ErrorCategory numaralandırarak tanımlanır.

  • Bir cmdlet yeni bir iş parçacığı oluşturursa ve bu iş parçacığında çalışan kod iş parçacıklı bir özel durum oluşturursa, Windows PowerShell hatayı yakalamaz ve işlemi sonlandırılır.

  • Bir nesnenin yok etmesinde işlanmamış bir özel duruma neden olan kod varsa Windows PowerShell, hatayı yakalamaz ve işlemi sonlandırılır. Bu durum, bir nesne işlanmamış bir özel duruma neden olan Dispose yöntemlerini çağırsa da oluşur.

Cmdlet'Windows PowerShell Dağıtmak için Bir Modül Kullanma (RC07)

Cmdlet'Windows PowerShell paketle ve dağıtacak bir modül oluşturun. modül desteği 2.0 Windows PowerShell tanıtıldı. Cmdlet sınıflarınızı içeren derlemeleri doğrudan ikili modül dosyaları olarak kullanabilirsiniz (cmdlet'lerinizi test etmek için çok yararlıdır) veya cmdlet derlemelerine başvurulan bir modül bildirimi oluşturabilirsiniz. (Modülleri kullanırken var olan ek bileşen derlemelerini de eklemek için kullanabilirsiniz.) Modüller hakkında daha fazla bilgi için bkz. Modül Windows PowerShell Yazma.

Ayrıca Bkz.

Özellikle Önerilen Geliştirme Yönergeleri

Tavsiye Niteliğinde Geliştirme Yönergeleri

Windows PowerShell Cmdlet’ini Yazma

  • Last updated on