Gerekli Geliştirme Yönergeleri

Cmdlet'lerinizi yazarken aşağıdaki yönergelere uyulmalıdır. Bunlar cmdlet'lerinizi tasarlama yönergelerine ve cmdlet kodunuzu yazmaya yönelik yönergelere ayrılır. Bu yönergeleri izlemezseniz, cmdlet'leriniz başarısız olabilir ve kullanıcılarınız cmdlet'lerinizi kullanırken kötü bir deneyim yaşayabilir.

Bu Konuda

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 uyulmalıdır. Durumunuz için geçerli olan bir Tasarım kılavuzu bulduğunuzda, benzer yönergeler için Kod yönergelerine göz attığınızdan emin olun.

Yalnızca Onaylı Fiilleri Kullan (RD01)

Cmdlet özniteliğinde belirtilen fiil, Windows PowerShell tarafından sağlanan tanınan fiil kümesinden gelmelidir. Yasaklanan eş anlamlılardan biri olmamalıdır. Cmdlet fiillerini belirtmek için aşağıdaki numaralandırmalar tarafından tanımlanan sabit dizeleri kullanın:

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

Kullanıcıların bulunabilir ve beklenen cmdlet adları kümesine ihtiyacı vardır. Kullanıcının bir cmdlet'in ne yaptığını hızlı bir şekilde değerlendirebilmesi ve sistemin özelliklerini kolayca bulabilmesi için uygun fiili kullanın. Örneğin, aşağıdaki komut satırı komutu, sistemdeki adları "Başlat" 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'lerinizdeki isimleri kullanın. İsim, işlemin gerçekleştirileceği kaynağı gösterir. İşlemin kendisi fiiliyle temsil edilir.

Cmdlet Adları: Kullanılamayabilen Karakterler (RD02)

Cmdlet'leri adlandırdığınızda, aşağıdaki özel karakterlerden hiçbirini kullanmayın.

