{"id":13303,"date":"2017-01-24T08:00:28","date_gmt":"2017-01-24T16:00:28","guid":{"rendered":"https:\/\/www.sapien.com\/blog\/?p=13303"},"modified":"2017-01-20T15:17:49","modified_gmt":"2017-01-20T23:17:49","slug":"powershell-helpwriter-2017-whats-new-part-2","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2017\/01\/24\/powershell-helpwriter-2017-whats-new-part-2\/","title":{"rendered":"PowerShell HelpWriter 2017: What’s New? (Part 2)"},"content":{"rendered":"

We\u2019ve written a series of blog posts to introduce you to the newest features of the product and in this release, we made major changes to PowerShell HelpWriter.<\/p>\n

In Part 1<\/a>, we looked at the new UI changes to the designer and the editor.<\/p>\n

In Part 2, we are looking at the new project feature for PowerShell HelpWriter.<\/p>\n

 <\/p>\n

Projects<\/h2>\n

PowerShell HelpWriter introduces projects to manage multi-file help, deployment and to keep track of the source module.<\/p>\n

 <\/p>\n

Are projects required?<\/h3>\n

No, you do not have to use projects to maintain your help files, but using a project will have the following benefits:<\/p>\n

    \n
  1. Keep track of the source module, which allow you to rebuild the help files in order to reflect changes in the module.<\/li>\n
  2. Organize all your help files in one location without having to leave PowerShell HelpWriter 2017.<\/li>\n
  3. Automatically backup existing help files when a module version changes or when you rebuild the help.<\/li>\n
  4. Ensure that you have access to project specific features and upcoming project features.<\/li>\n<\/ol>\n

     <\/p>\n

    How do I create a project?<\/h3>\n

    PowerShell HelpWriter 2017 will create a project when you select the Help Project (From Module)<\/strong> command or the New Help Project (Empty) <\/strong>commands.<\/p>\n

    \"New<\/a><\/p>\n

     <\/p>\n

    If you select Help Project (From Module)<\/strong>, you will be presented with a dialog to select the module from which to generate a help file.<\/p>\n

    \"Select<\/a><\/p>\n

    Optionally, you can use the Browse<\/strong> button to select the module. You will need to use this option if the module is not located in a discoverable PSModulePath<\/em> directory.<\/p>\n

     <\/p>\n

    Next you are presented with the New Help Project<\/strong> dialog. This dialog will allow you to configure the project\u2019s settings and name.<\/p>\n

    \"New<\/a><\/p>\n\n\n\n\n\n\n\n\n
    Setting<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
    Project Name<\/td>\nSets the name of the project. This defaults to the module\u2019s name.<\/td>\n<\/tr>\n
    Location<\/td>\nThe folder to save the project in.\u00a0 You will want to keep the help project outside of the module folder otherwise the project files and backups may clutter your module directory.\u00a0 The default location for projects is:<\/p>\n

    \\My Documents\\SAPIEN\\Help Projects<\/td>\n<\/tr>\n

    Create Project Folder<\/td>\nCreates a subdirectory in the Location<\/strong> folder using the project\u2019s name.<\/td>\n<\/tr>\n
    Language Folder<\/td>\nSets the destination folder within the project to store the help files. The default value is dependent on the default culture of the computer.<\/p>\n

    For example: en-US<\/strong> for English (United States).<\/td>\n<\/tr>\n

    Rebuild Using<\/td>\nSpecifies what method HelpWriter should use to import the module in order to rebuild the help files.<\/p>\n

    Module\u2019s Path:<\/em>
    \nRebuilds the help files by using the module\u2019s file path to import the module.
    \nUse this setting when you want a specific version of the module or when the module is located outside a PSModulePath<\/em> directory.<\/p>\n

    Module\u2019s Name:<\/em>
    \nRebuilds the help files by using the module\u2019s name to import the module.
    \nUse this setting when you want rebuild using the latest version of the module as determined by PowerShell.
    \nNote: The module must be located in a PSModulePath<\/em> directory.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    Once you have selected your options, press the Create<\/strong> button and you now have your new project.\u00a0 The newly created project will contain a sample about topic for your convenience. Now you can use the Project panel to modify the project settings or edit the generated files.<\/p>\n

     <\/p>\n

    Project Panel<\/h3>\n

    The Project panel allows you to add, remove and manipulate the project files. You can also use the panel to open the project\u2019s folder or the module\u2019s folder in Windows Explorer. Those of you who work with projects in PowerShell Studio, will find this panel familiar.<\/p>\n

    \"Project<\/a><\/p>\n

    The project contains the specified language folder and a sample about text file, in addition to the generated help files.<\/p>\n

    From the Project panel, you can:<\/p>\n

      \n
    1. Rename files or the project.<\/li>\n
    2. Add new files to the project.<\/li>\n
    3. Add existing files to the project.<\/li>\n
    4. Create folders<\/li>\n
    5. Open the project folder in Windows Explorer.<\/li>\n
    6. Open the module\u2019s folder in Windows Explorer.<\/li>\n
    7. Refresh the module information (see below).<\/li>\n
    8. Deploy the help files to the module (see below).<\/li>\n
    9. Rebuild the help files from the module (see below).<\/li>\n<\/ol>\n

      Select a file node or the project node in order to modify the settings in the Properties panel.<\/p>\n

       <\/p>\n

      Properties Panel and Project Properties<\/h3>\n

      As, we mentioned the Properties panel allows you to modify file or project properties\/settings depending on the selection in the Project panel.<\/p>\n

      \"Properties<\/a><\/p>\n

       <\/p>\n

      Now we will take a look at the project\u2019s properties.\u00a0 The project\u2019s properties are grouped into two categories: Module<\/em> and Project<\/em>.<\/p>\n

      Project Category<\/h4>\n

      The project category pertains to the project itself.<\/p>\n\n\n\n\n\n
      Property<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
      Project Name<\/td>\nSpecifies the name of the project. You can rename the project by editing this property.<\/td>\n<\/tr>\n
      Project Path<\/td>\nDisplays the location of the help project.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

       <\/p>\n

      Module Category<\/h4>\n

      The module category contains the module specific information and settings.<\/p>\n\n\n\n\n\n\n\n
      Property<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
      Module Name<\/td>\nSpecifies the name of the Module. This value is used to rebuild the help file depending on the Rebuild Using<\/strong> property (see below). You can edit this value.<\/td>\n<\/tr>\n
      Module Path<\/td>\nDisplays the location of the help projects. This value is used to rebuild the help file depending on the Rebuild Using<\/strong> property (see below). You can edit this value to select a specific version of the module.<\/td>\n<\/tr>\n
      Module Version<\/td>\nThe last detected version number of the module.<\/td>\n<\/tr>\n
      Rebuild Using<\/td>\nThis property was determined in the New Help Project<\/strong> dialog (See above).
      \nRebuild Using<\/strong> specifies what method PowerShell HelpWriter will use to import the module in order to rebuild the help files.<\/p>\n

      Path:<\/em>
      \nRebuilds the help files by using the project\u2019s Module Path<\/strong> property to import the module.<\/p>\n

      Name:<\/em>
      \nRebuilds the help files by using the project\u2019s Module Name<\/strong> property to import the module.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

       <\/p>\n

      Deploying Help Files<\/h3>\n

      Since the project is purposely kept outside the module\u2019s directory, we added the Deploy<\/strong> command.<\/p>\n

      \"Ribbon<\/a><\/p>\n

      Use the Deploy<\/strong> command to ensure your help files are accessible by PowerShell when loading the target module. When you deploy, PowerShell HelpWriter will copy the project\u2019s help files, including the folder structure, over to the module\u2019s directory. The module location is determined by the project\u2019s Module Path<\/strong> property.<\/p>\n

      \"Deploying\"<\/a><\/p>\n

       <\/p>\n

      Important: If you generated xml help from comment-based help, you will need to update any exported function\u2019s help-comment to include a .EXTERNALHELP line:<\/span><\/p>\n

      <#\r\n.EXTERNALHELP MyModule.psm1-Help.xml\r\n#><\/span>\r\nfunction<\/span> Get-MyFunction<\/span>\r\n{\r\n\r\n}<\/span><\/pre>\n
       <\/p>\n
      Rebuilding Help<\/h3>\n
      The Rebuild<\/strong> command will reconstruct the help files from the source module and will replace the existing files <\/strong><\/em>in the project.<\/p>\n
      \"Ribbon<\/a><\/p>\n
      Automatic Backup<\/h4>\n
      Before rebuilding and replacing the help file, PowerShell HelpWriter automatically backup all your project files to the following directory:<\/p>\n
      Project Folder\\Help_Backup\\version number\\<\/p><\/blockquote>\n
      For example:<\/p>\n
      MyHelpProject\\Help_Backup\\1.0.0.0<\/p><\/blockquote>\n
      The version number is determined by the project\u2019s Module Version<\/strong> property. If the Rebuild<\/strong> command fails, the application will automatically restore the files.<\/p>\n
      If you wish to roll back the rebuild changes, you can copy and replace the files using the backup copies.<\/p>\n
       <\/p>\n
      When you run the Rebuild<\/strong> command, you will be presented with the following dialog, which asks what action you would like to take:<\/p>\n
      \"Rebuild<\/a><\/p>\n
      You can select the following actions:<\/p>\n\n\n\n\n\n
      Action<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
      Deploy to and rebuild help from the module<\/td>\nThis action will deploy the file helps to the current module location before rebuilding the help files. This ensures the help content is present in the newly constructed files.<\/p>\n
      Important:<\/strong> If you are using the Rebuild By Name<\/strong> setting, PowerShell may rebuild the help from another location, which can mean the newly deployed help files may not be present. Therefore, it is recommended to check the module beforehand by using the Refresh Module Information<\/strong> command (see below).<\/td>\n<\/tr>\n
      Rebuild help from the module<\/td>\nThis action will simply rebuild the module help files without deploying the project files.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
      Target Language Folder<\/h4>\n
      Use the Target Language Folder setting to build the help files in a specific language folder.
      \nNote: PowerShell HelpWriter will default to the first language folder in the project. If not found, it will use the culture setting of the OS.<\/p>\n
      After making your choice and pressing the OK <\/strong>button, PowerShell HelpWriter will start the rebuilding process and display a progress dialog:<\/p>\n
      \"Rebuilding<\/a><\/p>\n
      You can press the Cancel<\/strong> button to stop the process and to restore the original files from the backup.<\/p>\n
      Upon a successful completion, PowerShell HelpWriter will list the files that were added and\/or updated:<\/p>\n
      \"Rebuild<\/a><\/p>\n
       <\/p>\n
      Refreshing Module Information<\/h3>\n
      The Refresh Module Information<\/strong> commands triggers PowerShell HelpWriter to query the module information using the method determined by the project\u2019s Rebuild Using<\/strong> property.<\/p>\n
      It is recommended to use this command before using the Rebuild<\/strong> command, especially when using the Rebuild Using Name<\/strong> setting.<\/p>\n
      \"Ribbon<\/a><\/p>\n
      If PowerShell HelpWriter detects a change in the module, such as the version, location or name, it will present you with the following dialog:<\/p>\n
      \"Module<\/a><\/p>\n
      The dialog displays the found module and the stored information determined by the project properties. It also presents you with the follow actions to perform:<\/p>\n\n\n\n\n\n\n
      Action<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
      Deploy to and rebuild help using the new version<\/em><\/td>\nThe action deploys the help to the new module location \/ version and then rebuilds and replaces the help files in the project.<\/td>\n<\/tr>\n
      Rebuild help using the new version<\/em><\/td>\nThe action rebuilds the help files without deploying the project files.<\/td>\n<\/tr>\n
      Update module information only<\/em><\/td>\nIt will update the project\u2019s settings without rebuilding or deploying.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
      When you press the OK<\/strong> button, PowerShell HelpWriter will automatically backup the help file using the current module version before updating the module information.<\/p>\n
      If you selected a rebuild action, it will then run the Rebuild<\/strong> command as discussed above.<\/p>\n
       <\/p>\n
      As you can see, projects contain many useful features such as, file management, automatic backups and deployment capacities. These features allow you to work outside of the module and to respond to new versions of the module.<\/p>\n
       <\/p>\n
      Please continue providing your feedback. Many of the new features included in the service builds are suggestions from users like you. Therefore, if you have any suggestions or feature requests, please share them with us on our Wish List and Feature Requests<\/a> forum.<\/p>\n","protected":false},"excerpt":{"rendered":"
      We\u2019ve written a series of blog posts to introduce you to the newest features of the product and in this release, we made major changes to PowerShell HelpWriter. In Part 1, we looked at the new UI changes to the designer and the editor. In Part 2, we are looking at the new project feature […]<\/p>\n","protected":false},"author":10,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[1038,624,21,632],"tags":[1179,28,953,645,155,141],"class_list":["post-13303","post","type-post","status-publish","format-standard","hentry","category-powershell-helpwriter","category-service-build","category-software-news","category-whats-new-software-news","tag-1179","tag-powershell","tag-powershell-help-writer","tag-service-build-2","tag-service-release","tag-whats-new"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/13303","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/10"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=13303"}],"version-history":[{"count":5,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/13303\/revisions"}],"predecessor-version":[{"id":13308,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/13303\/revisions\/13308"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=13303"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=13303"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=13303"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}