[AX]AX2012 帮助服务

在AX2012使用F1快捷键获取上下文帮助时需要有安装Help server，Help server是一个web服务，部署在IIS站点上，web服务URL记录在System administration>Setup>System>Help system parameters>Help service URL。需要注意的是Help server不能和Sharepoint 2010运行在同一个站点上，所以你可能需要创建一个单独端口的IIS站点宿主Help server站点。在Client程序中F1时Client查找到帮助服务web service url后调用Help view程序中查看，Help view随Client程序一起安装。帮助Web服务默认安装在C:\inetpub\wwwroot\DynamicsAX6HelpServer，帮助内容相关的文件在C:\inetpub\wwwroot\DynamicsAX6HelpServer\Content可以找到，在Help view中左边的树形列表来自于content目录下TableOfContents.xml文件中定义的主题页面链接，右边内容则是来自于content目录下众多HTML文件。

编写帮助文件

我们可以创建新的帮助文件，也可以修改已有的html帮助文件。html帮助文件必须遵循一些固定的格式，一个典型的文件类似这样：

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"[]>
<html dir="LTR" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dynHelp="http://schemas.microsoft.com/dynamicsHelp/2008/11" xmlns:dynHelpAx="http://schemas.microsoft.com/dynamicsHelpAx/2008/11" xmlns:MSHelp="http://msdn.microsoft.com/mshelp" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta NAME="save" content="history" />
    <title>temp testing </title>
    <link rel="stylesheet" type="text/css" href="../local/presentation.css" />
    <link rel="stylesheet" type="text/css" href="../local/AX.css" />
    <script type="text/javascript" src="../local/EventUtilities.js"> </script>
    <script type="text/javascript" src="../local/Dropdown.js"> </script>
    <script type="text/javascript" src="../local/script_manifold.js"> </script>
    <script type="text/javascript" src="../local/script_feedBack.js"> </script>
    <script type="text/javascript" src="../local/CheckboxMenu.js"> </script>
    <script type="text/javascript" src="../local/CommonUtilities.js"> </script>
    <meta name="Title" content="temp testing" />
    <meta name="Microsoft.Help.Id" content="D88E71BE-19A0-41F8-91C1-75F7675097AB" />
    <meta name="ms.locale" content="EN-US" />
    <meta name="publisher" content="Contoso" />
    <meta name="documentSets" content="UserDocumentation" />
    <meta name="Microsoft.Help.Keywords" content="" />
    <meta name="suppressedPublishers" content="" />
    <meta name="Microsoft.Help.F1" content="Forms.CustTable" />
    <meta name="description" content="Insert introduction here. " />
  </head>
  <body>
    <input type="hidden" id="userDataCache" class="userDataStyle" />
    <input type="hidden" id="hiddenScrollOffset" />
    <img id="collapseImage" style="display:none; height:0; 0;" src="../local/collapse_all.gif" alt="" title="" />
    <img id="expandImage" style="display:none; height:0; 0;" src="../local/expand_all.gif" alt="" title="" />
    <img id="collapseAllImage" style="display:none; height:0; 0;" src="../local/collapse_all.gif" />
    <img id="expandAllImage" style="display:none; height:0; 0;" src="../local/expand_all.gif" />
    <img id="dropDownImage" style="display:none; height:0; 0;" src="../local/dropdown.gif" />
    <img id="dropDownHoverImage" style="display:none; height:0; 0;" src="../local/dropdownHover.gif" />
    <img id="copyImage" style="display:none; height:0; 0;" src="../local/copycode.gif" alt="" title="" />
    <img id="copyHoverImage" style="display:none; height:0; 0;" src="../local/copycodeHighlight.gif" alt="" title="" />
    <div id="header">
      <table id="topTable">
        <tr>
          <td>
            <span onclick="ExpandCollapseAll(toggleAllImage)" style="cursor:default;" onkeypress="ExpandCollapseAll_CheckKey(toggleAllImage, event)" tabindex="0">
              <img ID="toggleAllImage" class="toggleAll" src="../local/collapse_all.gif" /> <label id="collapseAllLabel" for="toggleAllImage" style="display: none;">Hide all</label><label id="expandAllLabel" for="toggleAllImage" style="display: none;">Show all</label> </span>
          </td>
        </tr>
      </table>
      <table id="bottomTable">
        <tr id="headerTableRow1">
          <td align="left">
            <span id="runningHeaderText" />
          </td>
        </tr>
        <tr id="headerTableRow2">
          <td align="left">
            <span id="nsrTitle">temp testing </span>
          </td>
        </tr>
      </table>
      <hr class="title-divider" />
    </div>
    <div id="mainSection">
      <div id="mainBody">
        <div id="allHistory" class="saveHistory" onsave="saveAll()" onload="loadAll()" />
        <div class="introduction">
        <p>
            Insert introduction here.
        </p>
    </div>
        <h1 class="heading">
          <span onclick="ExpandCollapse(sectionToggle0)" style="cursor:default;" onkeypress="ExpandCollapse_CheckKey(sectionToggle0, event)" tabindex="0">
            <img id="sectionToggle0" class="toggle" name="toggleSwitch" src="../local/collapse_all.gif" />Section Heading</span>
        </h1>
        <div id="sectionSection0" class="section" name="collapseableSection" style="">
        
        <p>
            Insert section body here.
        </p>
    <h3 class="subHeading">Subsection Heading</h3><div class="subsection">
        <p>
            Insert subsection body here.
        </p>
    </div></div>
      </div>
      <div id="footer">
        <div class="footerLine">
          <img width="100%" height="3px" src="../local/footer.gif" alt="" title="" />
        </div>
        <p />    
       <p class="build-date">Build date: 2011-06-08 [13:05]</p></div>
    </div>
  </body>
