Kesinlikle Teşvik Edilen Geliştirme Yönergeleri

Bu bölümde, cmdlet'lerinizi yazarken izlemeniz gereken yönergeler açıklanmaktadır. Bunlar, cmdlet'lerinizi tasarlama yönergelerine ve cmdlet kodunuzu yazmaya yönelik yönergelere ayrılır. Bu yönergelerin her senaryo için geçerli olmadığını fark edebilirsiniz. Ancak, bunlar geçerliyse ve bu yönergeleri izlemezseniz, kullanıcılarınız cmdlet'lerinizi kullanırken kötü bir deneyim yaşayabilir.

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.

Cmdlet Adı için Belirli Bir İsim Kullanma (SD01)

Cmdlet adlandırmada kullanılan adların, kullanıcının cmdlet'lerinizi bulabilmesi için çok özel olması gerekir. Ürün adının kısaltılmış bir sürümüyle "sunucu" gibi genel adları önekleyin. Örneğin, bir isim Microsoft SQL Server örneğini çalıştıran bir sunucuya başvuruyorsa, "SQLServer" gibi bir isim kullanın. Belirli isimlerin ve onaylanan fiillerin kısa listesinin birleşimi, cmdlet adları arasında yinelemeyi önlerken kullanıcının işlevselliği hızla bulmasına ve tahmin etmesine olanak tanır.

Kullanıcı deneyimini geliştirmek için, cmdlet adı için seçtiğiniz isim tekil olmalıdır. Örneğin, Get-Process adını Get-Processes yerine kullanın. Bir cmdlet birden fazla öğe üzerinde işlem yapma olasılığı yüksek olsa bile, tüm cmdlet adları için bu kuralı izlemek en iyisidir.

Cmdlet Adları için Pascal Biçimi Kullanma (SD02)

Parametre adları için Pascal Case kullanın. Başka bir deyişle, ilk fiil harfini ve isimde kullanılan tüm terimleri büyük harfle yazın. Örneğin, "Clear-ItemProperty".

Parametre Tasarım Yönergeleri (SD03)

Cmdlet'in çalışması gereken verileri alan parametrelere ve işlemin özelliklerini belirlemek için kullanılan bilgileri gösteren parametrelere ihtiyacı vardır. Örneğin, bir cmdlet'in işlem hattından veri alan bir Name parametresi olabilir ve cmdlet'in işlemini gerçekleştirmeye zorlanabileceğini belirten bir Force parametresi olabilir. Bir cmdlet'in tanımlayabildiği parametre sayısıyla ilgili bir sınır yoktur.

Standart Parametre Adlarını Kullanma

Cmdlet'iniz, kullanıcının belirli bir parametrenin ne anlama geldiğini hızla belirleyebilmesi için standart parametre adlarını kullanmalıdır. Daha belirli bir ad gerekiyorsa standart bir parametre adı kullanın ve ardından diğer ad olarak daha belirli bir ad belirtin. Örneğin, Get-Service cmdlet'in bir genel adı (Name) ve daha belirli bir diğer adı (ServiceName) olan bir parametresi vardır. Her iki terim de parametresini belirtmek için kullanılabilir.

Parametre adları ve veri türleri hakkında daha fazla bilgi için bkz. Cmdlet Parametre Adı ve İşlevsellik Yönergeleri.

Tekil Parametre Adlarını Kullanma

Değeri tek bir öğe olan parametreler için çoğul ad kullanmaktan kaçının. Bu, kullanıcı yalnızca bir öğe içeren bir dizi veya liste sağlayabileceği için dizileri veya listeleri alan parametreleri içerir.

Çoğul parametre adları yalnızca parametrenin değerinin her zaman birden çok öğeli bir değer olduğu durumlarda kullanılmalıdır. Böyle durumlarda, cmdlet birden çok öğe sağlandığını doğrulamalı ve birden çok öğe sağlanmazsa cmdlet kullanıcıya bir uyarı göstermelidir.

Parametre Adları için Pascal Case Kullan

