{"id":3761,"date":"2009-07-09T15:11:00","date_gmt":"2009-07-09T15:11:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/powershell\/2009\/07\/09\/function-help-cannot-share-a-cmdlet-help-file\/"},"modified":"2019-02-18T13:12:31","modified_gmt":"2019-02-18T20:12:31","slug":"function-help-cannot-share-a-cmdlet-help-file","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/function-help-cannot-share-a-cmdlet-help-file\/","title":{"rendered":"Function Help Cannot Share a Cmdlet Help File"},"content":{"rendered":"

In Windows PowerShell 2.0, you can write help topics for functions, scripts, and modules, just as you do for cmdlets and providers. In fact, as a best practice, you should always include help topics for all shared PowerShell items. <\/font><\/span><\/p>\n

<\/font><\/span> And we make it easy. For functions and scripts, you can write comment-based help topics right in the script or function (see <\/font><\/span>about_Comment_Based_Help<\/font><\/span><\/a>) or you can write XML-based help topics that use the same schema as cmdlet help topics. .To do so, just add the .ExternalHelp<\/b> comment keyword to the function or script followed by the path and name of the XML file that contains the help topic. <\/font><\/span><\/p>\n

However, the XML-based help topics for functions and scripts must be in their own XML file. You can put XML-based topics for functions and scripts in the same file. But you cannot put the XML-based help topics for functions and scripts in the same file with XML-based help topics for cmdlets and providers. If you combine the topic types, Get-Help will find only the function\/script help topics or only the cmdlet help topics, but not both. This limitation might be fixed in the future, but combined-type XML files do not work property in Windows PowerShell 2.0.<\/font><\/span><\/p>\n

Unfortunately <blush\/>, we included an example of this error in Windows PowerShell 2.0. Try this:<\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Start a new Windows PowerShell session. (Type: powershell<\/b>).<\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Type: get-help Disable-PSRemoting -full<\/b><\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Read it. Great info. Really.<\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Now, type get-help Enable<\/span>-PSRemoting -full<\/b><\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Hmmm. Not much.<\/font><\/span><\/p>\n

It works in reverse, too. <\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Start a new Windows PowerShell session. (Type: powershell<\/b>).<\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Type: get-help Enable-PSRemoting -full<\/b><\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Read it. Great info. Really.<\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Now, type get-help Disable<\/span>-PSRemoting -full<\/b><\/font><\/span><\/p>\n

\u00b7        <\/span><\/span><\/span>Hmmm. Not much.<\/font><\/span><\/p>\n

The problem is that the help topic for the Disable-PSRemoting function (yes, it’s a function) is in the System.Management.Automation.dll-Help.xml file, along with the help topics for all of the cmdlets in the System.Management.Automation.dll file, including Enable-PSRemoting.. So, if your first Get-Help call in the session is for a function or script in that file, you can get help only for functions and scripts in the file. If your first Get-Help call in the session is for a cmdlet, you get only cmdlet help in that file.<\/font><\/span><\/p>\n

We’re working on ways to fix and prevent this, but you can be smarter and avoid it in the first place. I’ll be updating the about_Comment-Based_Help file online and our SDK topics creating help files. In the meantime, be sure to create separate XML files for your help topics.<\/font><\/span><\/p>\n

June Blender [MSFT], Windows PowerShell Documentation<\/font><\/span><\/p>\n

Guangfa Lu [MSFT], Windows PowerShell Test<\/font><\/span><\/p>\n

Get Windows PowerShell Help Online:  http:\/\/go.microsoft.com\/fwlink\/?LinkID=107116<\/a><\/font> <\/font><\/span><\/p>\n

<\/font><\/span> <\/p>\n","protected":false},"excerpt":{"rendered":"

In Windows PowerShell 2.0, you can write help topics for functions, scripts, and modules, just as you do for cmdlets and providers. In fact, as a best practice, you should always include help topics for all shared PowerShell items.  And we make it easy. For functions and scripts, you can write comment-based help topics right […]<\/p>\n","protected":false},"author":600,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[174,2,366],"class_list":["post-3761","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-get-help","tag-help","tag-xml"],"acf":[],"blog_post_summary":"

In Windows PowerShell 2.0, you can write help topics for functions, scripts, and modules, just as you do for cmdlets and providers. In fact, as a best practice, you should always include help topics for all shared PowerShell items.  And we make it easy. For functions and scripts, you can write comment-based help topics right […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/3761","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/600"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=3761"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/3761\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=3761"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=3761"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=3761"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}