</html>

第一行和第二行原封不动的拷贝就行了，需要注意的是“<html”开始的第二行，必须完整的添加xmlns引入的多个命名空间，在测试中发现这些内容必须在一行上，中间不能有换行，否则帮助服务无法解析此文件。和帮助主题等相关的内容都在meta标记中：

Microsoft.Help.Id：标记帮助的主题，在主题Content table中通过这个ID找到相应的文件，可以是guid字符串，或者自定义的更有含义的字符串，只是两个文件的help Id不能相同，否则只有第一个文件才会有效。
ms.locale：帮助内容的语言。
publisher：帮助的发布者，AX自带的内容都是Microsoft，如果是自定义的帮助文件可以使用自己公司的名称。在Help view查找Options中我们可以指定搜索来自于特定Publsiher的帮助内容。
documentSets：帮助的文档集合，标识帮助文件的性质类别，比如说是用户文档、开发文档、词汇表等，所有的文档集合定义在AOT/Help document set下。Document set的ContentLocation属性指定帮助内容是来自于Help server还是微软MSDN等在线站点，比如DeveloperDocumentation是来自于在线站点。
Microsoft.Help.Keywords：搜索关键字
suppressedPublishers：如果你是修改AX自带的帮助文件，最好设置该项为Microsoft
Microsoft.Help.F1：F1请求帮助时所用的主题词，AX的Base Enums、Classes、Configuration keys、Data types、Forms、List Pages、Maps、Menu items、Parts、Reports、Tables、Views支持F1帮助，F1 ID不是随便取的，AOT中右键点击对象Add-ins>Help property可以看到对象的F1帮助ID，比如客户详细信息Form的F1 Id为Forms.CustTable。可以有多个帮助文件使用相同的F1 Id，在Help view中它们都会被列出。如果帮助文件不对应AOT的某个对象，可以设置为和Help Id相同。Content table中条目使用F1 Id索引帮助文件。
Title：帮助的标题，也可以作为关键字来搜索。
description：说明描述

AX自带帮助中提供了一些css，使用它们来格式化帮助内容以统一风格，此外还有一些js脚本，用来折叠内容章节等等，参照已有的帮助文件使用就可以了。css和js文件在C:\inetpub\wwwroot\DynamicsAX6HelpServer\Content\Microsoft\EN-US\Local可以找到。

对html不熟悉的人员可以使用Office word来编写帮助文件，在Help view中搜索“Templates for Help Documentation”，在结果帮助页中找到Dynamics Help Content Template.docm，这是word的模板文件，需要使用office 2007及以后的版本打开，打开时需要启用宏，宏会在Ribbon工具栏上添加一个名为“Microsoft Dynamics Help”的标签页：

在这里可以设置帮助文档标题、Top Id、Publisher等属性。选中“Automatically Save Properties”和“Save As Single File Webpage”，在保存帮助文件时会自动创建一个.htm和.mht的文件，.htm包含meta设定的帮助属性，也由它打开具体的帮助内容文件.mht。

