Danışmanlık Geliştirme Yönergeleri

Bu bölümde, iyi geliştirme ve kullanıcı deneyimleri sağlamak için göz önünde bulundurmanız gereken yönergeler açıklanmaktadır. Bazen uygulanabilirler, bazen de uygulanamayabilirler.

Tasarım Yönergeleri

Cmdlet'ler tasarlarken aşağıdaki yönergeler dikkate alınmalı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.

InputObject Parametresini Destekleme (AD01)

Windows PowerShell doğrudan Microsoft .NET Framework nesneleriyle çalıştığından, genellikle kullanıcının belirli bir işlemi gerçekleştirmesi için gereken türle tam olarak eşleşen bir .NET Framework nesnesi kullanılabilir. InputObject , giriş gibi bir nesne alan parametrenin standart adıdır. Örneğin, Stop-Proc örnek cmdlet işlem hattından girişi destekleyen İşlem türünde bir InputObject parametre tanımlar. Kullanıcı bir dizi işlem nesnesi alabilir, durdurulacak nesneleri tam olarak seçmek için bunları işleyebilir ve ardından bunları doğrudan cmdlet'e Stop-Proc geçirebilir.

Force Parametresini Destekleme (AD02)

Bazen bir cmdlet'in kullanıcıyı istenen işlemi gerçekleştirmesine karşı koruması gerekir. Böyle bir cmdlet, kullanıcının işlemi gerçekleştirme izinleri varsa bu korumayı geçersiz kılması için force parametresini desteklemelidir.

Örneğin, Remove-Item cmdlet'i normalde salt okunur bir dosyayı kaldırmaz. Ancak, bu cmdlet bir Zorla parametresini destekler, böylece kullanıcı salt okunur bir dosyanın kaldırılmasını zorlayabilir. Kullanıcının salt okunur özniteliğini değiştirme izni zaten varsa ve kullanıcı dosyayı kaldırırsa Force parametresinin kullanılması işlemi basitleştirir. Ancak, kullanıcının dosyayı kaldırma izni yoksa Force parametresinin hiçbir etkisi olmaz.

Windows PowerShell Aracılığıyla Kimlik Bilgilerini İşleme (AD03)

Cmdlet, kimlik bilgilerini temsil eden bir Credential parametre tanımlamalıdır. Bu parametre System.Management.Automation.PSCredential türünde olmalı ve Credential öznitelik bildirimi kullanılarak tanımlanmalıdır. Bu destek, kullanıcı adını, parolayı veya tam kimlik bilgisi doğrudan sağlanmıyorsa her ikisi için de kullanıcıdan otomatik olarak ister. Credential özniteliği hakkında daha fazla bilgi için bkz. Kimlik Bilgisi Öznitelik Bildirimi.

Kodlama Parametrelerini Destekleme (AD04)

Cmdlet'iniz, dosya sistemindeki bir dosyaya yazma veya dosyadan okuma gibi ikili bir formdan metin okur veya yazarsa, cmdlet'inizin metnin ikili biçimde nasıl kodlandığını belirten Kodlama parametresine sahip olması gerekir.

Test Cmdlet'leri Boole Değeri Döndürmelidir (AD05)

Kaynaklarına göre test gerçekleştiren cmdlet'ler, koşullu ifadelerde kullanılabilmesi için işlem hattına bir System.Boole türü döndürmelidir.

Kod Yönergeleri

Cmdlet kodu yazarken aşağıdaki yönergeler dikkate alınmalıdır. Durumunuz için geçerli olan bir kılavuz bulduğunuzda, benzer yönergeler için Tasarım yönergelerine göz attığınızdan emin olun.

Cmdlet Sınıf Adlandırma Kurallarını (AC01) izleyin

Standart adlandırma kurallarını izleyerek cmdlet'lerinizi daha bulunabilir hale getirir ve kullanıcının cmdlet'lerin tam olarak ne yaptığını anlamasına yardımcı olursunuz. Cmdlet'ler genel türler olduğundan bu uygulama özellikle Windows PowerShell kullanan diğer geliştiriciler için önemlidir.

Doğru Ad Alanında Cmdlet Tanımlama

Normalde cmdlet'in çalıştığı ürünü temsil eden ad alanına eklenen .Commands bir .NET Framework ad alanında cmdlet sınıfını tanımlarsınız. Örneğin, Windows PowerShell'e dahil edilen cmdlet'ler ad alanında Microsoft.PowerShell.Commands tanımlanır.

Cmdlet Sınıfını Cmdlet Adıyla Eşleşecek Şekilde Adlandırın

Bir cmdlet uygulayan .NET Framework sınıfını adlandırdığınızda, ve <Verb><Noun>Command yer tutucularını cmdlet adı için kullanılan fiil ve isim ile değiştirdiğiniz <Verb> sınıfını <Noun>adlandırın. Örneğin, Get-Process cmdlet'i adlı GetProcessCommandbir sınıf tarafından uygulanır.

