c# - ExcelDNA 项目中的 SandcaSTLe 文档

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 注释文件输出。

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

要使用 SandcaSTLe，您会找到演练 Creating Your First Project .

底层 HTML 文件的输出可以通过 SandcaSTLe 实现，而不是使用项目属性 > 构建中的成功构建后清除中间文件选项。

创建好的帮助内容非常耗时，并且有一个学习曲线。 我推荐使用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!)