Yardım dosyalarını adlandırma

Not

XML tabanlı yardımın manuel olarak yazılması çok zordur. PlatyPS modülü, Markdown'da yardım yazmanıza ve ardından bunu XML tabanlı yardıma dönüştürmenize olanak tanır. Bu, yardım yazmayı ve sürdürmeyi çok daha kolaylaştırır. PlatyPS ayrıca sizin için Güncellenebilir Yardım paketleri de oluşturabilir. Daha fazla bilgi için PlatyPS kullanarak XML tabanlı yardım oluşturma konusuna bakın.

Bu konu, XML tabanlı bir yardım dosyasının Get-Help cmdlet'inin bulabilmesi için nasıl adlandırılacağını açıklamaktadır. Ad gereksinimleri her komut türü için farklılık gösterir.

Cmdlet Yardım dosyaları

C# cmdlet'inin yardım dosyası, cmdlet'in tanımlandığı derleme için adlandırılmalıdır. Aşağıdaki dosya adı biçimini kullanın:

<AssemblyName>.dll-help.xml

Derleme iç içe geçmiş bir modül olsa bile derleme adı formatı gereklidir.

Örneğin, Get-WinEvent cmdlet'i Microsoft.PowerShell.Diagnostics.dll derlemesinde tanımlanmıştır. Get-Help cmdlet'i, yalnızca Microsoft.PowerShell.Diagnostics.dll-help.xml cmdlet'i için bir yardım konusu arar > modül dizinindeki dosya.

Sağlayıcı Yardım dosyaları

Bir PowerShell sağlayıcısının yardım dosyası, sağlayıcının tanımlandığı derleme için adlandırılmalıdır. Aşağıdaki dosya adı biçimini kullanın:

<AssemblyName>.dll-help.xml

Derleme iç içe geçmiş bir modül olsa bile derleme adı formatı gereklidir.

Örneğin, Sertifika sağlayıcısı Microsoft.PowerShell.Security.dll derlemesinde tanımlanmıştır. Get-Help cmdlet'i, Sertifika sağlayıcısına yönelik bir yardım konusunu yalnızca modül dizinindeki Microsoft.PowerShell.Security.dll-help.xml dosyasında arar.

İşlev Yardım dosyaları

İşlevler, yoruma dayalı yardım kullanılarak belgelenebilir veya bir XML yardım dosyasında belgelenebilir. İşlev bir XML dosyasında belgelendiğinde, işlevin, işlevi XML dosyasıyla ilişkilendiren bir .ExternalHelp yorum anahtar sözcüğü olması gerekir. Aksi halde Get-Help cmdlet'i yardım dosyasını bulamaz.

İşlev yardım dosyasının adı için herhangi bir teknik gereksinim yoktur. Ancak en iyi uygulama, işlevin tanımlandığı komut dosyası modülünün yardım dosyasını adlandırmaktır. Örneğin aşağıdaki fonksiyon MyModule.psm1 dosyasında tanımlanmıştır.

#.ExternalHelp MyModule.psm1-help.xml
function Test-Function { ... }

CIM Komut Yardımı dosyaları

Bir CIM komutunun yardım dosyası, CIM komutunun tanımlandığı CDXML dosyasına göre adlandırılmalıdır. Aşağıdaki dosya adı biçimini kullanın:

<FileName>.cdxml-help.xml

CIM komutları, modüllere iç içe modüller olarak dahil edilebilecek CDXML dosyalarında tanımlanır. CIM komutu oturuma bir işlev olarak içe aktarıldığında, PowerShell, işlevi, CIM'in bulunduğu CDXML dosyası için adlandırılan bir XML yardım dosyasıyla ilişkilendiren işlev tanımına bir .ExternalHelp yorum anahtar sözcüğü ekler. CIM komutu tanımlandı.

Komut Dosyası İş Akışı Yardım dosyaları

Modüllerde bulunan komut dosyası iş akışları XML tabanlı yardım dosyalarında belgelenebilir. Yardım dosyasının adı için herhangi bir teknik gereksinim yoktur. Ancak en iyi uygulama, komut dosyası iş akışının tanımlandığı komut dosyası modülünün yardım dosyasını adlandırmaktır. Örneğin:

<ScriptModule>.psm1-help.xml

Diğer komut dosyasıyla yazılan komutların aksine, komut dosyası iş akışları, onları bir yardım dosyasıyla ilişkilendirmek için .ExternalHelp yorum anahtar sözcüğüne ihtiyaç duymaz. Bunun yerine PowerShell, XML tabanlı yardım dosyaları için modül dizininin UI-Culture'a özgü alt dizinlerinde arama yapar ve tüm dosyalarda komut dosyası iş akışına yönelik yardım arar. .ExternalHelp yorum anahtar sözcüğü göz ardı edilir.

.ExternalHelp yorum anahtar sözcüğü göz ardı edildiğinden, Get-Help cmdlet'i yalnızca modüllere dahil edildiklerinde komut dosyası iş akışları için yardım bulabilir.

İlgili makaleler