Parametre adları için PascalCase stili kullanın. Başka bir deyişle, parametre adındaki her sözcüğün ilk harfini, adın ilk harfini de içerecek şekilde büyük harfle yazın. Örneğin, parametre adı ErrorAction doğru büyük/küçük harf kullanımını kullanır. Aşağıdaki parametre adları yanlış büyük harf kullanımı kullanır:

  • errorAction
  • erroraction

Seçenekler Listesini Alan Parametreler

Bir dizi seçenek arasından değeri seçilebilen bir parametre oluşturmanın iki yolu vardır.

  • Geçerli değerleri belirten bir numaralandırma türü tanımlayın (veya mevcut bir numaralandırma türünü kullanın). Ardından, bu tür bir parametre oluşturmak için numaralandırma türünü kullanın.

  • ValidateSet özniteliğini parametre bildirimine ekleyin. Bu öznitelik hakkında daha fazla bilgi için bkz . ValidateSet Öznitelik Bildirimi.

Parametreler için Standart Türler Kullanma

Diğer cmdlet'lerle tutarlılık sağlamak için mümkün olduğunca parametreler için standart türleri kullanın. Farklı parametre için kullanılması gereken türler hakkında daha fazla bilgi için bkz. Standart Cmdlet Parametre Adları ve Türleri. Bu konu başlığında, standart parametre grupları için adları ve .NET Framework türlerini açıklayan "etkinlik parametreleri" gibi çeşitli konuların bağlantıları sağlanır.

Strongly-Typed .NET Framework Türlerini Kullanma

Parametreler, daha iyi parametre doğrulaması sağlamak için .NET Framework türleri olarak tanımlanmalıdır. Örneğin, bir değer kümesinden bir değerle kısıtlanmış parametreler bir numaralandırma türü olarak tanımlanmalıdır. Tekdüzen Kaynak Tanımlayıcısı (URI) değerini desteklemek için parametresini System.Uri türü olarak tanımlayın. Serbest biçimli metin özellikleri dışında tümü için temel dize parametrelerinden kaçının.

Tutarlı Parametre Türlerini Kullanma

Aynı parametre birden çok cmdlet tarafından kullanıldığında, her zaman aynı parametre türünü kullanın. Örneğin, parametre bir cmdlet için Process türüyse, başka bir cmdlet'in parametresini ProcessSystem.Uint16 türü haline getirmeyin.

True ve False Değerlerini Alan Parametreler

Parametreniz yalnızca true ve falsealıyorsa, parametresini System.Management.Automation.SwitchParameter türü olarak tanımlayın. Bir [switch] parametre, bir komutta belirtildiğinde olarak true değerlendirilir. Parametre bir komuta dahil değilse, Windows PowerShell parametresinin değerini false olarak değerlendirir. Boole parametrelerini tanımlama.

Parametrenizin $true, $false ve "belirtilmemiş" gibi 3 farklı değeri ayırt etmesi gerekiyorsa, Null değeri atanabilir<bool> türünde bir parametre tanımlayın. 3. ve "belirtilmemiş" bir değere ihtiyaç, genellikle cmdlet bir nesnenin Boole özelliğini değiştirebildiğinde ortaya çıkar. Bu durumda "belirtilmemiş" özelliğin geçerli değerini değiştirmemek anlamına gelir.

Parametreler için Destek Dizileri

Sık sık, kullanıcıların aynı işlemi birden çok bağımsız değişkene karşı gerçekleştirmesi gerekir. Bu kullanıcılar için, cmdlet'in parametre girişi olarak bir diziyi kabul etmesi gerekir, böylece kullanıcı bağımsız değişkenleri parametreye Windows PowerShell değişkeni olarak geçirebilir. Örneğin, Get-Process cmdlet'i alınacak işlemlerin adlarını tanımlayan dizeler için bir dizi kullanır.

PassThru Parametresini Destekleme

Varsayılan olarak, Stop-Process cmdlet'i gibi sistemi değiştiren birçok cmdlet, nesneler için "havuz" işlevi görür ve sonuç döndürmez. Bu cmdlet'ler, cmdlet'in bir nesne döndürmesini zorlamak amacıyla PassThru parametresini eklemelidir. parametresi belirtildiğinde PassThru , cmdlet System.Management.Automation.Cmdlet.WriteObject yöntemine bir çağrı kullanarak bir nesne döndürür. Örneğin, aşağıdaki komut Calc ' yi (CalculatorApp.exe) durdurur ve sonuçta elde edilen işlemi işlem hattına geçirir.