Karakter Name
# sayı işareti
, virgül
( ) Parantez
{ } Parantez
[ ] Parantez
& ampersand
- kısa çizgi
/ eğik çizgi işareti
\ ters eğik çizgi
$ dolar işareti
^ caret
; Noktalı virgül
: colon
" çift tırnak işareti
' tek tırnak işareti
< > açılı ayraçlar
| dikey çubuk
? soru işareti
@ AT İŞARETİ
` geri değer (aksan)
* yıldız işareti
% yüzde işareti
+ artı işareti
= eşittir işareti
~ Til -de

Kullanılamayabilen parametre adları (RD03)

Windows PowerShell, tüm cmdlet'lere ortak bir parametre kümesi ve belirli durumlarda eklenen ek parametreler sağlar. Kendi cmdlet'lerinizi tasarlarken şu adları kullanamazsınız: , , , , , OutBuffer, OutVariable, , WarningAction, WarningVariableWhatIfUseTransactionve .VerboseErrorVariableErrorActionDebugConfirm Bu parametreler hakkında daha fazla bilgi için bkz. Ortak Parametre Adları.

Destek onay istekleri (RD04)

Sistemi değiştiren bir işlem gerçekleştiren cmdlet'ler için, onay istemek için System.Management.Automation.Cmdlet.ShouldProcess* yöntemini çağırmalı ve özel durumlarda System.Management.Automation.Cmdlet.ShouldContinue* yöntemini çağırmalıdır . ( System.Management.Automation.Cmdlet.ShouldContinue* yöntemi yalnızca System.Management.Automation.Cmdlet.ShouldProcess* yöntemi çağrıldıktan sonra çağrılmalıdır.)

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

Note

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 gösteriyorsa ve cmdlet System.Management.Automation.Cmdlet.ShouldProcess* yöntemine çağrı yapamazsa, kullanıcı sistemi beklenmedik bir şekilde değiştirebilir.

Sistem değişiklikleri için System.Management.Automation.Cmdlet.ShouldProcess* yöntemini kullanın. Kullanıcı tercihi WhatIf ve parametresi System.Management.Automation.Cmdlet.ShouldProcess* yöntemini denetler. 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 WhatIf parametresi tarafından denetlenmiyor. Cmdlet'iniz System.Management.Automation.Cmdlet.ShouldContinue* yöntemini çağırırsa, bu iki yönteme yapılan çağrıları atlayan ve işlemle devam eden bir Force parametresi olmalıdır. Bu, cmdlet'inizin etkileşimli olmayan betiklerde ve konaklarda kullanılmasına izin verdiğinden önemlidir.

Cmdlet'leriniz bu çağrıları destekliyorsa, kullanıcı eylemin gerçekleştirilmesi gerekip gerekmediğini belirleyebilir. Örneğin, Stop-Processcmdlet'i System.Management.Automation.Cmdlet.ShouldContinue* yöntemini System, Winlogon ve Spoolsv işlemleri gibi bir dizi kritik işlemi durdurmadan önce çağırır.

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

Etkileşimli oturumlar için Destek Gücü parametresi (RD05)

Cmdlet'iniz etkileşimli olarak kullanılıyorsa, istemler veya girdi satırlarını okuma gibi etkileşimli eylemleri geçersiz kılmak için her zaman bir Force parametresi sağlayın. Bu, cmdlet'inizin etkileşimli olmayan betiklerde ve konaklarda kullanılmasına izin verdiğinden önemlidir. Aşağıdaki yöntemler etkileşimli bir konak tarafından uygulanabilir.

Belge çıktı 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 yararlanabilmesi için, döndürülen nesneleri belgelemelisiniz ve döndürülen nesnelerin üyelerinin ne için kullanıldığını belgelemelisiniz.

Kod yönergeleri

Cmdlet kodu yazılırken aşağıdaki yönergelere uyulmalıdır. Durumunuz için geçerli olan bir Kod kılavuzu bulduğunuzda, benzer yönergeler için Tasarım yönergelerine göz attığınızdan emin olun.

Cmdlet veya PSCmdlet sınıflarından türet (RC01)

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

Uyguladığınız tüm cmdlet sınıfları genel 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 tarafından tanınması için .NET Framework sınıfının Cmdlet özniteliğiyle donatılması gerekir. Bu öznitelik, cmdlet'in aşağıdaki özelliklerini belirtir.

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

  • Birden çok parametre kümesi belirtildiğinde kullanılan varsayılan parametre kümesi. Varsayılan parametre kümesi, Windows PowerShell hangi parametre kümesinin kullanılacağını belirlemek için yeterli bilgiye sahip olmadığında kullanılır.

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

  • Onay iletisiyle ilişkili eylemin etki düzeyini (veya önem derecesini) belirtin. Ç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 İsteme.

cmdlet özniteliğini bildirme hakkında daha fazla bilgi için bkz. CmdletAttribute Bildirimi.

Giriş işleme yöntemini geçersiz kılma (RC03)

Cmdlet'in Windows PowerShell ortamına katılması için aşağıdaki giriş işleme yöntemlerinden en az birini geçersiz kılması gerekir.

OutputType özniteliğini belirtme (RC04)

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

Çıkış nesnelerinin tanıtıcılarını koruma (RC05)

Cmdlet'iniz System.Management.Automation.Cmdlet.WriteObject* yöntemine geçirilen nesnelerin tanıtıcılarını tutmamalıdır. Bu nesneler işlem hattında sonraki cmdlet'e geçirilir veya bir betik tarafından kullanılır. Nesnelerin tanıtıcılarını korursanız, her nesneye iki varlık sahip olur ve bu da hatalara neden olur.

Hataları sağlam bir şekilde işleme (RC06)

Yönetim ortamı, yönetmekte olduğunuz sistemi doğal olarak algılar ve önemli değişiklikler yapar. Bu nedenle, cmdlet'lerin hataları doğru şekilde işlemesi çok önemlidir. Hata kayıtları hakkında daha fazla bilgi için bkz. powershell hata raporlama Windows.

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

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

  • Bir nesnenin yıkıcısında işlenmeyen bir özel duruma neden olan kod varsa, Windows PowerShell hatayı yakalayamaz ve işlemi sonlandırır. Bu durum, bir nesne işlenmeyen bir özel duruma neden olan Dispose yöntemlerini çağırırsa da oluşur.

Cmdlet'lerinizi dağıtmak için Windows PowerShell modülü kullanma (RC07)

Cmdlet'lerinizi paketlemek ve dağıtmak için bir Windows PowerShell modülü oluşturun. Modül desteği Windows PowerShell 2.0'da kullanıma sunulmuştur. Cmdlet sınıflarınızı içeren derlemeleri doğrudan ikili modül dosyaları olarak kullanabilirsiniz (bu, cmdlet'lerinizi test ederken çok yararlıdır) veya cmdlet derlemelerine başvuran bir modül bildirimi oluşturabilirsiniz. Modülleri kullanırken mevcut ek bileşen derlemelerini de ekleyebilirsiniz. Modüller hakkında daha fazla bilgi için bkz. Windows PowerShell Modülü Yazma.

Ayrıca bkz.

  • Last updated on