Özellikle Önerilen Geliştirme Yönergeleri

Bu bölümde, cmdlet 'lerinizi yazarken izlemeniz gereken kılavuzlar açıklanmaktadır. Cmdlet kodunuzu yazmak için cmdlet 'leri ve yönergeleri tasarlamaya yönelik yönergelere ayrılırlar. Bu yönergelerin her senaryo için geçerli olduğunu fark edebilirsiniz. Ancak, bu kurallar uygulanamazlar ve bu yönergeleri izlemeden, kullanıcılarınız cmdlet 'lerinizi kullandıklarında kötü bir deneyim yaşayabilir.

Tasarım Yönergeleri

Cmdlet 'lerinizi ve diğer cmdlet 'leri kullanma arasında tutarlı bir kullanıcı deneyimi sağlamak için cmdlet 'leri tasarlarken aşağıdaki yönergelerin izlenmesi gerekir. Durumunuza uygun bir tasarım kılavuzu bulduğunuzda, benzer yönergeler için kod yönergelerine baktığınızdan emin olun.

Bir cmdlet adı için belirli bir ad kullanın (SD01)

Cmdlet adlandırmasında kullanılan isimler, 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 isimler ön eki. örneğin, bir ad Microsoft SQL Server örneğini çalıştıran bir sunucuya başvuruyorsa, "SQLServer" gibi bir ad kullanın. Belirli adların ve onaylanan fiillerin kısa listesinin birleşimi, kullanıcının cmdlet adları arasında çoğaltmayı önleyerek işlevselliği hızlı bir şekilde bulmasını ve tahmin kurmasını sağlar.

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

Cmdlet adları için Pascal case kullanın (SD02)

Parametre adları için Pascal case kullanın. Diğer bir deyişle, Fiilin ilk harfini ve ad 'de kullanılan tüm koşulları büyük harfle yapın. Örneğin, "Clear-ItemProperty".

Parametre tasarım yönergeleri (SD03)

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

Standart parametre adlarını kullan

Cmdlet 'inizin belirli bir parametrenin ne anlama geldiğini hızla belirleyebilmesi için standart parametre adlarını kullanması gerekir. Daha belirli bir ad gerekliyse, standart bir parametre adı kullanın ve daha sonra diğer ad olarak daha özel bir ad belirtin. Örneğin, cmdlet 'in Get-Service genel adı ( Name ) ve daha belirli bir diğer ad () içeren bir parametresi vardır ServiceName . 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 Işlevsellik yönergeleri.

Tekil parametre adlarını kullanın

Değeri tek bir öğe olan parametreler için çoğul adlar kullanmaktan kaçının. Bu, Kullanıcı yalnızca bir öğe içeren bir dizi veya liste sağlayabileceğinden, diziler veya listeler alan parametreler içerir.

Çoğul parametre adları yalnızca parametre değerinin her zaman birden çok öğe değeri olduğu durumlarda kullanılmalıdır. Bu durumlarda, cmdlet birden çok öğe olduğunu doğrulamalıdır ve birden çok öğe sağlanmazsa cmdlet 'in kullanıcıya bir uyarı görüntülemesi gerektiğini doğrulaması gerekir.

Parametre adları için Pascal case kullanın

Parametre adları için Pascal case kullanın. Diğer bir deyişle, adın ilk harfi dahil olmak üzere parametre adındaki her sözcüğün ilk harfini büyük harfle yapın. Örneğin, parametre adı ErrorAction doğru büyük harfleri kullanır. Aşağıdaki parametre adları büyük/küçük harf yanlış kullanır:

• errorAction
• erroraction

Seçeneklerin bir listesini alan parametreler

Bir seçenek kümesinden değeri seçilebili bir parametre oluşturmanın iki yolu vardır.

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

• Validateset özniteliğini parametre bildirimine ekleyin. Bu öznitelik hakkında daha fazla bilgi için bkz. Validateset Attribute bildirimi.