Stop-Process -Name CalculatorApp -PassThru

Çoğu durumda, Ekle, Ayarla ve Yeni cmdlet'ler bir PassThru parametreyi desteklemelidir.

Parametre Kümelerini Destekleme

Cmdlet tek bir amaca yöneliktir. Ancak, işlemi veya işlem hedefini tanımlamak için genellikle birden fazla yol vardır. Örneğin, bir işlem adına, tanımlayıcısına veya bir işlem nesnesine göre tanımlanabilir. Cmdlet, hedeflerinin tüm makul temsillerini desteklemelidir. Normalde, cmdlet birlikte çalışan parametre kümelerini (parametre kümeleri olarak adlandırılır) belirterek bu gereksinimi karşılar. Tek bir parametre, herhangi bir sayıda parametre kümesine ait olabilir. Parametre kümeleri hakkında daha fazla bilgi için bkz. Cmdlet Parametre Kümeleri.

Parametre kümeleri belirttiğinizde, kümesindeki tek bir parametreyi ValueFromPipeline olarak ayarlayın. Parameter özniteliğini bildirme hakkında daha fazla bilgi için bkz. ParameterAttribute Bildirimi.

Parametre kümeleri kullanıldığında, varsayılan parametre kümesi Cmdlet özniteliği tarafından tanımlanır. Varsayılan parametre kümesi, etkileşimli Windows PowerShell oturumunda kullanılma olasılığı en yüksek olan parametreleri içermelidir. Cmdlet özniteliğini bildirme hakkında daha fazla bilgi için bkz. CmdletAttribute Bildirimi.

Kullanıcıya Geri Bildirim Sağlama (SD04)

Kullanıcıya geri bildirim sağlamak için bu bölümdeki yönergeleri kullanın. Bu geri bildirim, kullanıcının sistemde gerçekleşenlerin farkında olmasını ve daha iyi yönetim kararları alabilmesini sağlar.

Windows PowerShell çalışma zamanı, kullanıcının bir tercih değişkeni ayarlayarak Write yöntemine yapılan her çağrıdan çıkışın nasıl işleneceğini belirtmesine olanak tanır. Kullanıcı, sistemin bilgi görüntüleyip görüntülemeyeceğini belirleyen bir değişken ve daha fazla işlem gerçekleştirmeden önce sistemin kullanıcıyı sorgulaması gerekip gerekmediğini belirleyen bir değişken de dahil olmak üzere çeşitli tercih değişkenleri ayarlayabilir.

WriteWarning, WriteVerbose ve WriteDebug Yöntemlerini Destekleme

Cmdlet istenmeyen bir sonuca sahip olabilecek bir işlem gerçekleştirmek üzereyken cmdlet System.Management.Automation.Cmdlet.WriteWarning yöntemini çağırmalıdır. Örneğin, bir cmdlet, salt okunur bir dosyanın üzerine yazmak üzereyse bu yöntemi çağırmalıdır.

Bir cmdlet, kullanıcı cmdlet'in ne yaptığı hakkında biraz ayrıntı gerektirdiğinde System.Management.Automation.Cmdlet.WriteVerbose yöntemini çağırmalıdır. Örneğin, cmdlet yazarı cmdlet'in ne yaptığı hakkında daha fazla bilgi gerektirebilecek senaryolar olduğunu düşünüyorsa, cmdlet bu bilgileri çağırmalıdır.

Bir geliştirici veya ürün destek mühendisinin cmdlet işlemini neyin bozdığını anlaması gerektiğinde cmdlet System.Management.Automation.Cmdlet.WriteDebug yöntemini çağırmalıdır. Cmdlet'in System.Management.Automation.Cmdlet.WriteDebug yöntemini System.Management.Automation.Cmdlet.WriteVerbose yöntemini çağıran kodda çağırması gerekli değildir çünkü Debug parametre her iki bilgi kümesini de sunar.