与此类似，其他类型比如word的帮助文件我们也需要一个htm文件来间接引用，比如：

<html>
   <head>
      <meta name="Title" content="Sample content element" />
      <meta name="Microsoft.Help.Id" content="8D937F19-3A00-4F37-A316-0A48D052D627" />
      <meta name="ms.locale" content="EN-US" />
      <meta name="publisher" content="Microsoft" />
      <meta name="documentSets" content="UserDocumentation" />
      <meta name="Microsoft.Help.Keywords" content="" />
      <meta name="suppressedPublishers" content="" />
      <meta name="Microsoft.Help.F1" content="SampleContentElement" />
      <meta name="description" content="An example of a non-HTML content element that was published to the Help system." />

      <script type="text/javascript">
         <!-- 
            window.location=" SampleContentElement.docx" 
         //-->
      </script>

   </head>
</html>

在帮助文件中我们可以使用AX的标签，如果找到相应的AX标签会替换掉标记中的缺省内容：

<dynHelpAx:label axtype="Label" id="@SYS21829">Bank Account</ dynHelpAx:label>

也可以使用AX表字段的标签：

<dynHelpAx:label axtype="Field" axtable="DirPartyTable" axfield="Name">Name</dynHelpAx:label>

还可以使用AX Menu item标签：

<a href="MenuItemDisplay://CustTableListPage"><dynHelpAx:label axtype="MenuItem" axmenutype="Display" axmenuitem="CustTableListPage">All customers</dynHelpAx:label></a>

上面的例子中同时创建了一个链接，在Help view中点击时会在Client中打开相应的菜单对象。

发布帮助文件

帮助文件需要发布到Help server上才能使用，首先需要更改help server的web.config添加publisher Id，否则Help server不会索引：

    <publishers>
      <add publisherId="Microsoft" name="Microsoft" />
      <add publisherId="Contoso" name="Contoso" />
    </publishers>

这里Contoso是新添加的Publsiher，然后根据Publisher创建在Content下创建目录，然后根据语言创建相应的子目录：

C:\inetpub\wwwroot\DynamicsAX6HelpServer\Content\Contoso
C:\inetpub\wwwroot\DynamicsAX6HelpServer\Content\Contoso\EN-US

帮助文件可以直接放置到C:\inetpub\wwwroot\DynamicsAX6HelpServer\Content\Contoso\EN-US，也可以再创建子目录方便管理。把C:\inetpub\wwwroot\DynamicsAX6HelpServer\Content\Microsoft\EN-US\Local也拷贝到这个目录下以使用css和脚本。

Help server使用Windows search服务来索引帮助文件，确保该服务已经正常启动。帮助文件放置到Help server上后不需要太长时间就能在Help view中搜索到。

主题列表

要使帮助文件在Help view的主题列表中显示出来，需要创建主题列表文件TableOfContents.xml，典型的TableOfContents.xml类似：

<?xml version="1.0" encoding="utf-8"?>
<tableOfContents xmlns="http://schemas.microsoft.com/dynamicsHelp/2008/11" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <publisher>Contoso</publisher>
  <documentSet>UserDocumentation</documentSet>
  <ms.locale>EN-US</ms.locale>
  <entries>
    <entry>
      <text>Contoso help topic</text>
      <Microsoft.Help.F1>D7D800B6-93B3-4088-B214-722E503DE218</Microsoft.Help.F1>
      <children>
        <entry>
          <text>test</text>
          <Microsoft.Help.F1>D88E71BE-19A0-41F8-91C1-75F7675097AB</Microsoft.Help.F1>
        </entry>
      </children>
    </entry>
  </entries>
</tableOfContents>

entry标记引入一个帮助文件，使用F1 Id引用到帮助文件，Children标记引入子节点。F1 Id也可以使用AOT对象的F1 Id比如“Forms.CustTable”，如果多个帮助文件有相同的F1 Id，它们也都会被列出。TableOfContents.xml也需要发布到Help server，可以直接放到C:\inetpub\wwwroot\DynamicsAX6HelpServer\Content\Contoso\EN-US下，也可以创建一个子目录比如TOCResources来专门管理。发布TOCResources再打开Help view就能在左侧主题列表中看到相应的帮助文件。

总的来说AX2012的帮助服务还是很有用的，方便了帮助内容的管理，最大的好处是和Client的集成，在更新了AX程序功能后我们可以同时发布自定义的帮助内容，操作用户可以很方便的获取到帮助。