Parametreler için standart türleri kullan

Diğer cmdlet 'lerle tutarlılığı sağlamak için, mümkün olduğu durumlarda 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, "etkinlik parametreleri" gibi standart parametre grupları için adları ve .NET Framework türlerini tanımlayan çeşitli konuların bağlantılarını sağlar.

Strongly-Typed .NET Framework türlerini kullan

parametrelerin daha iyi parametre doğrulaması sağlaması için .NET Framework türleri olarak tanımlanması gerekir. Örneğin, bir değer kümesinden bir değerle kısıtlanan parametreler, bir sabit listesi türü olarak tanımlanmalıdır. Tekdüzen Kaynak tanımlayıcısı (URI) değerini desteklemek için, parametresini bir System. URI türü olarak tanımlayın. Tüm ancak serbest biçimli metin özellikleri için temel dize parametrelerinden kaçının.

Tutarlı parametre türlerini kullan

Aynı parametre birden çok cmdlet tarafından kullanıldığında, her zaman aynı parametre türünü kullanın. Örneğin, Process parametresi bir cmdlet Için System. Int16 türünde ise, Process başka bir cmdlet için parametresini bir System. uint16 türü olarak yapmayın.

Doğru ve yanlış alan parametreler

Yalnızca parametresi alırsa true false , parametresini System. Management. Automation. switchparametertürü olarak tanımlayın. Bir switch parametresi, true bir komutta belirtildiği gibi değerlendirilir. parametre bir komuta dahil değilse, Windows PowerShell parametrenin değerini kabul eder false . Boole parametreleri tanımlamayın.

Parametrinizdeki 3 değer arasında ayrım yapması gerekiyorsa: $true, $false ve "Unspecified", ardından null değer atanabilir türünde bir parametre tanımlayın <bool> . Bir 3., "belirtilmemiş" değeri gereksinimi genellikle cmdlet bir nesnenin Boolean özelliğini değiştiremediğinde oluşur. Bu durumda "belirtilmemiş" özelliği, özelliğin geçerli değerini değiştirmemelidir.

Parametreler için destek dizileri

Genellikle, kullanıcıların birden çok bağımsız değişken için aynı işlemi gerçekleştirmesi gerekir. bu kullanıcılar için bir cmdlet parametre girişi olarak bir diziyi kabul etmelidir, böylece bir kullanıcı bağımsız değişkenleri bir Windows PowerShell değişkeni olarak parametreye geçirebilir. Örneğin, Get-Process cmdlet 'i, alınacak işlemlerin adlarını belirleyen dizeler için bir dizi kullanır.

Geçiş parametresini destekleme

Varsayılan olarak, Durdur-Process cmdlet 'i gibi sistemi değiştiren birçok cmdlet, nesneler için "Havuzlar" olarak davranır ve sonuç döndürmez. Bu cmdlet, PassThru cmdlet 'in bir nesne döndürmesini zorlamak için parametresini uygulamalıdır. PassThruParametresi belirtildiğinde, 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 işlemini sonlandırır ve sonuç sürecini işlem hattına geçirir.

Stop-Process calc -passthru

Çoğu durumda, Add, set ve New cmdlet 'leri bir PassThru parametreyi desteklemelidir.

Destek parametre kümeleri

Bir cmdlet, tek bir amaca ulaşmak üzere tasarlanmıştır. Ancak, işlemi veya işlem hedefini tanımlamanın birden çok yolu vardır. Örneğin, bir işlem adına, tanımlayıcısına veya bir işlem nesnesine göre tanımlanabilir. Cmdlet 'inin, hedeflerinin tüm makul gösterimlerini desteklemesi gerekir. Genellikle 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üme içinde yalnızca bir parametreyi ValueFromPipeline olarak ayarlayın. Parametre ö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. Cmdtatattribute declaration.

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 neler olduğunu farkında ve daha iyi yönetim kararları almak için izin verir.

