翻譯-ExcelDNA開發文檔

轉載自我的主頁

前言

翻譯開源項目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>

相關連接

文檔地址