Uzun Süren İşlemler için WriteProgress Desteği

Tamamlanması uzun süren ve arka planda çalıştırılamayan cmdlet işlemleri , System.Management.Automation.Cmdlet.WriteProgress yöntemine yapılan düzenli çağrılar aracılığıyla ilerleme raporlamayı desteklemelidir.

Ana Bilgisayar Arayüzlerini Kullanma

Bazen, bir cmdlet'in System.Management.Automation.Cmdlet sınıfı tarafından desteklenen çeşitli Write veya Should yöntemlerini kullanmak yerine kullanıcıyla doğrudan iletişim kurması gerekir. Bu durumda, cmdlet System.Management.Automation.PSCmdlet sınıfından türetilmelidir ve System.Management.Automation.PSCmdlet.Host* özelliğini kullanmalıdır. Bu özellik PromptForChoice, Prompt ve WriteLine/ReadLine türleri de dahil olmak üzere farklı iletişim türü düzeylerini destekler. En spesifik düzeyde, tek tek anahtarları okuyabilmenin ve yazabilmenin ve arabelleklerle ilgilenmenin yollarını da sağlar.

Cmdlet özellikle grafik kullanıcı arabirimi (GUI) oluşturmak üzere tasarlanmamışsa System.Management.Automation.PSCmdlet.Host* özelliğini kullanarak konağı atlamamalıdır. GUI oluşturmak için tasarlanmış bir cmdlet örneği, Out-GridView cmdlet'idir.

Uyarı

Cmdlet'ler System.Console API'sini kullanmamalıdır.

Cmdlet Yardım Dosyası Oluşturma (SD05)

Her cmdlet derlemesi için, cmdlet hakkında bilgi içeren bir Help.xml dosyası oluşturun. Bu bilgiler cmdlet'in açıklamasını, cmdlet'in parametrelerinin açıklamalarını, cmdlet kullanımı örneklerini ve daha fazlasını içerir.

Kod Yönergeleri

Cmdlet'lerinizi ve diğer cmdlet'lerinizi kullanma arasında tutarlı bir kullanıcı deneyimi sağlamak için cmdlet'leri kodlarken aşağıdaki yönergeler izlenmelidir. 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.

Kodlama Parametreleri (SC01)

Parameter özniteliğiyle dekore edilmiş cmdlet sınıfının ortak özelliğini bildirerek bir parametre tanımlayın. Parametrelerin cmdlet için türetilmiş .NET Framework sınıfının statik üyeleri olması gerekmez. Parametre özniteliğini bildirme hakkında daha fazla bilgi için bkz. Parametre Özniteliği Bildirimi.

Windows PowerShell Yollarını Destekle

Windows PowerShell yolu, ad alanlarına erişimi normalleştirme mekanizmasıdır. cmdlet'indeki bir parametreye Windows bir PowerShell yolu atadığınızda, kullanıcı belirli bir yola kısayol işlevi gören özel bir "sürücü" tanımlayabilir. Kullanıcı böyle bir sürücü belirttiğinde, Kayıt Defteri'ndeki veriler gibi depolanan veriler tutarlı bir şekilde kullanılabilir.

Cmdlet'iniz kullanıcının bir dosya veya veri kaynağı belirtmesine izin veriyorsa System.String türünde bir parametre tanımlamalıdır. Birden fazla sürücü destekleniyorsa, tür bir dizi olmalıdır. parametresinin Pathadı, diğer adıyla PSPatholmalıdır. Parametre Path ayrıca joker karakterleri desteklemelidir. Joker karakterler için destek gerekmiyorsa bir LiteralPath parametre tanımlayın.

Cmdlet'in okuduğu veya yazdığı verilerin bir dosya olması gerekiyorsa, cmdlet Windows PowerShell yol girişini kabul etmelidir ve cmdlet Windows PowerShell yollarını dosya sisteminin tanıdığı yollara çevirmek için System.Management.Automation.SessionState.Path özelliğini kullanmalıdır. Belirli mekanizmalar aşağıdaki yöntemleri içerir:

Cmdlet'in okuduğu veya yazdığı veriler dosya yerine yalnızca bir dize kümesiyse, cmdlet'in okuma ve yazma için sağlayıcı içerik bilgilerini (Content üye) kullanması gerekir. Bu bilgiler System.Management.Automation.Provider.CmdletProvider.InvokeProvider özelliğinden alınır. Bu mekanizmalar, diğer veri depolarının veri okuma ve yazma işlemlerine katılmasını sağlar.

Joker Karakterleri Destekleme

Bir cmdlet'in, mümkünse joker karakterleri desteklemesi gerekir. Joker karakter desteği, cmdlet'in çeşitli yerlerinde (özellikle bir parametre, bir nesne kümesinden bir nesneyi tanımlamak amacıyla bir dize aldığında) sağlanır. Örneğin, Stop-Proc alınan örnek cmdlet, işlem adlarını temsil eden dizeleri işlemek için bir Name parametre tanımlar. Bu parametre, kullanıcının durdurulacak işlemleri kolayca belirtebilmesi için joker karakterleri destekler.

Joker karakterler için destek sağlandığında, cmdlet işlemi genellikle bir dizi üretir. Bazen, bir diziyi desteklemek mantıklı değildir çünkü kullanıcı aynı anda yalnızca tek bir öğe kullanabilir. Örneğin, Set-Location cmdlet'inin bir diziyi desteklemesi gerekmez çünkü kullanıcı yalnızca tek bir konum ayarlar. Bu örnekte, cmdlet hala joker karakterleri destekler, ancak çözümlemeyi tek bir konuma zorlar.

Joker karakter desenleri hakkında daha fazla bilgi için bkz. Cmdlet Parametrelerinde Joker Karakterleri Destekleme.

Nesneleri Tanımlama

Bu bölüm, cmdlet'ler için nesneleri tanımlamaya ve var olan nesneleri genişletmeye yönelik yönergeler içerir.

Standart Üyeleri Tanımlama

Özel bir Types.ps1xml dosyasında nesne türünü genişletmek için standart üyeler tanımlayın (şablon olarak Windows PowerShell Types.ps1xml dosyasını kullanın). Standart üyeler PSStandardMembers adlı bir düğüm tarafından tanımlanır. Bu tanımlar, diğer cmdlet'lerin ve Windows PowerShell çalışma zamanının nesnenizle tutarlı bir şekilde çalışmasını sağlar.

Parametre Olarak Kullanılacak ObjectMember'ları Tanımlama

Bir cmdlet için bir nesne tasarlarsanız, üyelerinin onu kullanacak cmdlet'lerin parametreleriyle doğrudan eşlediğinden emin olun. Bu eşleme, nesnenin işlem hattına kolayca gönderilmesini ve bir cmdlet'ten diğerine geçirilmesini sağlar.

Cmdlet'ler tarafından döndürülen önceden var olan .NET Framework nesneleri, betik geliştiricisi veya kullanıcı tarafından gereken bazı önemli veya kullanışlı üyelerin sık sık eksik olmasına sahiptir. Bu eksik üyeler özellikle görüntüleme ve nesnenin işlem hattına doğru şekilde geçirilebilmesi için doğru üye adlarını oluşturmak için önemli olabilir. Bu gerekli üyeleri belgeleye özel bir Types.ps1xml dosyası oluşturun. Bu dosyayı oluştururken aşağıdaki adlandırma kuralını öneririz: <Your_Product_Name>. Types.ps1xml.

Örneğin, bir Mode dosyanın özniteliklerini daha net görüntülemek için System.IO.FileInfo türüne bir betik özelliği ekleyebilirsiniz. Ayrıca, o özellik adının tutarlı bir şekilde kullanılmasına izin vermek için System.Array türüne bir Count diğer ad özelliği ekleyebilirsiniz (yerine Length).

IComparable Arabirimini Gerçekleştirme

Tüm çıkış nesnelerine System.IComparable arabirimi uygulayın. Bu, çıkış nesnelerinin çeşitli sıralama ve analiz cmdlet'lerine kolayca yöneltilmesine olanak tanır.

Görüntü Bilgilerini Güncelleştir