Windows PowerShell çalışma zamanı, bir kullanıcının bir Write tercih değişkeni ayarlayarak yönteme her çağrıdan çıkışın nasıl işleneceğini belirlemesine izin verir. Kullanıcı, sistemin başka bir işlem yapmadan önce kullanıcıyı sorgulayıp sorgulamayacağına karar veren bir değişken dahil olmak üzere çeşitli tercih değişkenleri ayarlayabilir.

WriteWarning, WriteVerbose ve WriteDebug yöntemlerini destekleme

Cmdlet, istemeden bir sonucu olabilecek bir işlem gerçekleştirmek üzere olduğunda, System. Management. Automation. cmdlet. WriteWarning metodunu çağırmalıdır. Örneğin, cmdlet salt okunurdur bir dosyanın üzerine yazmak için bir cmdlet bu yöntemi çağırmalıdır.

Kullanıcı cmdlet 'in yaptığı işe ilişkin bazı ayrıntılar gerektirdiğinde, cmdlet System. Management. Automation. cmdlet. WriteVerbose metodunu çağırmalıdır. Örneğin, cmdlet yazarı cmdlet'in ne yaptığı hakkında daha fazla bilgi gerektiren senaryolar olduğunu hissetmesi için bir cmdlet bu bilgileri çağırsa gerekir.

Bir geliştirici veya ürün destek mühendisi cmdlet'ini neyin bozmuş olduğunu anlayacaktır. Cmdlet, System.Management.Automation.Cmdlet.WriteDebug yöntemini çağırabilir. Cmdlet'in System.Management.Automation.Cmdlet.WriteDebug yöntemini System.Management.Automation.Cmdlet.WriteVerbose yöntemini çağıran aynı kodda çağırmasına gerek yoktur çünkü parametresi her iki bilgi kümesi de Debug sunar.

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

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

Konak Arabirimlerini Kullanma

Bazen, bir cmdlet'in System.Management.Automation.Cmdlet sınıfı tarafından desteklenen çeşitli Yazma veya Gerekir yöntemlerini kullanmak yerine doğrudan kullanıcıyla iletişim kurması gerekir. Bu durumda cmdlet, System.Management.Automation.PSCmdlet sınıfından türet olmalı ve System.Management.Automation.PSCmdlet.Host* özelliğini kullan olmalıdır. Bu özellik PromptForChoice, Prompt ve WriteLine/ReadLine türleri dahil olmak üzere farklı iletişim türü düzeylerini destekler. En özel düzeyde, ayrı anahtarları okumanın ve yazmanın ve arabelleklerle başa etmenin yollarını da sağlar.

Bir cmdlet özellikle grafik kullanıcı arabirimi (GUI) oluşturmak üzere tasarlanmadıkça, System.Management.Automation.PSCmdlet.Host* özelliğini kullanarak ana bilgisayarı atlamaz. GUI oluşturmak için tasarlanmış cmdlet'e örnek olarak Out-GridView cmdlet'i örnek olarak vetir.

Not

Cmdlet'ler System.Console API'sini kullanmaz.

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

Her cmdlet derlemesi için, cmdlet Help.xml içeren bir dosya oluşturun. Bu bilgiler cmdlet'in açıklamasını, cmdlet'in parametrelerinin açıklamalarını, cmdlet'in 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ö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.

Kodlama Parametreleri (SC01)

Parameter özniteliğiyle birlikte bir cmdlet sınıfının genel özelliğini bildirerek bir parametre tanımlayın. Parametrelerin, cmdlet'i için türetilmiş .NET Framework statik üyeleri olması gerekir. Parameter özniteliğini nasıl bildiryebilirsiniz? hakkında daha fazla bilgi için bkz. Parametre Özniteliği Bildirimi.

Destek Windows PowerShell Yolları