İşlem Hattı Girişi Yoksa BeginProcessing Yöntemini Geçersiz Kıl (AC02)

Cmdlet'iniz işlem hattından girişi kabul etmiyorsa, işlem System.Management.Automation.Cmdlet.BeginProcessing yönteminde uygulanmalıdır. Bu yöntemin kullanılması, Windows PowerShell'in cmdlet'ler arasında sıralamayı korumasını sağlar. İşlem hattındaki ilk cmdlet, işlem hattındaki kalan cmdlet'ler işlemeye başlamadan önce her zaman nesnelerini döndürür.

Durdurma İsteklerini İşlemek için StopProcessing Yöntemini (AC03) Geçersiz Kıl

Cmdlet'inizin durdurma sinyalini işleyebilmesi için System.Management.Automation.Cmdlet.StopProcessing yöntemini geçersiz kılın. Bazı cmdlet'lerin işlemlerini tamamlaması uzun zaman alır ve cmdlet'in uzun süre çalışan RPC çağrılarında iş parçacığını engellemesi gibi Windows PowerShell çalışma zamanı çağrıları arasında uzun bir süre geçmesine izin verir. Bu, System.Management.Automation.Cmdlet.WriteObject yöntemine, System.Management.Automation.Cmdlet.WriteError yöntemine ve tamamlanması uzun sürebilecek diğer geri bildirim mekanizmalarına çağrılar yapacak cmdlet'leri içerir. Bu durumlarda kullanıcının bu cmdlet'lere bir durdurma sinyali göndermesi gerekebilir.

IDisposable Arabirimini Uygulama (AC04)

Cmdlet'inizde System.Management.Automation.Cmdlet.ProcessRecord yöntemi tarafından atılmayan (işlem hattına yazılan) nesneler varsa, cmdlet'iniz ek nesnenin atılması gerektirebilir. Örneğin, cmdlet'iniz System.Management.Automation.Cmdlet.BeginProcessing yönteminde bir dosya tanıtıcısı açarsa ve tanıtıcıyı System.Management.Automation.Cmdlet.ProcessRecord yöntemi tarafından kullanılmak üzere açık tutarsa, bu tanıtıcının işlem sonunda kapatılması gerekir.

Windows PowerShell çalışma zamanı her zaman System.Management.Automation.Cmdlet.EndProcessing yöntemini çağırmaz . Örneğin, cmdlet işlemi sırasında iptal edilirse veya cmdlet'in herhangi bir bölümünde sonlandırma hatası oluşursa System.Management.Automation.Cmdlet.EndProcessing yöntemi çağrılamayabilir. Bu nedenle, nesne temizleme gerektiren bir cmdlet için .NET Framework sınıfı, Windows PowerShell çalışma zamanının işlem sonunda hem System.Management.Automation.Cmdlet.EndProcessing hem de System.IDisposable.Dispose* yöntemlerini çağırabilmesi için sonlandırıcı da dahil olmak üzere tam System.IDisposable arabirim desenini uygulamalıdır.

Serileştirme dostu Parametre Türlerini Kullanma (AC05)

Cmdlet'inizi uzak bilgisayarlarda çalıştırmayı desteklemek için, istemci bilgisayarda seri hale getirilebilen ve ardından sunucu bilgisayarda yeniden doldurulabilen türleri kullanın. Aşağıdaki türler serileştirme dostudur.

İlkel türler:

• Bayt, SByte, Ondalık, Tek, Çift, Int16, Int32, Int64, Uint16, UInt32 ve UInt64.
• Boole, Guid, Byte[], TimeSpan, DateTime, Uri ve Version.
• Char, String, XmlDocument.

Yerleşik yeniden doldurulan türler:

• PSPrimitiveDictionary
• SwitchParameter
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Diğer türler:

• Güvenli Dize
• Kapsayıcılar (yukarıdaki türdeki listeler ve sözlükler)

Hassas Veriler için SecureString kullanma (AC06)

Hassas verileri işlerken her zaman System.Security.SecureString veri türünü kullanın. Bu, parametrelere işlem hattı girişi ve işlem hattına hassas veriler döndürmeyi içerebilir.

.NET, yeni geliştirme için SecureString'in kullanılmasını önerse de PowerShell geriye dönük uyumluluk için SecureString sınıfını desteklemeye devam eder. SecureString kullanmak, düz metin dizesi kullanmaktan daha güvenlidir. PowerShell, içeriği yanlışlıkla konsola veya günlüklere göstermemek için SecureString türüne dayanır. SecureString'i dikkatli bir şekilde kullanın çünkü düz metin dizesine kolayca dönüştürülebilir. SecureString kullanma hakkında tam bir tartışma için System.Security.SecureString sınıfı belgelerine bakın.

Ayrıca Bkz.

Gerekli Geliştirme Yönergeleri

Kesinlikle Teşvik Edilen Geliştirme Yönergeleri

Windows PowerShell Cmdlet'i yazma