Nesnenin görüntüsü beklenen sonuçları sağlamıyorsa, bu nesne için özel bir <YourProductName>.Format.ps1xml dosyası oluşturun.

İyi Tanımlanmış İşlem Hattı Girişini (SC02) Destekleme

Boru Hattının Ortası için Uygula

İşlem hattının ortasından çağrılacağını varsayarak bir cmdlet uygulayın (yani, diğer cmdlet'ler onun girişini sağlar veya çıkışını tüketir). Örneğin, veri oluşturduğu için Get-Process cmdlet'in yalnızca bir işlem hattındaki ilk cmdlet olarak kullanıldığını varsayabilirsiniz. Ancak, bu cmdlet bir işlem hattının ortası için tasarlandığından, bu cmdlet işlem hattındaki önceki cmdlet'lerin veya verilerin alınacak işlemleri belirtmesine izin verir.

Boru Hattından Destek Girişi

Bir cmdlet için her parametre kümesinde, işlem hattından girişi destekleyen en az bir parametre ekleyin. İşlem hattı girişi desteği, kullanıcının verileri veya nesneleri almasını, bunları doğru parametre kümesine göndermesini ve sonuçları doğrudan bir cmdlet'e geçirmesini sağlar.

Parametre özniteliği, bildiriminde anahtar sözcük veya ValueFromPipeline anahtar sözcük özniteliği içeriyorsa ya da her iki anahtar sözcüğü içeriyorsa, parametre işlem hattından girişi kabul eder. Bir parametre kümesindeki parametrelerin hiçbiri ValueFromPipeline veya ValueFromPipelineByPropertyName anahtar sözcüklerini desteklemiyorsa, herhangi bir işlem hattı girişini yoksayacağından, cmdlet başka bir cmdlet'in arkasına anlamlı bir şekilde yerleştirilemez.

ProcessRecord Yöntemini Destekleme

İşlem hattında önceki cmdlet'ten tüm kayıtları kabul etmek için cmdlet'inizin System.Management.Automation.Cmdlet.ProcessRecord yöntemini uygulaması gerekir. Windows PowerShell, cmdlet'inize gönderilen her kayıt için bu yöntemi birden çok kez çağırır.

İşlem Hattına Tek Kayıt Yazma (SC03)

Bir cmdlet nesneleri döndürdüğünde, cmdlet'in nesneleri oluşturuldukları anda yazması gerekir. Cmdlet, bunları birleştirilmiş bir diziye arabellek oluşturmak için geçici olarak tutmamalıdır. Nesneleri giriş olarak alan cmdlet'ler daha sonra çıkış nesnelerini gecikmeden işleyebilir, görüntüleyebilir veya hem işleyip hem de görüntüleyebilir. Çıkış nesnelerini tek tek oluşturan bir cmdlet , System.Management.Automation.Cmdlet.WriteObject yöntemini çağırmalıdır. Çıktı nesnelerini toplu olarak oluşturan bir cmdlet (örneğin, temel alınan bir API bir çıkış nesneleri dizisi döndürdüğünden) system.management.automation.cmdlet.WriteObject yöntemini çağırmalıdır ve ikinci parametresi olarak trueayarlanmalıdır.

Cmdlet'leri Case-Insensitive ve Case-Preserving Yapma (SC04)

Windows PowerShell varsayılan olarak büyük/küçük harf duyarlılığı yoktur. Ancak, önceden var olan birçok sistemle çalıştığından Windows PowerShell, kullanım kolaylığı ve uyumluluk açısından büyük/küçük harf korumasını sağlar. Başka bir deyişle, eğer bir karakter büyük harflerle sağlanırsa, Windows PowerShell onu büyük harflerle tutar. Sistemlerin düzgün çalışması için bir cmdlet'in bu kuralı izlemesi gerekir. Mümkünse büyük/küçük harfe duyarsız bir şekilde çalışmalıdır. Ancak, daha sonra bir komutta veya işlem hattında gerçekleşen cmdlet'ler için özgün büyük/küçük harf korunmalıdır.

Ayrıca Bkz.

Gerekli Geliştirme Yönergeleri

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

Windows PowerShell Cmdlet'ini yazma

  • Last updated on