Bu Windows PowerShell, ad alanlarına erişimi normalleştirme mekanizmasıdır. Cmdlet'Windows PowerShell bir parametreye bir yol atadığınız zaman, kullanıcı belirli bir yolun kısayolu olarak görev alan özel bir "sürücü" tanımlayabilir. Bir kullanıcı böyle bir sürücü tasarlarsa Kayıt Defterindeki veriler gibi depolanan veriler tutarlı bir şekilde kullanılabilir.

Cmdlet'iniz kullanıcının bir dosya veya veri kaynağı belirtmesini sağlarsa, System.Stringtüründe bir parametre tanımlaması gerekir. Birden fazla sürücü desteklense, tür bir dizi olması gerekir. Parametrenin adı, diğer adıyla Path PSPath olmalıdır. Ayrıca, parametresi Path joker karakterleri desteklemeli. Joker karakter desteği gerekli yoksa bir parametre LiteralPath tanımlayın.

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

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

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

Joker Karakter Desteği

Mümkünse bir cmdlet joker karakterleri desteklemeli. Bir cmdlet'te birçok yerde joker karakter desteği oluşur (özellikle de bir parametre bir nesne kümesinden bir nesneyi tanımlamak için bir dizeyi alıyorsa). Örneğin, Stop-Proc StopProc Öğreticisi'nin örnek cmdlet'i, işlem adlarını Name temsil eden dizeleri işlemek için bir parametre tanımlar. Bu parametre, kullanıcının durduracak işlemleri kolayca belirtmesi için joker karakterleri destekler.

Joker karakter desteği kullanılabilir olduğunda, cmdlet işlemi genellikle bir dizi üretir. Bazen, kullanıcı aynı anda yalnızca tek bir öğe kullanabileceği için bir diziyi desteklemek mantıklı değildir. Örneğin, Set-Location cmdlet'inin bir diziyi desteklemesi gerekir çünkü kullanıcı yalnızca tek bir konum ayarlar. Bu örnekte cmdlet yine de joker karakterleri destekler, ancak çözümlemeyi tek bir konuma iter.

Joker karakter desenleri hakkında daha fazla bilgi için bkz. Cmdlet Parametrelerinde Joker Karakter Desteği.

Nesneleri Tanımlama

Bu bölüm cmdlet'ler için nesneleri tanımlama ve mevcut nesneleri genişletme yönergelerini içerir.

Standart Üyeleri Tanımlama

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

Parametre Olarak Kullanılacak ObjectMembers Tanımlama

Bir cmdlet için bir nesne tasarıyorsanız, üyelerinin doğrudan onu kullanan cmdlet'lerin parametrelerine eşleyenden emin olur. Bu eşleme, nesnenin işlem hattına kolayca gönderilene ve bir cmdlet'inden diğerine geçirilene olanak sağlar.

Cmdlet'ler .NET Framework nesnelerinin önceden var olup, betik geliştiricisi veya kullanıcısı tarafından gerekli olan bazı önemli veya kullanışlı üyeler sıklıkla eksiktir. Bu eksik üyeler, nesnenin işlem hattına doğru şekilde geçirilene kadar doğru üye adlarını oluşturması ve görüntüleme açısından özellikle önemli olabilir. Bu gerekli üyeleri belgeley için özel bir Types.ps1xml dosyası oluşturun. Bu dosyayı oluşturmadan önce şu adlandırma kuralını <Your_Product_Name>. Types.ps1xml.

Örneğin, bir dosyanın özniteliklerini daha net görüntülemek için Mode System.IO.FileInfo türüne bir betik özelliği eklersiniz. Buna ek olarak, system.Array türüne bir diğer ad özelliği ekleyebilir ve bu özellik adının Count (yerine) tutarlı bir şekilde kullanımına izin veebilirsiniz. Length

IComparable Arabirimini Uygulama

Tüm çıkış nesnelerine System.IComparable arabirimi uygulama. Bu, çıkış nesnelerinin çeşitli sıralama ve analiz cmdlet'lerine kolayca kanal oluşturmasını sağlar.

