Question

我有一个ExcelDNA项目，该项目在Excel中添加了带有udf函数的功能区。

使用ExcelDNA.Documentation为该项目创建了一些基本文档。但是我发现文档功能有限，并且我已经开始在其上使用Sandcastle。但是我无法让Sandcastle在每个函数上方找到XML注释。

以下是包含ExcelDNA和Sandcastle文档的简单函数：

/// <summary>
/// Returns the name of a chemical element.
/// </summary>
/// <param name="symbol">Symbol of an element</param>
/// <returns></returns>
[ExcelFunctionDoc(Name = "zAtomicName", Description = "Returns the name of a chemical element.", Category = "Chemistry", HelpTopic = "xxx.chm!2002")]
public static object zAtomicName([ExcelArgument(Name = "symbol", Description = "is the symbol of the element")] object input)
{

我需要ExcelDNA属性，因为它们在您选择功能时在Excel中显示为弹出帮助信息。

ExcelDNA属性是否阻止Sandcastle查找每个函数的XML注释？

Answer 1

我假设您正在使用Visual Studio。您知道-XML注释必须添加到代码中以记录各种类型及其成员。

此外，您必须为项目启用XML注释文件输出。

在解决方案资源管理器中，右键单击该项目，然后选择“属性”。
选择“构建属性”页面。
在“输出”部分中，选中“ Xml文档文件”文本框旁边的复选框，然后指定XML文件的名称。尽管不是必需的，但通常的约定是在相关程序集之后命名XML注释文件（扩展名为.xml的文件除外）。程序集名称可以在“应用程序”属性页面上找到。
如果您的解决方案包含多个需要记录的项目，请对解决方案中的每个项目重复上述步骤。建议您为每个项目的XML注释文件指定一个唯一的名称。

要使用沙堡，您将找到一个演练Creating Your First Project。

使用成功完成构建后的 清理中间文件 选项，可以使用Sandcastle来实现基础HTML文件的输出。

创建好的帮助内容非常耗时，并且需要学习。 我建议使用ExcelDna.Documentation，因为基础HTML文件已直接分配了文件名，并且已经生成了上下文ID（请参阅* .hhp文件中的[ALIAS]和[MAP]部分）。

[OPTIONS]
Compatibility=1.1 or later
Compiled file="Excel-DNA-Library-AddIn.chm"
Contents file=Table of Contents.hhc
Default topic=index.htm
Display compile progress=No
Language=0x409 English (United States)

[INFOTYPES]

[ALIAS]
Topic20000=MyAddTwoIntegers.htm
Topic10000=MyHelloWorld.htm

[MAP]
#define Topic20000 20000
#define Topic10000 10000

有关更多信息，我附加了以下示例代码和屏幕截图：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using ExcelDna.Integration;
using ExcelDna.Documentation;

namespace Excel_DNA_Library
{
    /// <summary>
    /// This code is only used as test case for Excel-DNA and Sandcastle XML-comments.
    /// </summary>
    /// <remarks>
    /// <para>This class can welcome you and add.</para>
    /// <para>Nothing else is possible.</para>
    /// </remarks>
    public class UDFHelper
    {
        /// <summary>
        /// <c>MyHelloWorld</c> - my first .NET function using Excel-DNA.
        /// </summary>
        /// <param name="name">Your first name.</param>/// 
        /// <returns>A welcome string and text from user input.</returns>
        /// <example>
        /// <code>
        /// =MyHelloWorld("www.help-info.de");
        /// </code>
        /// </example>
        [ExcelFunction( Name = "MyHelloWorld",
                        Category = "Text",
                        Description = "Welcome - my first .NET function using Excel-DNA.",
                        HelpTopic = "Excel-DNA-Library-AddIn.chm!10000")]

        public static string SayHello(string name)
        {
            return "You are welcome " + name;
        }

        /// <summary>
        /// <c>MyAddTwoIntegers</c> - my second .NET function using Excel-DNA.
        /// </summary>
        /// <param name="a">The first integer.</param>
        /// <param name="b">The second integer.</param>
        /// <returns>The sum of two integers.</returns>
        /// <example>
        /// <code>
        /// =MyAddTwoIntegers(4, 5);
        /// </code>
        /// </example>
        [ExcelFunctionDoc(Name = "MyAddTwoIntegers",
                          Category = "Math",
                          Description = "Add two integers - my second .NET function using Excel-DNA.",
                          HelpTopic = "Excel-DNA-Library-AddIn.chm!20000",
                          Summary = "really all it does is add two number ... I promise.",
                          Returns = "the sum of the two arguments")]            

        public static int Add(int a, int b)
        {
            return a + b;
        }

    }
}

使用ExcelDna.Documentation生成的CHM为：

已打开帮助查看器窗口的Excel用例：

使用Sandcastle生成的CHM为（请注意：此阶段不包括Context-ID！）

ExcelDNA项目中的Sandcastle文档

1 个答案: