翻譯-ExcelDNA開發文檔

本文轉載自查看原文 2018-10-06 14:45 1734 Office 加載項/ 技術/ 翻譯/ 個人隨筆/ Office 外接程序/ Excel-DNA

轉載自個人主頁

前言

翻譯開源項目ExcelDNA開發文檔

異步處理

ExcelDNA支持兩種異步函數：

RTD，該函數適用與Excel2003及以上版本，（當你使用ExcelAsyncUtil.*時，RTD起作用）
本地Excel異步函數，使用Excel2010及以上版本（當你的函數使用ExcelAsyncHandle作為參數並且返回值為void時）

兩種方式的不同之處

RTD函數允許你在函數執行的時候，與Excel通信
本地異步函數，當函數已經被執行時，Excel只允許執行工作薄的其他部分。所以在單元格計算時，你不並能影響Excel。

RTD的使用方法之一是：ExcelAsyncUtil.Run。為了方便執行，ExcelDNA在內部定義了RTD服務（詳情）RTD服務允許ExcelDNA通知Excel，例如：在異步任務完成之后，該公式是否需要重新計算。

異步函數如下：

你定義一個異步函數在公式里
Excel需要重新計算，調用異步函數執行ExcelAsyncUtil.Run
使用ExcelAsyncUtil.Run 創建RTD主題（引用方法名和在參數中信息中在讓ExcelAsyncUtil.Run作為第一個參數）
ExcelAsyncUtil.Run 使異步工作開始，並且與RTD主題保持聯系
當持續計算時，ExcelAsyncUtil.Run會返回#N/A給UDF。
你的UDF會返回#N/A到Excel工作薄
當你工作完成時，ExcelDNA會發送標識讓RTD更新
當RTD出現錯誤時，Excel會在單元格上標記
Excel重新計算時，會讓單元格重新計算，會讓UDF重新被調用
UDF調用ExcelAsyncUtil.Run和之前的主題信息一致
ExcelAsyncUtil.Run查找在方法中存儲的主題和完成的值，它會直接返回值，如果找不到會返回#N/A
UDF函數會接收到結果值，並且將值返回給工作薄
由於ExcelAsyncUtil.Run不能再次調用Excel RTD方法，所以RTD主題會清空Excel內部的值

ExcelFunction 屬性

Name
Description
Category
HelpTopic
IsVolatile (! suffix)
IsHidden
IsExceptionSafe
IsMacroType (# suffix)
IsThreadSafe ($ suffix)
IsClusterSafe (& suffix)
ExplicitRegistration
SuppressOverwriteError

IsMacroType

是否使用宏類型
當IsMacroType=true時，ExcelDNA注冊該函數，會調用xlfRegister
Excel API Reference for xlfRegister。詳細說，如果IsMacroType=true，ExcelDNA會在pxTypeText后加"#"
相關文檔中如此描述

在pxTypeText最后一個參數加#，給函數相同的調用許可證，作為一個宏中的函數

函數會獲取在重新計算的循環中，尚未計算的單元格的值

這個函數可以調用任一xlm信息中的函數，例如：xlfGetCell

如果並沒有出現#符號

求並沒有計算的單元格的結果，會出現xlretUncalced 錯誤。一旦單元格被計算，當前函數會被再次調用

調用xlm中除xlfCaller以外的函數，會引發xlretInvXlfn錯誤

使用IsMacroType=true的一些弊端

如果不加"$"后綴，不能使用多線程，即使被標記了IsThreadSafe=true
如果他們包含至少一種參數，標記[ExcelArgument(AllowReference=true)]的類型參數，則Excel自動將函數視為不穩定性（即使函數被標記IsVolatile=false）

進一步看，我理解的是,在Excel計算期間,這些函數處理不同的線程，因此，你可能期待在工作薄計算時，會有一些變化，我並沒有引用也沒有重寫它。

我建議值在意料之外的案例中只設置IsMacroType=true，當你確定需要並且已經足夠了解時，你可以升級

IsThreadSafe

是否線程安全，設置為true時，意味着你的函數安全的多線程重新計算，如果在注冊字符串最后加上"$"符號，可以在內部調用xlfRegister

IsClusterSafe

是否集群安全，設置為true時，意味着你的函數在集群時安全
Cluster safe functions

IsExceptionSafe

是否異常安全，設置為true時，意味着無論何時出現未知的異常時，Excel應該崩潰，該參數最好忽略

ExcelArgumentAttribute

Name
Description
AllowReference

ExcelCommandAttribute

Name
Description (Unused)
HelpTopic (Unused)
ShortCut
MenuName
MenuText
IsExceptionSafe
ExplicitRegistration
SuppressOverwriteError

函數注冊

默認注冊

默認情況下，ExcelDNA所有的函數注冊方法必須是 public static,為的是能在.dna文件中訪問到，下面有兩個屬性，你可以放在.dna文件中便於控制你的注冊。

ExplicitExports

如果你僅僅想注冊一個方法並且明確的標志他是一個Excel方法或者Excel命令，你可以在.dna文件中假如 ExplicitExports='true'
例如：

<ExternalLibrary Path="MyFunctions.dll" Pack="true" ExplicitExports="true" />

這些屬性在.dna文件中的項目與類庫中的標記中是有效的

顯式注冊選項

如果你的AddIn明確的注冊（如果你要注冊一個擴展類庫），你可以在.dna文件中增加ExplicitRegisration='true'，在ExcelDNA中，並不會自動注冊任一個函數，並且你的AddIn可以使用ExcelIntegration.RegisterDelegates(...)被調用，
ExplicitRegistration選項運行允許明確的方法或者類庫退出默認的注冊處理，例如，方法或者類庫有explicitly register，則調用ExcelIntegration.RegisterXXX 方法中的其中一個

在ExcelFunctionAttribute 和ExcelCommandAttribute均有效
在.dna文件中的Project和ExternalLibrary中有效
當ExcelIntegration.RegisterMethods或者ExcelIntegration.RegisterDelegates被調用時，這些標志會在任一屬性被調用之前刪除

動態注冊

ExcelDNA自定義外部類庫，可以通過自定義方法與注冊線程，動態注冊函數，此處使用了委托，ExcelIntegration.RegisterDelegates。詳情

數據類型

以下是函數的參數以及返回值的類型

Double
String
DateTime -- 返回double類型到Excel (或許直接返回字符串會更好)
Double[] -- 如果只有一列,則取該列，否則將會使用該行
Double[,]
Object
Object[] -- 如果只有一列,則取該列，否則將會使用該行
Object[,]
Boolean (bool) -- 返回Excel布爾值 (返回一個字符串會更好)
Int32 (int)
Int16 (short)
UInt16 (ushort)
Decimal

傳入函數的參數類型，只允許傳入以下的參數:

Double
String
Boolean
ExcelDna.Integration.ExcelError
ExcelDna.Integration.ExcelMissing
ExcelDna.Integration.ExcelEmpty
Object[,] containing an array with a mixture of the above types
ExcelReference -- (只有 AllowReference=true 時)

參數類型為 Object[] 、 Object[,] 的函數將接受上述類型，返回類型如下:

Double
String
DateTime
Boolean
Double[]
Double[,]
Object[]
Object[,]
ExcelDna.Integration.ExcelError
ExcelDna.Integration.ExcelMissing.Value // Converted by Excel to be 0.0
ExcelDna.Integration.ExcelEmpty.Value // Converted by Excel to be 0.0
Int32 (int)
Int16 (short)
UInt16 (ushort)
Decimal
otherwise return #VALUE! error

自定義編譯輸出

當ExcelDna.AddInNuGet包被安裝在項目中，一些附加的編譯配置已經被定義好，此時，只需要Copy所需的.xll文件到輸出目錄，即可以創建一個用於插件的單獨的包。

安裝包會增加文件到項目中（Properties\ExcelDna.Build.props）。這個文件被用於自定義需要哪些附件。ExcelDna.Build.props允許配置一下內容

  <!--
    Configuration properties for building .dna files
  -->
  <PropertyGroup>
    <!--
      Enable/Disable automatic generation of platform-specific versions of .dna files
    -->
    <ExcelDnaCreate32BitAddIn Condition="'$(ExcelDnaCreate32BitAddIn)' == ''">true</ExcelDnaCreate32BitAddIn>
    <ExcelDnaCreate64BitAddIn Condition="'$(ExcelDnaCreate64BitAddIn)' == ''">true</ExcelDnaCreate64BitAddIn>

    <!--
      Define the suffix used for each platform-specific file e.g. MyAddIn64.dna
    -->
    <ExcelDna32BitAddInSuffix Condition="'$(ExcelDna32BitAddInSuffix)' == ''"></ExcelDna32BitAddInSuffix>
    <ExcelDna64BitAddInSuffix Condition="'$(ExcelDna64BitAddInSuffix)' == ''">64</ExcelDna64BitAddInSuffix>
  </PropertyGroup>

  <!--
    Configuration properties for packing .dna files
  -->
  <PropertyGroup>
    <!--
      Enable/Disable packing of .dna files
    -->
    <RunExcelDnaPack Condition="'$(RunExcelDnaPack)' == ''">true</RunExcelDnaPack>

    <!--
      Suffix used for packed .xll files e.g. MyAddIn-packed.xll
    -->
    <ExcelDnaPackXllSuffix Condition="'$(ExcelDnaPackXllSuffix)' == ''">-packed</ExcelDnaPackXllSuffix>
  </PropertyGroup>