Görüntüleme Bilgilerini Güncelleştirme

Bir nesnenin görüntüsü beklenen sonuçları sağlayamasa özel bir <YourProductName> oluşturun. Bu nesne için Format.ps1xml dosyası.

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

İşlem Hattının Ortasında Uygulama

Bir işlem hattının ortasından çağrıldığını varsayarak bir cmdlet uygulama (diğer bir ifade, diğer cmdlet'ler kendi girdisini üretir veya çıktısını tüketir). Örneğin, veri üretmesi nedeniyle cmdlet'in yalnızca bir işlem hattında ilk Get-Process cmdlet olarak kullanılageldiğini varsayabilirsiniz. Ancak, bu cmdlet bir işlem hattının ortasında tasarlanma nedeniyle, bu cmdlet işlem hattında önceki cmdlet'lerin veya verilerin alınarak işlemleri belirtmesi için izin verir.

İşlem Hattından Destek Girişi

Cmdlet'in her parametre kümesinde, işlem hattından gelen girişi destekleyen en az bir parametreyi dahil eder. İşlem hattı girişi desteği, kullanıcının verileri veya nesneleri almalarına, bunları doğru parametre kümesine göndermelerine ve sonuçları doğrudan bir cmdlet'e göndermesini sağlar.

Parameter özniteliği anahtar sözcüğünü, anahtar sözcük özniteliğini veya bildiriminde her iki anahtar sözcüğü de içerirse, parametre ValueFromPipeline işlem ValueFromPipelineByPropertyName hattından gelen girişi kabul eder. Parametre kümesinde yer alan parametrelerin hiçbiri veya anahtar sözcüklerini desteklemezse, herhangi bir işlem hattı girişini yoksayacak olan cmdlet başka bir cmdlet'in ardına anlamlı bir şekilde ValueFromPipeline ValueFromPipelineByPropertyName yerleştirilamaz.

ProcessRecord Yöntemini Destekleme

İşlem hattında önceki cmdlet'inden 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 bir kez olmak üzere bu yöntemi birden çok kez çağıran bir yöntemdir.

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

Bir cmdlet nesneleri döndür olduğunda, cmdlet nesneleri oluşturulurken hemen yazmalıdır. Cmdlet bunları birleştirilmiş dizide arabelleğe alma amacıyla tutmamalı. Nesneleri giriş olarak alan cmdlet'ler daha sonra gecikme olmadan çıkış nesnelerini işleye, görüntüye veya işlemeye ve görüntülemeye devam eder. Tek tek çıkış nesneleri oluşturan bir cmdlet, System.Management.Automation.Cmdlet.WriteObject yöntemini çağırabilir. Çıkış nesnelerini toplu olarak oluşturan bir cmdlet (örneğin, temel api bir çıkış nesneleri dizisi döndüren için), ikinci parametresi olarak ayarlanmış System.Management.Automation.Cmdlet.WriteObject Yöntemini true çağırabilir.

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

Varsayılan olarak, Windows PowerShell büyük/büyük/büyük harfe duyarlı değildir. Bununla birlikte, önceden var olan birçok sistemle Windows PowerShell kullanım kolaylığı ve uyumluluk için durumu korumaz. Başka bir deyişle, bir karakter büyük harflerle sağlanmadı Windows PowerShell büyük harflerle tutar. Sistemlerin iyi çalışması için cmdlet'in bu kuralı izlemesi gerekir. Mümkünse, büyük/küçük harfe duyarlı olmayan bir şekilde çalışmalı. Ancak, daha sonra bir komutta veya işlem hattında oluşan cmdlet'ler için özgün büyük/küçük harfe sahip olması gerekir.

Ayrıca Bkz.

Gerekli Geliştirme Yönergeleri

Tavsiye Niteliğinde Geliştirme Yönergeleri

Windows PowerShell Cmdlet’ini Yazma