├── SpecialTopics
├── DynamicArrays
│ ├── Examples.xlsx
│ ├── DynamicArrays.csproj
│ ├── DynamicArrays.sln
│ ├── ArrayMap.cs
│ ├── ExampleFunctions.cs
│ ├── ArrayResizer.cs
│ └── README.md
├── IntelliSenseForVBAFunctions
│ ├── TempFunctions.xlsm
│ ├── TempFunctionsWithDescriptions.xlsm
│ ├── TempFunctions.IntelliSense.xml
│ └── README.md
└── RTD
│ ├── TimerRTD
│ ├── TimerRTD.csproj
│ ├── Functions.cs
│ ├── TimerRTD.sln
│ ├── DataSources.cs
│ └── RtdServer.cs
│ └── README.md
├── Testing
├── TestingSample
│ ├── Sample.Test
│ │ ├── TestBook.xlsx
│ │ ├── Sample.Test.csproj
│ │ └── ExcelTests.cs
│ ├── Sample
│ │ ├── Sample.csproj
│ │ └── Functions.cs
│ └── TestingSample.sln
└── README.md
├── Fundamentals
├── ArgumentTypeBasics
│ ├── ArgumentTypeBasics.xlsm
│ ├── ArgumentTypeBasics.vbproj
│ ├── ArgumentTypeBasics.sln
│ └── Functions.vb
└── RibbonBasics
│ ├── RibbonResources
│ ├── MagicWand.png
│ ├── Ribbon.xml
│ ├── RibbonResources.Designer.vb
│ └── RibbonResources.resx
│ ├── Functions.vb
│ ├── My Project
│ ├── Settings.settings
│ ├── Application.Designer.vb
│ ├── Application.myapp
│ ├── AssemblyInfo.vb
│ ├── Resources.Designer.vb
│ ├── Settings.Designer.vb
│ └── Resources.resx
│ ├── Ribbon.vb
│ ├── RibbonBasics.vbproj
│ ├── RibbonBasics.sln
│ ├── RibbonFromResources.md
│ └── README.md
├── VBA-to-.NET
├── FormulaEvaluateConvert
│ ├── FormulaEvaluate
│ │ ├── Test.xlsx
│ │ ├── My Project
│ │ │ ├── launchSettings.json
│ │ │ ├── Settings.settings
│ │ │ ├── Application.Designer.vb
│ │ │ ├── Application.myapp
│ │ │ ├── AssemblyInfo.vb
│ │ │ ├── Resources.Designer.vb
│ │ │ ├── Settings.Designer.vb
│ │ │ └── Resources.resx
│ │ ├── FormulaEvaluate.vbproj
│ │ ├── mFunHelpers.vb
│ │ ├── mExcelHelpers.vb
│ │ └── mExcelMacros.vb
│ ├── OriginalFiles
│ │ ├── clsMathParser.cls
│ │ ├── mExcelMacros.bas
│ │ ├── mMathSpecFun.bas
│ │ └── Analisis Numerico y Macros en Excel.xlsm
│ ├── FormulaEvaluate.sln
│ └── FormulaEvaluateConvert.md
├── Readme.md
└── WebRequestBasics
│ └── Readme.md
├── README.md
├── GettingStarted
└── InstallVisualStudio.md
├── .gitattributes
└── .gitignore
/SpecialTopics/DynamicArrays/Examples.xlsx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/SpecialTopics/DynamicArrays/Examples.xlsx
--------------------------------------------------------------------------------
/Testing/TestingSample/Sample.Test/TestBook.xlsx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/Testing/TestingSample/Sample.Test/TestBook.xlsx
--------------------------------------------------------------------------------
/Fundamentals/ArgumentTypeBasics/ArgumentTypeBasics.xlsm:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/Fundamentals/ArgumentTypeBasics/ArgumentTypeBasics.xlsm
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/RibbonResources/MagicWand.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/Fundamentals/RibbonBasics/RibbonResources/MagicWand.png
--------------------------------------------------------------------------------
/SpecialTopics/IntelliSenseForVBAFunctions/TempFunctions.xlsm:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/SpecialTopics/IntelliSenseForVBAFunctions/TempFunctions.xlsm
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/Test.xlsx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/Test.xlsx
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/clsMathParser.cls:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/clsMathParser.cls
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/mExcelMacros.bas:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/mExcelMacros.bas
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/mMathSpecFun.bas:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/mMathSpecFun.bas
--------------------------------------------------------------------------------
/SpecialTopics/IntelliSenseForVBAFunctions/TempFunctionsWithDescriptions.xlsm:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/SpecialTopics/IntelliSenseForVBAFunctions/TempFunctionsWithDescriptions.xlsm
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/Analisis Numerico y Macros en Excel.xlsm:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Excel-DNA/Tutorials/HEAD/VBA-to-.NET/FormulaEvaluateConvert/OriginalFiles/Analisis Numerico y Macros en Excel.xlsm
--------------------------------------------------------------------------------
/Fundamentals/ArgumentTypeBasics/ArgumentTypeBasics.vbproj:
--------------------------------------------------------------------------------
1 |
2 |
3 | net472;net6.0-windows
4 |
5 |
6 |
7 |
8 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/Functions.vb:
--------------------------------------------------------------------------------
1 | Imports ExcelDna.Integration
2 |
3 | Public Module MyFunctions
4 |
5 |
6 | Public Function HelloDna(name As String) As String
7 | Return "Hello " & name
8 | End Function
9 |
10 | End Module
--------------------------------------------------------------------------------
/SpecialTopics/RTD/TimerRTD/TimerRTD.csproj:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | net472;net6.0-windows
5 |
6 |
7 |
8 |
9 |
10 |
11 |
--------------------------------------------------------------------------------
/Testing/TestingSample/Sample/Sample.csproj:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | net472;net6.0-windows
5 |
6 |
7 |
8 |
9 |
10 |
11 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/launchSettings.json:
--------------------------------------------------------------------------------
1 | {
2 | "profiles": {
3 | "Excel": {
4 | "commandName": "Executable",
5 | "executablePath": "C:\\Program Files\\Microsoft Office\\root\\Office16\\EXCEL.EXE",
6 | "commandLineArgs": "/x \"FormulaEvaluate-AddIn64.xll\""
7 | }
8 | }
9 | }
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/My Project/Settings.settings:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/Settings.settings:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
--------------------------------------------------------------------------------
/SpecialTopics/DynamicArrays/DynamicArrays.csproj:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | net472;net6.0-windows
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/FormulaEvaluate.vbproj:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | net472
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/RibbonResources/Ribbon.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/My Project/Application.Designer.vb:
--------------------------------------------------------------------------------
1 | '------------------------------------------------------------------------------
2 | '
3 | ' This code was generated by a tool.
4 | ' Runtime Version:4.0.30319.42000
5 | '
6 | ' Changes to this file may cause incorrect behavior and will be lost if
7 | ' the code is regenerated.
8 | '
9 | '------------------------------------------------------------------------------
10 |
11 | Option Strict On
12 | Option Explicit On
13 |
14 |
--------------------------------------------------------------------------------
/SpecialTopics/RTD/TimerRTD/Functions.cs:
--------------------------------------------------------------------------------
1 | using ExcelDna.Integration;
2 |
3 | namespace TimerRTD
4 | {
5 | public static class Functions
6 | {
7 | public static object TimerNow()
8 | {
9 | return XlCall.RTD("TimerRTD.RtdServer", null, "NOW");
10 | }
11 |
12 | public static object TimerWave(double amplitude, double frequency)
13 | {
14 | return XlCall.RTD("TimerRTD.RtdServer", null, "WAVE", amplitude.ToString(), frequency.ToString());
15 | }
16 | }
17 | }
18 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/My Project/Application.myapp:
--------------------------------------------------------------------------------
1 |
2 |
3 | false
4 | false
5 | 0
6 | true
7 | 0
8 | 1
9 | true
10 |
11 |
--------------------------------------------------------------------------------
/Testing/TestingSample/Sample/Functions.cs:
--------------------------------------------------------------------------------
1 | using System;
2 | using System.Collections.Generic;
3 | using System.Linq;
4 | using System.Text;
5 | using System.Threading.Tasks;
6 |
7 | namespace Sample
8 | {
9 | public static class Functions
10 | {
11 | public static double AddThem(double input1, double input2)
12 | {
13 | // Change the calculation here to give the 'wrong' values and re-run the tests.
14 | // return input1 + input2 - 1;
15 | return input1 + input2;
16 | }
17 | }
18 | }
19 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/Application.Designer.vb:
--------------------------------------------------------------------------------
1 | '------------------------------------------------------------------------------
2 | '
3 | ' This code was generated by a tool.
4 | ' Runtime Version:4.0.30319.42000
5 | '
6 | ' Changes to this file may cause incorrect behavior and will be lost if
7 | ' the code is regenerated.
8 | '
9 | '------------------------------------------------------------------------------
10 |
11 | Option Strict On
12 | Option Explicit On
13 |
14 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/Application.myapp:
--------------------------------------------------------------------------------
1 |
2 |
3 | false
4 | false
5 | 0
6 | true
7 | 0
8 | 1
9 | true
10 |
11 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/mFunHelpers.vb:
--------------------------------------------------------------------------------
1 | Imports System.Math
2 |
3 | Module mFunHelpers
4 | Function IsMissing(obj As Object) As Boolean
5 | IsMissing = obj Is Nothing
6 | End Function
7 |
8 | Function Sqr(d As Double)
9 | Sqr = d * d
10 | End Function
11 |
12 | Function Atn(d As Double)
13 | Atn = Atan(d)
14 | End Function
15 |
16 | Function Sgn(d As Double)
17 | Sgn = Sign(d)
18 | End Function
19 |
20 | Function MakeArray(ParamArray doubles() As Double) As Double()
21 | MakeArray = doubles
22 | End Function
23 | End Module
24 |
--------------------------------------------------------------------------------
/Testing/TestingSample/Sample.Test/Sample.Test.csproj:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | net472;net6.0-windows
5 | true
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 |
18 |
19 | PreserveNewest
20 |
21 |
22 |
23 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Tutorials
2 | Tutorial content and sample projects for Excel-DNA.
3 |
4 | ## Contents
5 |
6 | ### GettingStarted
7 | * [Installing Visual Studio](GettingStarted/InstallVisualStudio.md)
8 |
9 | ### Fundamentals
10 | * [UDF Argument Types in VBA and .NET](Fundamentals/ArgumentTypeBasics)
11 | * [Ribbon Basics](Fundamentals/RibbonBasics)
12 |
13 | ### Special Topics
14 | * [Dynamic Arrays](SpecialTopics/DynamicArrays)
15 | * [IntelliSense for VBA Functions](SpecialTopics/IntelliSenseForVBAFunctions)
16 | * [RTD](SpecialTopics/RTD)
17 |
18 | ### Testing
19 | * [Testing Helper Introduction](Testing)
20 |
21 | ## Topic ideas
22 | * All about arrays
23 | * IntelliSense inside and out
24 | * VBA to DNA (and back again)
25 | * Dealing with a deluge of data
26 |
--------------------------------------------------------------------------------
/VBA-to-.NET/Readme.md:
--------------------------------------------------------------------------------
1 | # VBA to .NET
2 |
3 | The **VBA to .NET** series discusses topics that might be of particular interest to programmers who are familiar with VBA and want to start using the .NET platform. General themes include
4 | * How to port code from VBA to VB.NET, and what the main differences are between these languages and environments.
5 | * How to perform common tasks in .NET where the libraries and code would be quite different to those used in VBA.
6 | * How to structure projects in .NET to use the code in a variety of ways - different platforms, in a cloud-hosted setting, or as an Excel add-in.
7 |
8 | ### [Web Request Basics](WebRequestBasics/Readme.md)
9 |
10 | A common programming task is to retrieve some information from a remote system via an HTTP web request. This tutorial gives a high-level view of how to aprroach this task, an example of how to get started with the simple case, and some pointers on where to look further.
11 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/Ribbon.vb:
--------------------------------------------------------------------------------
1 | Imports System.Runtime.InteropServices
2 | Imports Microsoft.Office.Interop.Excel
3 | Imports ExcelDna.Integration.CustomUI
4 | Imports ExcelDna.Integration
5 | Imports RibbonBasics.My.Resources
6 |
7 |
8 | Public Class Ribbon
9 | Inherits ExcelRibbon
10 |
11 | Public Overrides Function GetCustomUI(RibbonID As String) As String
12 | Return RibbonResources.Ribbon ' The name here is the resource name that the ribbon xml has in the RibbonResources resource file
13 | End Function
14 |
15 | Public Overrides Function LoadImage(imageId As String) As Object
16 | ' This will return the image resource with the name specified in the image='xxxx' tag
17 | Return RibbonResources.ResourceManager.GetObject(imageId)
18 | End Function
19 | Public Sub OnSayHelloPressed(control As IRibbonControl)
20 | Dim app As Application
21 | Dim rng As Range
22 |
23 | app = ExcelDnaUtil.Application
24 | rng = app.Range("A1")
25 | rng.Value = "Hello from .NET!"
26 |
27 | End Sub
28 |
29 | End Class
30 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/mExcelHelpers.vb:
--------------------------------------------------------------------------------
1 | Imports ExcelDna.Integration
2 | Imports Microsoft.Office.Interop.Excel
3 |
4 | Friend Module mExcelHelpers
5 |
6 | Public Application As Application = ExcelDnaUtil.Application
7 |
8 | Function Cells() As Range
9 | Cells = Application.Cells
10 | End Function
11 | Function Range(cell1 As Object) As Range
12 | Range = Application.Range(cell1)
13 | End Function
14 | Function Range(cell1 As Object, cell2 As Object) As Range
15 | Range = Application.Range(cell1, cell2)
16 | End Function
17 | Function Charts() As Sheets
18 | Charts = Application.Charts
19 | End Function
20 | Function ActiveChart() As Chart
21 | ActiveChart = Application.ActiveChart
22 | End Function
23 | Function Sheets() As Sheets
24 | Sheets = Application.Sheets
25 | End Function
26 | Function ActiveSheet() As Object
27 | ActiveSheet = Application.ActiveSheet
28 | End Function
29 | Function Selection() As Object
30 | Selection = Application.Selection
31 | End Function
32 |
33 | End Module
34 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/RibbonBasics.vbproj:
--------------------------------------------------------------------------------
1 |
2 |
3 | net472;net6.0-windows
4 | true
5 |
6 |
7 |
8 | PreserveNewest
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 | True
18 | True
19 | RibbonResources.resx
20 |
21 |
22 |
23 |
24 | My.Resources
25 | ResXFileCodeGenerator
26 | RibbonResources.Designer.vb
27 |
28 |
29 |
--------------------------------------------------------------------------------
/SpecialTopics/RTD/TimerRTD/TimerRTD.sln:
--------------------------------------------------------------------------------
1 |
2 | Microsoft Visual Studio Solution File, Format Version 12.00
3 | # Visual Studio Version 16
4 | VisualStudioVersion = 16.0.30717.126
5 | MinimumVisualStudioVersion = 10.0.40219.1
6 | Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TimerRTD", "TimerRTD.csproj", "{78EBE69C-1FDE-4A29-B18D-7D8024CC85E4}"
7 | EndProject
8 | Global
9 | GlobalSection(SolutionConfigurationPlatforms) = preSolution
10 | Debug|Any CPU = Debug|Any CPU
11 | Release|Any CPU = Release|Any CPU
12 | EndGlobalSection
13 | GlobalSection(ProjectConfigurationPlatforms) = postSolution
14 | {78EBE69C-1FDE-4A29-B18D-7D8024CC85E4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
15 | {78EBE69C-1FDE-4A29-B18D-7D8024CC85E4}.Debug|Any CPU.Build.0 = Debug|Any CPU
16 | {78EBE69C-1FDE-4A29-B18D-7D8024CC85E4}.Release|Any CPU.ActiveCfg = Release|Any CPU
17 | {78EBE69C-1FDE-4A29-B18D-7D8024CC85E4}.Release|Any CPU.Build.0 = Release|Any CPU
18 | EndGlobalSection
19 | GlobalSection(SolutionProperties) = preSolution
20 | HideSolutionNode = FALSE
21 | EndGlobalSection
22 | GlobalSection(ExtensibilityGlobals) = postSolution
23 | SolutionGuid = {FF2E304F-1AEE-4B2D-861E-5B90D4707CC4}
24 | EndGlobalSection
25 | EndGlobal
26 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/RibbonBasics.sln:
--------------------------------------------------------------------------------
1 |
2 | Microsoft Visual Studio Solution File, Format Version 12.00
3 | # Visual Studio Version 16
4 | VisualStudioVersion = 16.0.30517.126
5 | MinimumVisualStudioVersion = 10.0.40219.1
6 | Project("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "RibbonBasics", "RibbonBasics.vbproj", "{BC64C7ED-B1ED-4FF3-B286-041CC9D400FE}"
7 | EndProject
8 | Global
9 | GlobalSection(SolutionConfigurationPlatforms) = preSolution
10 | Debug|Any CPU = Debug|Any CPU
11 | Release|Any CPU = Release|Any CPU
12 | EndGlobalSection
13 | GlobalSection(ProjectConfigurationPlatforms) = postSolution
14 | {BC64C7ED-B1ED-4FF3-B286-041CC9D400FE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
15 | {BC64C7ED-B1ED-4FF3-B286-041CC9D400FE}.Debug|Any CPU.Build.0 = Debug|Any CPU
16 | {BC64C7ED-B1ED-4FF3-B286-041CC9D400FE}.Release|Any CPU.ActiveCfg = Release|Any CPU
17 | {BC64C7ED-B1ED-4FF3-B286-041CC9D400FE}.Release|Any CPU.Build.0 = Release|Any CPU
18 | EndGlobalSection
19 | GlobalSection(SolutionProperties) = preSolution
20 | HideSolutionNode = FALSE
21 | EndGlobalSection
22 | GlobalSection(ExtensibilityGlobals) = postSolution
23 | SolutionGuid = {B64813DD-EEAE-429C-AEBE-D08ED5A7CFA5}
24 | EndGlobalSection
25 | EndGlobal
26 |
--------------------------------------------------------------------------------
/SpecialTopics/DynamicArrays/DynamicArrays.sln:
--------------------------------------------------------------------------------
1 |
2 | Microsoft Visual Studio Solution File, Format Version 12.00
3 | # Visual Studio Version 16
4 | VisualStudioVersion = 16.0.30517.126
5 | MinimumVisualStudioVersion = 10.0.40219.1
6 | Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DynamicArrays", "DynamicArrays.csproj", "{86BCC618-6225-42CD-BD32-D0A188BF2489}"
7 | EndProject
8 | Global
9 | GlobalSection(SolutionConfigurationPlatforms) = preSolution
10 | Debug|Any CPU = Debug|Any CPU
11 | Release|Any CPU = Release|Any CPU
12 | EndGlobalSection
13 | GlobalSection(ProjectConfigurationPlatforms) = postSolution
14 | {86BCC618-6225-42CD-BD32-D0A188BF2489}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
15 | {86BCC618-6225-42CD-BD32-D0A188BF2489}.Debug|Any CPU.Build.0 = Debug|Any CPU
16 | {86BCC618-6225-42CD-BD32-D0A188BF2489}.Release|Any CPU.ActiveCfg = Release|Any CPU
17 | {86BCC618-6225-42CD-BD32-D0A188BF2489}.Release|Any CPU.Build.0 = Release|Any CPU
18 | EndGlobalSection
19 | GlobalSection(SolutionProperties) = preSolution
20 | HideSolutionNode = FALSE
21 | EndGlobalSection
22 | GlobalSection(ExtensibilityGlobals) = postSolution
23 | SolutionGuid = {9768A2E3-E831-4C21-8BF9-ACB8334777C6}
24 | EndGlobalSection
25 | EndGlobal
26 |
--------------------------------------------------------------------------------
/Fundamentals/ArgumentTypeBasics/ArgumentTypeBasics.sln:
--------------------------------------------------------------------------------
1 |
2 | Microsoft Visual Studio Solution File, Format Version 12.00
3 | # Visual Studio Version 16
4 | VisualStudioVersion = 16.0.30517.126
5 | MinimumVisualStudioVersion = 10.0.40219.1
6 | Project("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "ArgumentTypeBasics", "ArgumentTypeBasics.vbproj", "{DE0E5693-45DE-414F-BD36-E2BB27566EAD}"
7 | EndProject
8 | Global
9 | GlobalSection(SolutionConfigurationPlatforms) = preSolution
10 | Debug|Any CPU = Debug|Any CPU
11 | Release|Any CPU = Release|Any CPU
12 | EndGlobalSection
13 | GlobalSection(ProjectConfigurationPlatforms) = postSolution
14 | {DE0E5693-45DE-414F-BD36-E2BB27566EAD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
15 | {DE0E5693-45DE-414F-BD36-E2BB27566EAD}.Debug|Any CPU.Build.0 = Debug|Any CPU
16 | {DE0E5693-45DE-414F-BD36-E2BB27566EAD}.Release|Any CPU.ActiveCfg = Release|Any CPU
17 | {DE0E5693-45DE-414F-BD36-E2BB27566EAD}.Release|Any CPU.Build.0 = Release|Any CPU
18 | EndGlobalSection
19 | GlobalSection(SolutionProperties) = preSolution
20 | HideSolutionNode = FALSE
21 | EndGlobalSection
22 | GlobalSection(ExtensibilityGlobals) = postSolution
23 | SolutionGuid = {5D3363B5-4857-41B1-BF46-BD7009A586D5}
24 | EndGlobalSection
25 | EndGlobal
26 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate.sln:
--------------------------------------------------------------------------------
1 |
2 | Microsoft Visual Studio Solution File, Format Version 12.00
3 | # Visual Studio Version 16
4 | VisualStudioVersion = 16.0.31112.23
5 | MinimumVisualStudioVersion = 10.0.40219.1
6 | Project("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "FormulaEvaluate", "FormulaEvaluate\FormulaEvaluate.vbproj", "{2339F95A-6632-403F-9ED8-7CE80BB2CD04}"
7 | EndProject
8 | Global
9 | GlobalSection(SolutionConfigurationPlatforms) = preSolution
10 | Debug|Any CPU = Debug|Any CPU
11 | Release|Any CPU = Release|Any CPU
12 | EndGlobalSection
13 | GlobalSection(ProjectConfigurationPlatforms) = postSolution
14 | {2339F95A-6632-403F-9ED8-7CE80BB2CD04}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
15 | {2339F95A-6632-403F-9ED8-7CE80BB2CD04}.Debug|Any CPU.Build.0 = Debug|Any CPU
16 | {2339F95A-6632-403F-9ED8-7CE80BB2CD04}.Release|Any CPU.ActiveCfg = Release|Any CPU
17 | {2339F95A-6632-403F-9ED8-7CE80BB2CD04}.Release|Any CPU.Build.0 = Release|Any CPU
18 | EndGlobalSection
19 | GlobalSection(SolutionProperties) = preSolution
20 | HideSolutionNode = FALSE
21 | EndGlobalSection
22 | GlobalSection(ExtensibilityGlobals) = postSolution
23 | SolutionGuid = {2FDD05DA-2D03-4843-AB51-850AA0694CCC}
24 | EndGlobalSection
25 | EndGlobal
26 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/My Project/AssemblyInfo.vb:
--------------------------------------------------------------------------------
1 | Imports System
2 | Imports System.Reflection
3 | Imports System.Runtime.InteropServices
4 |
5 | ' General Information about an assembly is controlled through the following
6 | ' set of attributes. Change these attribute values to modify the information
7 | ' associated with an assembly.
8 |
9 | ' Review the values of the assembly attributes
10 |
11 | '
12 |
13 | '
14 | '
15 |
16 |
17 |
18 |
19 |
20 | 'The following GUID is for the ID of the typelib if this project is exposed to COM
21 |
22 |
23 | ' Version information for an assembly consists of the following four values:
24 | '
25 | ' Major Version
26 | ' Minor Version
27 | ' Build Number
28 | ' Revision
29 | '
30 | ' You can specify all the values or you can default the Build and Revision Numbers
31 | ' by using the '*' as shown below:
32 | '
33 |
34 | '
35 | '
36 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/AssemblyInfo.vb:
--------------------------------------------------------------------------------
1 | Imports System
2 | Imports System.Reflection
3 | Imports System.Runtime.InteropServices
4 |
5 | ' General Information about an assembly is controlled through the following
6 | ' set of attributes. Change these attribute values to modify the information
7 | ' associated with an assembly.
8 |
9 | ' Review the values of the assembly attributes
10 |
11 | '
12 |
13 | '
14 | '
15 |
16 |
17 |
18 |
19 |
20 | 'The following GUID is for the ID of the typelib if this project is exposed to COM
21 |
22 |
23 | ' Version information for an assembly consists of the following four values:
24 | '
25 | ' Major Version
26 | ' Minor Version
27 | ' Build Number
28 | ' Revision
29 | '
30 | ' You can specify all the values or you can default the Build and Revision Numbers
31 | ' by using the '*' as shown below:
32 | '
33 |
34 | '
35 | '
36 |
--------------------------------------------------------------------------------
/SpecialTopics/IntelliSenseForVBAFunctions/TempFunctions.IntelliSense.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 |
7 |
8 |
10 |
12 |
13 |
16 |
18 |
20 |
22 |
23 |
24 |
25 |
--------------------------------------------------------------------------------
/Testing/TestingSample/TestingSample.sln:
--------------------------------------------------------------------------------
1 |
2 | Microsoft Visual Studio Solution File, Format Version 12.00
3 | # Visual Studio Version 16
4 | VisualStudioVersion = 16.0.30621.155
5 | MinimumVisualStudioVersion = 10.0.40219.1
6 | Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sample.Test", "Sample.Test\Sample.Test.csproj", "{BF559676-9F49-4508-AAC7-AA824053ADF7}"
7 | EndProject
8 | Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sample", "Sample\Sample.csproj", "{057CA235-D5C9-40F7-BFDB-217C43B50469}"
9 | EndProject
10 | Global
11 | GlobalSection(SolutionConfigurationPlatforms) = preSolution
12 | Debug|Any CPU = Debug|Any CPU
13 | Release|Any CPU = Release|Any CPU
14 | EndGlobalSection
15 | GlobalSection(ProjectConfigurationPlatforms) = postSolution
16 | {BF559676-9F49-4508-AAC7-AA824053ADF7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
17 | {BF559676-9F49-4508-AAC7-AA824053ADF7}.Debug|Any CPU.Build.0 = Debug|Any CPU
18 | {BF559676-9F49-4508-AAC7-AA824053ADF7}.Release|Any CPU.ActiveCfg = Release|Any CPU
19 | {BF559676-9F49-4508-AAC7-AA824053ADF7}.Release|Any CPU.Build.0 = Release|Any CPU
20 | {057CA235-D5C9-40F7-BFDB-217C43B50469}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
21 | {057CA235-D5C9-40F7-BFDB-217C43B50469}.Debug|Any CPU.Build.0 = Debug|Any CPU
22 | {057CA235-D5C9-40F7-BFDB-217C43B50469}.Release|Any CPU.ActiveCfg = Release|Any CPU
23 | {057CA235-D5C9-40F7-BFDB-217C43B50469}.Release|Any CPU.Build.0 = Release|Any CPU
24 | EndGlobalSection
25 | GlobalSection(SolutionProperties) = preSolution
26 | HideSolutionNode = FALSE
27 | EndGlobalSection
28 | GlobalSection(ExtensibilityGlobals) = postSolution
29 | SolutionGuid = {B3A86753-D27E-43F0-A049-1C9E257E2662}
30 | EndGlobalSection
31 | EndGlobal
32 |
--------------------------------------------------------------------------------
/GettingStarted/InstallVisualStudio.md:
--------------------------------------------------------------------------------
1 | # Install Visual Studio
2 |
3 | [Visual Studio](https://visualstudio.microsoft.com) is the integrated development environment (IDE) used to develop .NET application and libraries, including Excel-DNA add-ins developed with .NET. I've made a step-by-step video guide that you can find on YouTube.
4 |
5 | [](http://www.youtube.com/watch?v=M-9jsOXVw_o "Excel-DNA - Install Visual Studio")
6 |
7 | Some notes are below.
8 |
9 | ### Notice the different 'Visual Studio' products and editions
10 |
11 | We are interested in the 'Visual Studio' product, and can then select one of the three editions to install.
12 |
13 | 
14 |
15 | Any of the three editions can be used for Excel-DNA developement.
16 | The Community and Professional editions have the same functionality, but differ in the cost and license restrictions. The Community edition is free but have limitation on use in Enterprise environments.
17 | [Details about Visual Studio editions](https://visualstudio.microsoft.com/vs/compare)
18 |
19 | ### Select the workload during installation
20 |
21 | During Visual Studio installation the main selection concerns the workloads and components to be installed.
22 |
23 | 
24 |
25 | For Excel-DNA development we require only the *.NET Desktop Development* workload to be installed. All the optional features may be deselected. Also note tate the *Office/Sharepoint tools* workload in not required for doing Excel-DNA development.
26 |
--------------------------------------------------------------------------------
/SpecialTopics/RTD/TimerRTD/DataSources.cs:
--------------------------------------------------------------------------------
1 | using System;
2 | using System.Timers;
3 |
4 | namespace TimerRTD
5 | {
6 | // Represents a streaming source of 'current time' updates,
7 | // implementd by a simple timer
8 | public class NowDataSource: IDisposable
9 | {
10 | // This event 'publishes' new values of 'Now'
11 | public event Action NewValue;
12 |
13 | // The backing Timer object - it fires from a ThreadPool thread
14 | readonly Timer _timer;
15 |
16 | public NowDataSource()
17 | {
18 | _timer = new Timer(100);
19 | _timer.Elapsed += (s, e) => NewValue(DateTime.Now);
20 | _timer.Start();
21 | }
22 |
23 | // We use the IDisposable pattern to clean up any 'data source' resources
24 | // It's not really needed in this case, but shows where a clean-up step might appear
25 | public void Dispose()
26 | {
27 | _timer.Dispose();
28 | }
29 | }
30 |
31 | public class WaveDataSource : IDisposable
32 | {
33 | // Publish an event that 'publishes' new random values
34 | public event Action NewValue;
35 |
36 | double _amplitude;
37 | double _frequency;
38 | DateTime _start;
39 | Timer _timer;
40 |
41 | public WaveDataSource(double amplitude, double frequency)
42 | {
43 | _amplitude = amplitude;
44 | _frequency = frequency;
45 | _start = DateTime.UtcNow;
46 | _timer = new Timer(100);
47 | _timer.Elapsed += (s, e) => NewValue?.Invoke(CurrentValue());
48 | _timer.Start();
49 | }
50 |
51 | double CurrentValue()
52 | {
53 | double t = (DateTime.UtcNow - _start).TotalSeconds;
54 | return _amplitude * Math.Sin(t * 2 * Math.PI * _frequency);
55 | }
56 |
57 | public void Dispose()
58 | {
59 | _timer.Dispose();
60 | }
61 | }
62 | }
63 |
--------------------------------------------------------------------------------
/SpecialTopics/RTD/TimerRTD/RtdServer.cs:
--------------------------------------------------------------------------------
1 | using System;
2 | using System.Collections.Generic;
3 | using System.Linq;
4 | using System.Runtime.InteropServices;
5 | using ExcelDna.Integration;
6 | using ExcelDna.Integration.Rtd;
7 |
8 | namespace TimerRTD
9 | {
10 | [ComVisible(true)]
11 | public class RtdServer : ExcelRtdServer
12 | {
13 | Dictionary _dataSources;
14 |
15 | protected override bool ServerStart()
16 | {
17 | _dataSources = new Dictionary();
18 | return true;
19 | }
20 |
21 | protected override object ConnectData(Topic topic, IList topicInfo, ref bool newValues)
22 | {
23 | var sourceName = topicInfo.FirstOrDefault();
24 | if (sourceName == "NOW")
25 | {
26 | var source = new NowDataSource();
27 | source.NewValue += dateTime => topic.UpdateValue($"{dateTime:HH:mm:ss}");
28 | _dataSources[topic] = source;
29 | return null; // We could also return an initial value
30 | }
31 |
32 | if (sourceName == "WAVE")
33 | {
34 | // Figure out the other topic parameters, which are strings in the topicInfo list.
35 | // No error - assume we have two extra topic strings and they are numbers
36 | double.TryParse(topicInfo[1], out double amplitude);
37 | double.TryParse(topicInfo[2], out double frequency);
38 | var source = new WaveDataSource(amplitude, frequency);
39 | source.NewValue += val => topic.UpdateValue(val);
40 | _dataSources[topic] = source;
41 | return null;
42 | }
43 |
44 | // This is unexpected and an error in our code - the RTD Server is used with our own wrapper functions
45 | throw new ArgumentOutOfRangeException(nameof(topicInfo), $"Unknown topic {sourceName}");
46 | }
47 |
48 | protected override void DisconnectData(Topic topic)
49 | {
50 | _dataSources[topic].Dispose();
51 | _dataSources.Remove(topic);
52 | }
53 |
54 | protected override void ServerTerminate()
55 | {
56 | // All topics will already have been Disconnected
57 | // We can do final clean-up here
58 | }
59 |
60 | }
61 | }
62 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/RibbonFromResources.md:
--------------------------------------------------------------------------------
1 | # Project layout with ribbon and images in a resources file
2 |
3 |
4 | An alternative approach is to add the .xml file in a separate file and embed as a resource in the add-in.
5 | For complicated projects, this might be a better structure.
6 |
7 | I'll put the ribbon xml file and related resources (like images we show in the ribbon) into a project folder called `RibbonResources`.
8 |
9 | Steps to add the `.xml` file as a resource:
10 | 1. Add a new folder under our project to hold our ribbon resources - called e.g. `RibbonResources`
11 | 2. Add a new xml file called `Ribbon.xml` with the following content inside the `RibbonResources` folder:
12 |
13 | ```xml
14 |
15 |
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 |
25 |
26 | ```
27 |
28 | 3. Add a new resources file to the project called `RibbonResources.resx`.
29 | 4. Into the resource file, `Add Existing File` and select the `RibbonResouces\Ribbon.xml` file. Check that it is called `Ribbon` - we'll use this name a bit later.
30 |
31 | 5. Take similar steps for an image, where the name of the image in the resources file matches the name in the `image` attribute in the ribbon markup.
32 |
33 | 6. The class will now explicitly get the ribbon markup and images from the resources class. It does this my overriding the `GetCustomUI` and `LoadImage` methods of the `ExcelRibbon` base class.
34 |
35 | ```vb
36 | Imports System.Runtime.InteropServices
37 | Imports ExcelDna.Integration.CustomUI
38 |
39 |
40 | Public Class Ribbon
41 | Inherits ExcelRibbon
42 |
43 | Public Overrides Function GetCustomUI(RibbonID As String) As String
44 | Return RibbonResources.Ribbon ' The name here is the resource name that the ribbon xml has in the RibbonResources resource file
45 | End Function
46 |
47 | Public Overrides Function LoadImage(imageId As String) As Object
48 | ' This will return the image resource with the name specified in the image='xxxx' tag
49 | Return RibbonResources.ResourceManager.GetObject(imageId)
50 | End Function
51 |
52 | Public Sub OnButtonPressed(control As IRibbonControl)
53 | MsgBox("Hello")
54 | End Sub
55 |
56 | End Class
57 | ```
58 |
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
1 | ###############################################################################
2 | # Set default behavior to automatically normalize line endings.
3 | ###############################################################################
4 | * text=auto
5 |
6 | ###############################################################################
7 | # Set default behavior for command prompt diff.
8 | #
9 | # This is need for earlier builds of msysgit that does not have it on by
10 | # default for csharp files.
11 | # Note: This is only used by command line
12 | ###############################################################################
13 | #*.cs diff=csharp
14 |
15 | ###############################################################################
16 | # Set the merge driver for project and solution files
17 | #
18 | # Merging from the command prompt will add diff markers to the files if there
19 | # are conflicts (Merging from VS is not affected by the settings below, in VS
20 | # the diff markers are never inserted). Diff markers may cause the following
21 | # file extensions to fail to load in VS. An alternative would be to treat
22 | # these files as binary and thus will always conflict and require user
23 | # intervention with every merge. To do so, just uncomment the entries below
24 | ###############################################################################
25 | #*.sln merge=binary
26 | #*.csproj merge=binary
27 | #*.vbproj merge=binary
28 | #*.vcxproj merge=binary
29 | #*.vcproj merge=binary
30 | #*.dbproj merge=binary
31 | #*.fsproj merge=binary
32 | #*.lsproj merge=binary
33 | #*.wixproj merge=binary
34 | #*.modelproj merge=binary
35 | #*.sqlproj merge=binary
36 | #*.wwaproj merge=binary
37 |
38 | ###############################################################################
39 | # behavior for image files
40 | #
41 | # image files are treated as binary by default.
42 | ###############################################################################
43 | #*.jpg binary
44 | #*.png binary
45 | #*.gif binary
46 |
47 | ###############################################################################
48 | # diff behavior for common document formats
49 | #
50 | # Convert binary document formats to text before diffing them. This feature
51 | # is only available from the command line. Turn it on by uncommenting the
52 | # entries below.
53 | ###############################################################################
54 | #*.doc diff=astextplain
55 | #*.DOC diff=astextplain
56 | #*.docx diff=astextplain
57 | #*.DOCX diff=astextplain
58 | #*.dot diff=astextplain
59 | #*.DOT diff=astextplain
60 | #*.pdf diff=astextplain
61 | #*.PDF diff=astextplain
62 | #*.rtf diff=astextplain
63 | #*.RTF diff=astextplain
64 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/My Project/Resources.Designer.vb:
--------------------------------------------------------------------------------
1 | '------------------------------------------------------------------------------
2 | '
3 | ' This code was generated by a tool.
4 | ' Runtime Version:4.0.30319.42000
5 | '
6 | ' Changes to this file may cause incorrect behavior and will be lost if
7 | ' the code is regenerated.
8 | '
9 | '------------------------------------------------------------------------------
10 |
11 | Option Strict On
12 | Option Explicit On
13 |
14 |
15 | Namespace My.Resources
16 |
17 | 'This class was auto-generated by the StronglyTypedResourceBuilder
18 | 'class via a tool like ResGen or Visual Studio.
19 | 'To add or remove a member, edit your .ResX file then rerun ResGen
20 | 'with the /str option, or rebuild your VS project.
21 | '''
22 | ''' A strongly-typed resource class, for looking up localized strings, etc.
23 | '''
24 | _
28 | Friend Module Resources
29 |
30 | Private resourceMan As Global.System.Resources.ResourceManager
31 |
32 | Private resourceCulture As Global.System.Globalization.CultureInfo
33 |
34 | '''
35 | ''' Returns the cached ResourceManager instance used by this class.
36 | '''
37 | _
38 | Friend ReadOnly Property ResourceManager() As Global.System.Resources.ResourceManager
39 | Get
40 | If Object.ReferenceEquals(resourceMan, Nothing) Then
41 | Dim temp As Global.System.Resources.ResourceManager = New Global.System.Resources.ResourceManager("RibbonBasics.Resources", GetType(Resources).Assembly)
42 | resourceMan = temp
43 | End If
44 | Return resourceMan
45 | End Get
46 | End Property
47 |
48 | '''
49 | ''' Overrides the current thread's CurrentUICulture property for all
50 | ''' resource lookups using this strongly typed resource class.
51 | '''
52 | _
53 | Friend Property Culture() As Global.System.Globalization.CultureInfo
54 | Get
55 | Return resourceCulture
56 | End Get
57 | Set(ByVal value As Global.System.Globalization.CultureInfo)
58 | resourceCulture = value
59 | End Set
60 | End Property
61 | End Module
62 | End Namespace
63 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/Resources.Designer.vb:
--------------------------------------------------------------------------------
1 | '------------------------------------------------------------------------------
2 | '
3 | ' This code was generated by a tool.
4 | ' Runtime Version:4.0.30319.42000
5 | '
6 | ' Changes to this file may cause incorrect behavior and will be lost if
7 | ' the code is regenerated.
8 | '
9 | '------------------------------------------------------------------------------
10 |
11 | Option Strict On
12 | Option Explicit On
13 |
14 |
15 | Namespace My.Resources
16 |
17 | 'This class was auto-generated by the StronglyTypedResourceBuilder
18 | 'class via a tool like ResGen or Visual Studio.
19 | 'To add or remove a member, edit your .ResX file then rerun ResGen
20 | 'with the /str option, or rebuild your VS project.
21 | '''
22 | ''' A strongly-typed resource class, for looking up localized strings, etc.
23 | '''
24 | _
28 | Friend Module Resources
29 |
30 | Private resourceMan As Global.System.Resources.ResourceManager
31 |
32 | Private resourceCulture As Global.System.Globalization.CultureInfo
33 |
34 | '''
35 | ''' Returns the cached ResourceManager instance used by this class.
36 | '''
37 | _
38 | Friend ReadOnly Property ResourceManager() As Global.System.Resources.ResourceManager
39 | Get
40 | If Object.ReferenceEquals(resourceMan, Nothing) Then
41 | Dim temp As Global.System.Resources.ResourceManager = New Global.System.Resources.ResourceManager("FormulaEvaluate.Resources", GetType(Resources).Assembly)
42 | resourceMan = temp
43 | End If
44 | Return resourceMan
45 | End Get
46 | End Property
47 |
48 | '''
49 | ''' Overrides the current thread's CurrentUICulture property for all
50 | ''' resource lookups using this strongly typed resource class.
51 | '''
52 | _
53 | Friend Property Culture() As Global.System.Globalization.CultureInfo
54 | Get
55 | Return resourceCulture
56 | End Get
57 | Set(ByVal value As Global.System.Globalization.CultureInfo)
58 | resourceCulture = value
59 | End Set
60 | End Property
61 | End Module
62 | End Namespace
63 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/My Project/Settings.Designer.vb:
--------------------------------------------------------------------------------
1 | '------------------------------------------------------------------------------
2 | '
3 | ' This code was generated by a tool.
4 | ' Runtime Version:4.0.30319.42000
5 | '
6 | ' Changes to this file may cause incorrect behavior and will be lost if
7 | ' the code is regenerated.
8 | '
9 | '------------------------------------------------------------------------------
10 |
11 | Option Strict On
12 | Option Explicit On
13 |
14 |
15 | Namespace My
16 |
17 | _
20 | Partial Friend NotInheritable Class MySettings
21 | Inherits Global.System.Configuration.ApplicationSettingsBase
22 |
23 | Private Shared defaultInstance As MySettings = CType(Global.System.Configuration.ApplicationSettingsBase.Synchronized(New MySettings), MySettings)
24 |
25 | #Region "My.Settings Auto-Save Functionality"
26 | #If _MyType = "WindowsForms" Then
27 | Private Shared addedHandler As Boolean
28 |
29 | Private Shared addedHandlerLockObject As New Object
30 |
31 | _
32 | Private Shared Sub AutoSaveSettings(ByVal sender As Global.System.Object, ByVal e As Global.System.EventArgs)
33 | If My.Application.SaveMySettingsOnExit Then
34 | My.Settings.Save()
35 | End If
36 | End Sub
37 | #End If
38 | #End Region
39 |
40 | Public Shared ReadOnly Property [Default]() As MySettings
41 | Get
42 |
43 | #If _MyType = "WindowsForms" Then
44 | If Not addedHandler Then
45 | SyncLock addedHandlerLockObject
46 | If Not addedHandler Then
47 | AddHandler My.Application.Shutdown, AddressOf AutoSaveSettings
48 | addedHandler = True
49 | End If
50 | End SyncLock
51 | End If
52 | #End If
53 | Return defaultInstance
54 | End Get
55 | End Property
56 | End Class
57 | End Namespace
58 |
59 | Namespace My
60 |
61 | _
64 | Friend Module MySettingsProperty
65 |
66 | _
67 | Friend ReadOnly Property Settings() As Global.RibbonBasics.My.MySettings
68 | Get
69 | Return Global.RibbonBasics.My.MySettings.Default
70 | End Get
71 | End Property
72 | End Module
73 | End Namespace
74 |
--------------------------------------------------------------------------------
/Testing/TestingSample/Sample.Test/ExcelTests.cs:
--------------------------------------------------------------------------------
1 | using System;
2 | using Xunit;
3 | using ExcelDna.Testing;
4 | using Microsoft.Office.Interop.Excel;
5 | using ExcelDna.Integration;
6 |
7 | namespace Sample.Test
8 | {
9 | // The path give here is relative to the output directory of the test project.
10 | // Setting an AddIn options here will request the test runner to load this add-in into Excel before the tests start.
11 | // The name here excludes the ".xll" or "64.xll" suffix. The test runner will choose according to the Excel bitness where it runs.
12 | #if NETFRAMEWORK
13 | [ExcelTestSettings(AddIn = @"..\..\..\..\Sample\bin\Debug\net6.0-windows\Sample-AddIn")]
14 | #else
15 | [ExcelTestSettings(AddIn = @"..\..\..\..\Sample\bin\Debug\net472\Sample-AddIn")]
16 | #endif
17 |
18 | public class ExcelTests : IDisposable
19 | {
20 | // This workbook will be available to all tests in the class
21 | Workbook _testWorkbook;
22 |
23 | // The test class constructor will configure the required environment for the tests in the class.
24 | // In this case it creates a new Workbook that will be shared by the tests
25 | public ExcelTests()
26 | {
27 | var app = Util.Application;
28 | _testWorkbook = app.Workbooks.Add();
29 | }
30 |
31 | // Clean-up for the class is in the IDisposable.Dispose implementation
32 | public void Dispose()
33 | {
34 | _testWorkbook.Close(SaveChanges: false);
35 | }
36 |
37 | // This test just interacts with Excel
38 | [ExcelFact]
39 | public void ExcelCanAddNumbers()
40 | {
41 | Worksheet ws = (Worksheet) _testWorkbook.Sheets[1];
42 |
43 | ws.Range["A1"].Value = 2.0;
44 | ws.Range["A2"].Value = 3.0;
45 | ws.Range["A3"].Formula = "=A1 + A2";
46 |
47 | var result = ws.Range["A3"].Value;
48 |
49 | Assert.Equal(5.0, result);
50 | }
51 |
52 | // This test depends on the AddIn value set in the class's ExcelTestSettings attributes
53 | // With the Sample-AddIn loaded, the function should work correctly.
54 | [ExcelFact]
55 | public void AddInCanAddNumbers()
56 | {
57 | Worksheet ws = (Worksheet) _testWorkbook.Sheets[1];
58 |
59 | ws.Range["A1"].Value = 2.0;
60 | ws.Range["A2"].Value = 3.0;
61 | ws.Range["A3"].Formula = "=AddThem(A1, A2)";
62 |
63 | var result = ws.Range["A3"].Value;
64 |
65 | Assert.Equal(5.0, result);
66 | }
67 |
68 | // Before this test is run, a pre-created workbook will be loaded
69 | // It has been added to the test project and configured to always be copied to the output directory
70 | [ExcelFact(Workbook = "TestBook.xlsx")]
71 | public void WorkbookCheckIsOK()
72 | {
73 | // Get the pre-loaded workbook using the Util.Workbook property
74 | var wb = Util.Workbook;
75 | Worksheet ws = (Worksheet) wb.Sheets["Check"];
76 | Util.Application.CalculateFull();
77 |
78 | var result = ws.Range["A1"].Value;
79 |
80 | Assert.Equal("OK", result);
81 | }
82 | }
83 | }
84 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/Settings.Designer.vb:
--------------------------------------------------------------------------------
1 | '------------------------------------------------------------------------------
2 | '
3 | ' This code was generated by a tool.
4 | ' Runtime Version:4.0.30319.42000
5 | '
6 | ' Changes to this file may cause incorrect behavior and will be lost if
7 | ' the code is regenerated.
8 | '
9 | '------------------------------------------------------------------------------
10 |
11 | Option Strict On
12 | Option Explicit On
13 |
14 |
15 | Namespace My
16 |
17 | _
20 | Partial Friend NotInheritable Class MySettings
21 | Inherits Global.System.Configuration.ApplicationSettingsBase
22 |
23 | Private Shared defaultInstance As MySettings = CType(Global.System.Configuration.ApplicationSettingsBase.Synchronized(New MySettings), MySettings)
24 |
25 | #Region "My.Settings Auto-Save Functionality"
26 | #If _MyType = "WindowsForms" Then
27 | Private Shared addedHandler As Boolean
28 |
29 | Private Shared addedHandlerLockObject As New Object
30 |
31 | _
32 | Private Shared Sub AutoSaveSettings(ByVal sender As Global.System.Object, ByVal e As Global.System.EventArgs)
33 | If My.Application.SaveMySettingsOnExit Then
34 | My.Settings.Save()
35 | End If
36 | End Sub
37 | #End If
38 | #End Region
39 |
40 | Public Shared ReadOnly Property [Default]() As MySettings
41 | Get
42 |
43 | #If _MyType = "WindowsForms" Then
44 | If Not addedHandler Then
45 | SyncLock addedHandlerLockObject
46 | If Not addedHandler Then
47 | AddHandler My.Application.Shutdown, AddressOf AutoSaveSettings
48 | addedHandler = True
49 | End If
50 | End SyncLock
51 | End If
52 | #End If
53 | Return defaultInstance
54 | End Get
55 | End Property
56 | End Class
57 | End Namespace
58 |
59 | Namespace My
60 |
61 | _
64 | Friend Module MySettingsProperty
65 |
66 | _
67 | Friend ReadOnly Property Settings() As Global.FormulaEvaluate.My.MySettings
68 | Get
69 | Return Global.FormulaEvaluate.My.MySettings.Default
70 | End Get
71 | End Property
72 | End Module
73 | End Namespace
74 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/RibbonResources/RibbonResources.Designer.vb:
--------------------------------------------------------------------------------
1 | '------------------------------------------------------------------------------
2 | '
3 | ' This code was generated by a tool.
4 | ' Runtime Version:4.0.30319.42000
5 | '
6 | ' Changes to this file may cause incorrect behavior and will be lost if
7 | ' the code is regenerated.
8 | '
9 | '------------------------------------------------------------------------------
10 |
11 | Option Strict On
12 | Option Explicit On
13 |
14 | Imports System
15 |
16 | Namespace My.Resources
17 |
18 | 'This class was auto-generated by the StronglyTypedResourceBuilder
19 | 'class via a tool like ResGen or Visual Studio.
20 | 'To add or remove a member, edit your .ResX file then rerun ResGen
21 | 'with the /str option, or rebuild your VS project.
22 | '''
23 | ''' A strongly-typed resource class, for looking up localized strings, etc.
24 | '''
25 | _
28 | Friend Class RibbonResources
29 |
30 | Private Shared resourceMan As Global.System.Resources.ResourceManager
31 |
32 | Private Shared resourceCulture As Global.System.Globalization.CultureInfo
33 |
34 | _
35 | Friend Sub New()
36 | MyBase.New
37 | End Sub
38 |
39 | '''
40 | ''' Returns the cached ResourceManager instance used by this class.
41 | '''
42 | _
43 | Friend Shared ReadOnly Property ResourceManager() As Global.System.Resources.ResourceManager
44 | Get
45 | If Object.ReferenceEquals(resourceMan, Nothing) Then
46 | Dim temp As Global.System.Resources.ResourceManager = New Global.System.Resources.ResourceManager("RibbonBasics.RibbonResources", GetType(RibbonResources).Assembly)
47 | resourceMan = temp
48 | End If
49 | Return resourceMan
50 | End Get
51 | End Property
52 |
53 | '''
54 | ''' Overrides the current thread's CurrentUICulture property for all
55 | ''' resource lookups using this strongly typed resource class.
56 | '''
57 | _
58 | Friend Shared Property Culture() As Global.System.Globalization.CultureInfo
59 | Get
60 | Return resourceCulture
61 | End Get
62 | Set
63 | resourceCulture = value
64 | End Set
65 | End Property
66 |
67 | '''
68 | ''' Looks up a localized resource of type System.Drawing.Bitmap.
69 | '''
70 | Friend Shared ReadOnly Property MagicWand() As System.Drawing.Bitmap
71 | Get
72 | Dim obj As Object = ResourceManager.GetObject("MagicWand", resourceCulture)
73 | Return CType(obj,System.Drawing.Bitmap)
74 | End Get
75 | End Property
76 |
77 | '''
78 | ''' Looks up a localized string similar to <?xml version="1.0" encoding="utf-8" ?>
79 | '''<customUI xmlns='http://schemas.microsoft.com/office/2009/07/customui' loadImage='LoadImage'>
80 | ''' <ribbon>
81 | ''' <tabs>
82 | ''' <tab id='tab1' label='My Tab'>
83 | ''' <group id='group1' label='My Group'>
84 | ''' <button id='button1' label='My Button' onAction='OnButtonPressed' image='MagicWand'/>
85 | ''' </group>
86 | ''' </tab>
87 | ''' </tabs>
88 | ''' </ribbon>
89 | '''</customUI>.
90 | '''
91 | Friend Shared ReadOnly Property Ribbon() As String
92 | Get
93 | Return ResourceManager.GetString("Ribbon", resourceCulture)
94 | End Get
95 | End Property
96 | End Class
97 | End Namespace
98 |
--------------------------------------------------------------------------------
/SpecialTopics/DynamicArrays/ArrayMap.cs:
--------------------------------------------------------------------------------
1 | using System;
2 | using ExcelDna.Integration;
3 | using static ExcelDna.Integration.XlCall;
4 |
5 | public static class ArrayMapFunctions
6 | {
7 | // This helper function is converted from https://github.com/Excel-DNA/Samples/blob/master/ArrayMap/Functions.vb
8 | [ExcelFunction(Description = "Evaluates the two-argument function for every value in the first and second inputs. " + "Takes a single value and any rectangle, or one row and one column, or one column and one row.")]
9 | public static object dnaArrayMap2([ExcelArgument(Description = "The function to evaluate - either enter the name without any quotes or brackets (for .xll functions), or as a string (for VBA functions)")] object function, [ExcelArgument(Description = "The input value(s) for the first argument (row, column or rectangular range) ")] object input1, [ExcelArgument(Description = "The input value(s) for the second argument (row, column or rectangular range) ")] object input2)
10 | {
11 | {
12 | Func evaluate;
13 | if (function is double)
14 | {
15 | evaluate = (x, y) => Excel(xlUDF, function, x, y);
16 | }
17 | else if (function is string)
18 | {
19 | // First try to get the RegisterId, if it's an .xll UDF
20 | object registerId;
21 | registerId = Excel(xlfEvaluate, function);
22 | if (registerId is double)
23 | {
24 | evaluate = (x, y) => Excel(xlUDF, registerId, x, y);
25 | }
26 | else
27 | {
28 | // Just call as string, hoping it's a valid VBA function
29 | evaluate = (x, y) => Excel(xlUDF, function, x, y);
30 | }
31 | }
32 | else
33 | {
34 | return ExcelError.ExcelErrorValue;
35 | }
36 |
37 | // Check for the case where one of the arguments is not an array, so we evaluate as a 1D function
38 | if (!(input1 is object[,] inputArr1))
39 | {
40 | object evaluate1(object x) => evaluate(input1, x);
41 | return ArrayEvaluate(evaluate1, input2);
42 | }
43 | if (!(input2 is object[,] inputArr2))
44 | {
45 | object evaluate1(object x) => evaluate(x, input2);
46 | return ArrayEvaluate(evaluate1, input1);
47 | }
48 |
49 | // Otherwise we now have the function to evaluate, and two arrays
50 | return ArrayEvaluate2(evaluate, inputArr1, inputArr2);
51 | }
52 | }
53 |
54 | private static object[,] ArrayEvaluate2(Func evaluate, object[,] inputArr1, object[,] inputArr2)
55 | {
56 |
57 | // Now we know both input1 and input2 are arrays
58 | // We assume they are 1D, else we'll do our best to combine - the exact rules might be decided more carefully
59 | if (inputArr1.GetLength(0) > 1)
60 | {
61 | // Lots of rows in input1, we'll take its first column only, and take the columns of input2
62 | var rows = inputArr1.GetLength(0);
63 | var cols = inputArr2.GetLength(1);
64 |
65 | var output = new object[rows, cols];
66 | for (int i = 0; i < rows; i++)
67 | for (int j = 0; j < cols; j++)
68 | output[i, j] = evaluate(inputArr1[i, 0], inputArr2[0, j]);
69 |
70 | return output;
71 | }
72 | else
73 | {
74 |
75 | // Single row in input1, we'll take its columns, and take the rows from input2
76 | var rows = inputArr2.GetLength(0);
77 | var cols = inputArr1.GetLength(1);
78 |
79 | var output = new object[rows, cols];
80 | for (int i = 0; i < rows; i++)
81 | for (int j = 0; j < cols; j++)
82 | output[i, j] = evaluate(inputArr1[0, j], inputArr2[i, 0]);
83 |
84 | return output;
85 | }
86 | }
87 |
88 | private static object ArrayEvaluate(Func evaluate, object input)
89 | {
90 | if (input is object[,] inputArr)
91 | {
92 | var rows = inputArr.GetLength(0);
93 | var cols = inputArr.GetLength(1);
94 | var output = new object[rows, cols];
95 |
96 | for (int i = 0; i < rows; i++)
97 | for (int j = 0; j < cols; j++)
98 | output[i, j] = evaluate(inputArr[i, j]);
99 |
100 | return output;
101 | }
102 | else
103 | {
104 | return evaluate(input);
105 | }
106 | }
107 | }
108 |
--------------------------------------------------------------------------------
/SpecialTopics/DynamicArrays/ExampleFunctions.cs:
--------------------------------------------------------------------------------
1 | using System;
2 | using System.Threading;
3 | using ExcelDna.Integration;
4 |
5 | public static class ExampleFunctions
6 | {
7 | // Returns a rows x cols sized array with some values
8 | public static object[,] dnaMakeArray(int rows, int cols)
9 | {
10 | object[,] result = new object[rows, cols];
11 | for (int i = 0; i < rows; i++)
12 | {
13 | for (int j = 0; j < cols; j++)
14 | {
15 | result[i, j] = $"{i},{j}";
16 | }
17 | }
18 | return result;
19 | }
20 |
21 | // Describes the size of the input array
22 | public static object dnaDescribeArray(object[,] input)
23 | {
24 | var rows = input.GetLength(0);
25 | var cols = input.GetLength(1);
26 |
27 | return $"Input: {rows} rows, {cols} columns";
28 | }
29 |
30 | public static object dnaAddPrefix(string prefix, object[,] input)
31 | {
32 | var rows = input.GetLength(0);
33 | var cols = input.GetLength(1);
34 |
35 | var result = new object[rows, cols];
36 | for (int i = 0; i < rows; i++)
37 | {
38 | for (int j = 0; j < cols; j++)
39 | {
40 | result[i,j] = $"{prefix}{input[i, j]}";
41 | }
42 | }
43 | return result;
44 | }
45 |
46 | public static double dnaAddThem(double val1, double val2)
47 | {
48 | return val1 + val2;
49 | }
50 |
51 | // To implement an array-aware function, we sometimes need to decide how to process various size combinations
52 | public static object[,] dnaConcatenate(string separator, object[,] val1, object[,] val2)
53 | {
54 | int rows1 = val1.GetLength(0);
55 | int cols1 = val1.GetLength(1);
56 | int rows2 = val2.GetLength(0);
57 | int cols2 = val2.GetLength(1);
58 |
59 | if (rows1 == rows2 && cols1 == cols2)
60 | {
61 | // Same shapes, operate elementwise
62 | object[,] result = new object[rows1, cols1];
63 | for (int i = 0; i < rows1; i++)
64 | {
65 | for (int j = 0; j < cols1; j++)
66 | {
67 | result[i, j] = $"{val1[i, j]}{separator}{val2[i, j]}";
68 | }
69 | }
70 | return result;
71 | }
72 |
73 | if (rows1 > 1)
74 | {
75 | // Lots of rows in input1, we'll take its first column only, and take the columns of input2
76 | var rows = rows1;
77 | var cols = cols2;
78 |
79 | var output = new object[rows, cols];
80 | for (int i = 0; i < rows; i++)
81 | for (int j = 0; j < cols; j++)
82 | output[i, j] = $"{val1[i, 0]}{separator}{val2[0, j]}";
83 |
84 | return output;
85 | }
86 | else
87 | {
88 |
89 | // Single row in input1, we'll take its columns, and take the rows from input2
90 | var rows = rows2;
91 | var cols = cols1;
92 |
93 | var output = new object[rows, cols];
94 | for (int i = 0; i < rows; i++)
95 | for (int j = 0; j < cols; j++)
96 | output[i, j] = $"{val1[0, j]}{separator}{val2[i, 0]}";
97 |
98 | return output;
99 | }
100 | }
101 |
102 | // Functions can take ExcelReference references, as well as return them
103 | // On the sheet the ExcelReference result will be converted to the values,
104 | // but when input to another function, the ExcelReference is passed directly
105 | public static object dnaArrayGetHead([ExcelArgument(AllowReference = true)] object input, int numRows)
106 | {
107 | if (input is ExcelReference inputRef)
108 | {
109 | var rowFirst = inputRef.RowFirst;
110 | var rowLast = Math.Min(inputRef.RowFirst + numRows, inputRef.RowLast);
111 | return new ExcelReference(rowFirst, rowLast, inputRef.ColumnFirst, inputRef.ColumnLast, inputRef.SheetId);
112 | }
113 | else if (input is object[,] inputArray)
114 | {
115 | var rows = inputArray.GetLength(0);
116 | var cols = inputArray.GetLength(1);
117 |
118 | var resultRows = Math.Min(rows, numRows);
119 | var result = new object[resultRows, cols];
120 | for (int i = 0; i < resultRows; i++)
121 | {
122 | for (int j = 0; j < cols; j++)
123 | {
124 | result[i, j] = inputArray[i, j];
125 | }
126 | }
127 | return result;
128 | }
129 | else
130 | {
131 | // Just a scalar value
132 | if (numRows >= 1)
133 | {
134 | return input;
135 | }
136 | }
137 | // Otherwise we have an error - return #VALUE!
138 | return ExcelError.ExcelErrorValue;
139 | }
140 |
141 | // RTD-based async and streaming functions work correctly with dyncami arrays
142 | public static object dnaMakeArrayAsync(int delayMs, int rows, int cols)
143 | {
144 | var funcName = nameof(dnaMakeArrayAsync);
145 | var args = new object[] { delayMs, rows, cols };
146 |
147 | return ExcelAsyncUtil.Run(funcName, args, () =>
148 | {
149 | Thread.Sleep(delayMs);
150 | object[,] result = new object[rows, cols];
151 | for (int i = 0; i < rows; i++)
152 | {
153 | for (int j = 0; j < cols; j++)
154 | {
155 | result[i, j] = $"{i}|{j}";
156 | }
157 | }
158 | return result;
159 | });
160 | }
161 | }
162 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/My Project/Resources.resx:
--------------------------------------------------------------------------------
1 |
2 |
3 |
62 |
63 |
64 |
65 |
66 |
67 |
68 |
69 |
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 |
78 |
79 |
80 |
81 |
82 |
83 |
84 |
85 |
86 |
87 |
88 |
89 |
90 |
91 |
92 |
93 |
94 |
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 | text/microsoft-resx
107 |
108 |
109 | 2.0
110 |
111 |
112 | System.Resources.ResXResourceReader, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
113 |
114 |
115 | System.Resources.ResXResourceWriter, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
116 |
117 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/My Project/Resources.resx:
--------------------------------------------------------------------------------
1 |
2 |
3 |
62 |
63 |
64 |
65 |
66 |
67 |
68 |
69 |
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 |
78 |
79 |
80 |
81 |
82 |
83 |
84 |
85 |
86 |
87 |
88 |
89 |
90 |
91 |
92 |
93 |
94 |
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 | text/microsoft-resx
107 |
108 |
109 | 2.0
110 |
111 |
112 | System.Resources.ResXResourceReader, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
113 |
114 |
115 | System.Resources.ResXResourceWriter, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
116 |
117 |
--------------------------------------------------------------------------------
/Fundamentals/ArgumentTypeBasics/Functions.vb:
--------------------------------------------------------------------------------
1 | Imports ExcelDna.Integration
2 |
3 | Public Module Functions
4 |
5 | ' Provides information about the data type and value that is passed in as argument
6 | Public Function dnaArgumentInfo(arg As Object) As String
7 |
8 | If TypeOf arg Is ExcelMissing Then
9 | Return "<>"
10 | ElseIf TypeOf arg Is ExcelEmpty Then
11 | Return "<>"
12 | ElseIf TypeOf arg Is Double Then
13 | Return "Double: " & CDbl(arg)
14 | ElseIf TypeOf arg Is String Then
15 | Return "String: " & CStr(arg)
16 | ElseIf TypeOf arg Is Boolean Then
17 | Return "Boolean: " & CBool(arg)
18 | ElseIf TypeOf arg Is ExcelError Then
19 | Return "ExcelError: " & arg.ToString()
20 | ElseIf TypeOf arg Is Object(,) Then
21 | ' The object array returned here may contain a mixture of different types,
22 | ' corresponding to the different cell contents.
23 | ' Arrays received will always be 0-based 2D arrays
24 | Dim argArray(,) As Object = arg
25 | Return String.Format("Array({0},{1})", argArray.GetLength(0), argArray.GetLength(1))
26 | Else
27 | Return "!? Unheard Of ?!"
28 | End If
29 |
30 | End Function
31 |
32 |
33 | ' Adding the AllowReference:=True flag means we can also accept sheet references
34 | Public Function dnaArgumentInfoAllowRef( arg As Object) As String
35 |
36 | If TypeOf arg Is ExcelReference Then
37 | Dim argRef As ExcelReference = arg
38 |
39 | ' We could construct a COM Range object from the ExcelReference if we needed to access some of the Range information
40 | ' For now we just read the values, and call the normal description function to describe the values at the sheet reference
41 | Return "Reference " & argRef.ToString() & ": " & dnaArgumentInfo(argRef.GetValue())
42 | Else
43 | Return dnaArgumentInfo(arg)
44 | End If
45 |
46 | End Function
47 |
48 | ' The parameter type is declared as a 2D array.
49 | ' The function can take a single value, or any rectangular range as input.
50 | ' Union references with multiple areas will only pass in the first area
51 | Public Function dnaSumEvenNumbers2D(arg(,) As Object) As Double
52 |
53 | Dim sum As Double = 0
54 | Dim rows As Integer
55 | Dim cols As Integer
56 |
57 | rows = arg.GetLength(0)
58 | cols = arg.GetLength(1)
59 |
60 | For i As Integer = 0 To rows - 1
61 | For j As Integer = 0 To cols - 1
62 |
63 | Dim val As Object = arg(i, j)
64 | If val Mod 2 = 0 Then
65 | sum += val
66 | End If
67 |
68 | Next
69 | Next
70 |
71 | Return sum
72 |
73 | End Function
74 |
75 | ' The parameter type is declared as a 1D array.
76 | ' The function can take a single value, a single row or a single column
77 | ' If a 2D range with more than one row and column is passed in, only the first row will be passed in here
78 | Public Function dnaSumEvenNumbers1D(arg() As Object) As Double
79 |
80 | Dim sum As Double = 0
81 | Dim val As Object
82 |
83 | For Each val In arg
84 | If val Mod 2 = 0 Then
85 | sum += val
86 | End If
87 | Next
88 |
89 | Return sum
90 |
91 | End Function
92 |
93 | ' The parameter type is declared as a 1D double array.
94 | ' If the values passed in cannot be converted to numbers, Excel will return a #VALUE! error to the sheet
95 | Public Function dnaSumEvenNumbersDouble1D(arg() As Double) As Double
96 |
97 | Dim sum As Double = 0
98 |
99 | For i As Integer = 0 To arg.Length - 1 ' Alternative to `For Each ...` for going through the array
100 |
101 | Dim val As Object = arg(i)
102 | If val Mod 2 = 0 Then
103 | sum += val
104 | End If
105 |
106 | Next
107 |
108 | Return sum
109 |
110 | End Function
111 |
112 | ' The parameter type is declared as a 2D double array.
113 | ' If the values passed in cannot be converted to numbers, Excel will return a #VALUE! error to the sheet
114 | Public Function dnaSumEvenNumbersDouble2D(arg(,) As Double) As Double
115 |
116 | Dim sum As Double = 0
117 | Dim rows As Integer
118 | Dim cols As Integer
119 |
120 | rows = arg.GetLength(0)
121 | cols = arg.GetLength(1)
122 |
123 | For i As Integer = 0 To rows - 1
124 | For j As Integer = 0 To cols - 1
125 |
126 | Dim val As Object = arg(i, j)
127 | If val Mod 2 = 0 Then
128 | sum += val
129 | End If
130 |
131 | Next
132 | Next
133 |
134 | Return sum
135 |
136 | End Function
137 |
138 | ' The parameter type is declared as Object, and marked with the AllowReference:=True flag
139 | ' The function can take a single value, or any sheet reference as input
140 | ' Sheet references might be to union ranges with multiple areas, which we process individually
141 | Public Function dnaSumEvenNumbersR( arg As Object)
142 | Dim sum As Double
143 |
144 | If TypeOf arg Is ExcelReference Then
145 |
146 | ' To be really careful, we get the 2D array of values from each of the areas in the reference
147 | ' This lets the function suppport union ranges as input correctly
148 | Dim argRef As ExcelReference = arg
149 | For Each rect In argRef.InnerReferences
150 | sum += dnaSumEvenNumbers2D(rect.GetValue())
151 | Next
152 | ElseIf TypeOf arg Is Object(,) Then
153 | ' We can call the array implementation directly
154 | sum = dnaSumEvenNumbers2D(arg)
155 | Else
156 | ' Just check and return the value
157 | If arg Mod 2 = 0 Then
158 | sum = arg
159 | End If
160 | End If
161 | Return sum
162 | End Function
163 |
164 | End Module
165 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluateConvert.md:
--------------------------------------------------------------------------------
1 | # Example: Convert Formula Evaluate
2 |
3 | ## Notes
4 | * New project - Visual Basic "Class Library (.NET Framework)"
5 | * Wrap code in `Public Class` (except the `Option Explicit On`)
6 | * `Private Type` to [`Private Structure`](https://docs.microsoft.com/en-us/dotnet/visual-basic/programming-guide/language-features/data-types/how-to-declare-a-structure)
7 | * Add `Dim` / `Public` to fields in the Structure
8 | * `Property Get` to [`Property`](https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/property-statement) and [`Get`](https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/get-statement)
9 | * From
10 | ```vb
11 | Public Property Get Expression() As String
12 | Expression = Expr
13 | End Property
14 | ```
15 | * To
16 | ```vb
17 | Public ReadOnly Property Expression() As String
18 | Get
19 | Expression = Expr
20 | End Get
21 | End Property
22 | ```
23 | * `Property Let` to [`Property`](https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/property-statement) and [`Set`](https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/set-statement)
24 | * From
25 | ```vb
26 | Public Property Let VarValue(ByVal Index As Long, ByVal VarVal As Double)
27 | If Index <= VTtop Then
28 | VT(Index).Value = VarVal
29 | VT(Index).Init = True
30 | iInit = iInit + 1
31 | End If
32 | End Property
33 | ```
34 | * To
35 | ```vb
36 | Public WriteOnly Property VarValue(ByVal Index As Long) As Double
37 | Set(ByVal VarVal As Double)
38 | If Index <= VTtop Then
39 | VT(Index).Value = VarVal
40 | VT(Index).Init = True
41 | iInit = iInit + 1
42 | End If
43 | End Set
44 | End Property
45 | ```
46 |
47 | * Add brackets to function calls where needed
48 | * From `Err.Raise 1001, "MathParser", ErrMsg` to `Err.Raise(1001, "MathParser", ErrMsg)`
49 | * From `Catch_Sign SubExpr, Sign` to `Catch_Sign(SubExpr, Sign)`
50 |
51 | * Add explicit type to parameters when one of the parameters has a type
52 | * From `Public Function EvalMulti(ByRef VarValue() As Double, Optional ByVal VarName)` to `Public Function EvalMulti(ByRef VarValue() As Double, Optional ByVal VarName As Object)`
53 |
54 | * Optional / `IsMissing` pattern
55 | * Approach 1:
56 | * From
57 | ```vb
58 | Public Function EvalMulti(ByRef VarValue() As Double, Optional ByVal VarName)
59 | ...
60 | If IsMissing(VarName) Then
61 | ....
62 | ```
63 | * To adding the parameter type and assigning a default of Nothing, then checking this
64 | ```vb
65 | Public Function EvalMulti(ByRef VarValue() As Double, Optional ByVal VarName As Object = Nothing)
66 | ...
67 | If VarName Is Nothing Then
68 | ....
69 | ```
70 | * Approach 2:
71 | * Add the right default to the function declaration and remove the IsMissing()
72 |
73 | * Approach 3:
74 | * Define a function `IsMissing()` As
75 | ```vb
76 | Private Function IsMissing(obj As Object) As Boolean
77 | IsMissing = obj Is Nothing
78 | End Function
79 | ```
80 | and still add default value for the optional parameters.
81 |
82 |
83 | * `If Err() <> 0 Then` to `If Err.Number <> 0 Then`
84 |
85 | * Remove Set for assignment
86 |
87 | * Escape keywords with [] brackets: `Dim char As String` to `Dim [char] As String`
88 |
89 | * Undo VS formatting for
90 | * From `.FunTok = GetFunTok(Of Char)()` to `.FunTok = GetFunTok([char])`
91 |
92 | * Don't mix type characters and explicit types
93 | * From
94 | ```vb
95 | Dim n&, i&, j&, k&, p&, count_iter&, Node_dup As Boolean
96 | ```
97 | * To
98 | ```vb
99 | Dim n&, i&, j&, k&, p&, count_iter&
100 | Dim Node_dup As Boolean
101 | ```
102 | * Add `Imports System.Math`
103 |
104 | * Define `Sqr`
105 |
106 | * `Variant` to `Object`
107 |
108 | * Take care with array dimensions in declarations
109 | * From
110 | ```vb
111 | Sub ET_Dump(ByRef ETable() As Variant)
112 | ReDim ETable(ETtop, 30)
113 | ```
114 | * To
115 | ```vb
116 | Sub ET_Dump(ByRef ETable(,) As Object)
117 | ReDim ETable(ETtop, 30)
118 | ```
119 |
120 | * `Option Private Module` to `Friend Module ...`
121 |
122 | * Rewrite `Array(...)` function calls with `MakeArray` helper function
123 | ```vb
124 | Private Function MakeArray(ParamArray doubles() As Double) As Double()
125 | MakeArray = doubles
126 | End Function
127 | ```
128 | Could also do
129 | `MyArray = New Double() { 1.1, 1.2, 1.3}`
130 |
131 | * Remove type from ReDim calls
132 | `ReDim BI(n) As Double, DI(n) As Double, BK(n) As Double, DK(n) As Double`
133 | to
134 | `ReDim BI(n) : ReDim DI(n) : ReDim BK(n) : ReDim DK(n)`
135 |
136 | * Date processing
137 | ```vb
138 | Select Case UCase$(SymbConst)
139 | Case "DATE" 'or date
140 | retval = CDbl(Date)
141 | Case "TIME" 'or time
142 | retval = CDbl(Time)
143 | Case "NOW" 'or now
144 | retval = CDbl(Now)
145 | ```
146 | to
147 | ```vb
148 | Select Case UCase$(SymbConst)
149 | Case "DATE" 'or date
150 | retval = DateTime.Today.ToOADate()
151 | Case "TIME" 'or time
152 | retval = (DateTime.MinValue + (DateTime.Now - DateTime.Today)).ToOADate()
153 | Case "NOW" 'or now
154 | retval = DateTime.Now.ToOADate()
155 | ```
156 |
157 | *
158 | ```vb
159 | ris = DateSerial(.Arg(1).Value, .Arg(2).Value, .Arg(3).Value).ToOADate()
160 | ```
161 | to
162 | ```vb
163 | ris = DateSerial(.Arg(1).Value, .Arg(2).Value, .Arg(3).Value).ToOADate()
164 | ```
165 |
166 | *
167 | ```vb
168 | Case symYear : ris = Year(CDate(a))
169 | ```
170 | to
171 | ```vb
172 | Case symYear : ris = Year(DateTime.FromOADate(a))
173 | ```
174 |
175 | * Make sure Optional parameters have a default
176 | ```vb
177 | Private Function cvDegree(ByVal DMS As String, ByRef angle As Double, Optional ByRef sMsg As String = Nothing) As Boolean
178 | ```
179 | to
180 | ```vb
181 | Private Function cvDegree(ByVal DMS As String, ByRef angle As Double, Optional ByRef sMsg As String = Nothing) As Boolean
182 | ```
183 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/RibbonResources/RibbonResources.resx:
--------------------------------------------------------------------------------
1 |
2 |
3 |
62 |
63 |
64 |
65 |
66 |
67 |
68 |
69 |
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 |
78 |
79 |
80 |
81 |
82 |
83 |
84 |
85 |
86 |
87 |
88 |
89 |
90 |
91 |
92 |
93 |
94 |
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 |
107 |
108 |
109 | text/microsoft-resx
110 |
111 |
112 | 2.0
113 |
114 |
115 | System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
116 |
117 |
118 | System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
119 |
120 |
121 |
122 | MagicWand.png;System.Drawing.Bitmap, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
123 |
124 |
125 | Ribbon.xml;System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089;utf-8
126 |
127 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | ## Ignore Visual Studio temporary files, build results, and
2 | ## files generated by popular Visual Studio add-ons.
3 | ##
4 | ## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
5 |
6 | # User-specific files
7 | *.rsuser
8 | *.suo
9 | *.user
10 | *.userosscache
11 | *.sln.docstates
12 |
13 | # User-specific files (MonoDevelop/Xamarin Studio)
14 | *.userprefs
15 |
16 | # Build results
17 | [Dd]ebug/
18 | [Dd]ebugPublic/
19 | [Rr]elease/
20 | [Rr]eleases/
21 | x64/
22 | x86/
23 | [Aa][Rr][Mm]/
24 | [Aa][Rr][Mm]64/
25 | bld/
26 | [Bb]in/
27 | [Oo]bj/
28 | [Ll]og/
29 |
30 | # Visual Studio 2015/2017 cache/options directory
31 | .vs/
32 | # Uncomment if you have tasks that create the project's static files in wwwroot
33 | #wwwroot/
34 |
35 | # Visual Studio 2017 auto generated files
36 | Generated\ Files/
37 |
38 | # MSTest test Results
39 | [Tt]est[Rr]esult*/
40 | [Bb]uild[Ll]og.*
41 |
42 | # NUNIT
43 | *.VisualState.xml
44 | TestResult.xml
45 |
46 | # Build Results of an ATL Project
47 | [Dd]ebugPS/
48 | [Rr]eleasePS/
49 | dlldata.c
50 |
51 | # Benchmark Results
52 | BenchmarkDotNet.Artifacts/
53 |
54 | # .NET Core
55 | project.lock.json
56 | project.fragment.lock.json
57 | artifacts/
58 |
59 | # StyleCop
60 | StyleCopReport.xml
61 |
62 | # Files built by Visual Studio
63 | *_i.c
64 | *_p.c
65 | *_h.h
66 | *.ilk
67 | *.meta
68 | *.obj
69 | *.iobj
70 | *.pch
71 | *.pdb
72 | *.ipdb
73 | *.pgc
74 | *.pgd
75 | *.rsp
76 | *.sbr
77 | *.tlb
78 | *.tli
79 | *.tlh
80 | *.tmp
81 | *.tmp_proj
82 | *_wpftmp.csproj
83 | *.log
84 | *.vspscc
85 | *.vssscc
86 | .builds
87 | *.pidb
88 | *.svclog
89 | *.scc
90 |
91 | # Chutzpah Test files
92 | _Chutzpah*
93 |
94 | # Visual C++ cache files
95 | ipch/
96 | *.aps
97 | *.ncb
98 | *.opendb
99 | *.opensdf
100 | *.sdf
101 | *.cachefile
102 | *.VC.db
103 | *.VC.VC.opendb
104 |
105 | # Visual Studio profiler
106 | *.psess
107 | *.vsp
108 | *.vspx
109 | *.sap
110 |
111 | # Visual Studio Trace Files
112 | *.e2e
113 |
114 | # TFS 2012 Local Workspace
115 | $tf/
116 |
117 | # Guidance Automation Toolkit
118 | *.gpState
119 |
120 | # ReSharper is a .NET coding add-in
121 | _ReSharper*/
122 | *.[Rr]e[Ss]harper
123 | *.DotSettings.user
124 |
125 | # JustCode is a .NET coding add-in
126 | .JustCode
127 |
128 | # TeamCity is a build add-in
129 | _TeamCity*
130 |
131 | # DotCover is a Code Coverage Tool
132 | *.dotCover
133 |
134 | # AxoCover is a Code Coverage Tool
135 | .axoCover/*
136 | !.axoCover/settings.json
137 |
138 | # Visual Studio code coverage results
139 | *.coverage
140 | *.coveragexml
141 |
142 | # NCrunch
143 | _NCrunch_*
144 | .*crunch*.local.xml
145 | nCrunchTemp_*
146 |
147 | # MightyMoose
148 | *.mm.*
149 | AutoTest.Net/
150 |
151 | # Web workbench (sass)
152 | .sass-cache/
153 |
154 | # Installshield output folder
155 | [Ee]xpress/
156 |
157 | # DocProject is a documentation generator add-in
158 | DocProject/buildhelp/
159 | DocProject/Help/*.HxT
160 | DocProject/Help/*.HxC
161 | DocProject/Help/*.hhc
162 | DocProject/Help/*.hhk
163 | DocProject/Help/*.hhp
164 | DocProject/Help/Html2
165 | DocProject/Help/html
166 |
167 | # Click-Once directory
168 | publish/
169 |
170 | # Publish Web Output
171 | *.[Pp]ublish.xml
172 | *.azurePubxml
173 | # Note: Comment the next line if you want to checkin your web deploy settings,
174 | # but database connection strings (with potential passwords) will be unencrypted
175 | *.pubxml
176 | *.publishproj
177 |
178 | # Microsoft Azure Web App publish settings. Comment the next line if you want to
179 | # checkin your Azure Web App publish settings, but sensitive information contained
180 | # in these scripts will be unencrypted
181 | PublishScripts/
182 |
183 | # NuGet Packages
184 | *.nupkg
185 | # The packages folder can be ignored because of Package Restore
186 | **/[Pp]ackages/*
187 | # except build/, which is used as an MSBuild target.
188 | !**/[Pp]ackages/build/
189 | # Uncomment if necessary however generally it will be regenerated when needed
190 | #!**/[Pp]ackages/repositories.config
191 | # NuGet v3's project.json files produces more ignorable files
192 | *.nuget.props
193 | *.nuget.targets
194 |
195 | # Microsoft Azure Build Output
196 | csx/
197 | *.build.csdef
198 |
199 | # Microsoft Azure Emulator
200 | ecf/
201 | rcf/
202 |
203 | # Windows Store app package directories and files
204 | AppPackages/
205 | BundleArtifacts/
206 | Package.StoreAssociation.xml
207 | _pkginfo.txt
208 | *.appx
209 |
210 | # Visual Studio cache files
211 | # files ending in .cache can be ignored
212 | *.[Cc]ache
213 | # but keep track of directories ending in .cache
214 | !?*.[Cc]ache/
215 |
216 | # Others
217 | ClientBin/
218 | ~$*
219 | *~
220 | *.dbmdl
221 | *.dbproj.schemaview
222 | *.jfm
223 | *.pfx
224 | *.publishsettings
225 | orleans.codegen.cs
226 |
227 | # Including strong name files can present a security risk
228 | # (https://github.com/github/gitignore/pull/2483#issue-259490424)
229 | #*.snk
230 |
231 | # Since there are multiple workflows, uncomment next line to ignore bower_components
232 | # (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
233 | #bower_components/
234 |
235 | # RIA/Silverlight projects
236 | Generated_Code/
237 |
238 | # Backup & report files from converting an old project file
239 | # to a newer Visual Studio version. Backup files are not needed,
240 | # because we have git ;-)
241 | _UpgradeReport_Files/
242 | Backup*/
243 | UpgradeLog*.XML
244 | UpgradeLog*.htm
245 | ServiceFabricBackup/
246 | *.rptproj.bak
247 |
248 | # SQL Server files
249 | *.mdf
250 | *.ldf
251 | *.ndf
252 |
253 | # Business Intelligence projects
254 | *.rdl.data
255 | *.bim.layout
256 | *.bim_*.settings
257 | *.rptproj.rsuser
258 | *- Backup*.rdl
259 |
260 | # Microsoft Fakes
261 | FakesAssemblies/
262 |
263 | # GhostDoc plugin setting file
264 | *.GhostDoc.xml
265 |
266 | # Node.js Tools for Visual Studio
267 | .ntvs_analysis.dat
268 | node_modules/
269 |
270 | # Visual Studio 6 build log
271 | *.plg
272 |
273 | # Visual Studio 6 workspace options file
274 | *.opt
275 |
276 | # Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
277 | *.vbw
278 |
279 | # Visual Studio LightSwitch build output
280 | **/*.HTMLClient/GeneratedArtifacts
281 | **/*.DesktopClient/GeneratedArtifacts
282 | **/*.DesktopClient/ModelManifest.xml
283 | **/*.Server/GeneratedArtifacts
284 | **/*.Server/ModelManifest.xml
285 | _Pvt_Extensions
286 |
287 | # Paket dependency manager
288 | .paket/paket.exe
289 | paket-files/
290 |
291 | # FAKE - F# Make
292 | .fake/
293 |
294 | # JetBrains Rider
295 | .idea/
296 | *.sln.iml
297 |
298 | # CodeRush personal settings
299 | .cr/personal
300 |
301 | # Python Tools for Visual Studio (PTVS)
302 | __pycache__/
303 | *.pyc
304 |
305 | # Cake - Uncomment if you are using it
306 | # tools/**
307 | # !tools/packages.config
308 |
309 | # Tabs Studio
310 | *.tss
311 |
312 | # Telerik's JustMock configuration file
313 | *.jmconfig
314 |
315 | # BizTalk build output
316 | *.btp.cs
317 | *.btm.cs
318 | *.odx.cs
319 | *.xsd.cs
320 |
321 | # OpenCover UI analysis results
322 | OpenCover/
323 |
324 | # Azure Stream Analytics local run output
325 | ASALocalRun/
326 |
327 | # MSBuild Binary and Structured Log
328 | *.binlog
329 |
330 | # NVidia Nsight GPU debugger configuration file
331 | *.nvuser
332 |
333 | # MFractors (Xamarin productivity tool) working folder
334 | .mfractor/
335 |
336 | # Local History for Visual Studio
337 | .localhistory/
338 |
339 | # BeatPulse healthcheck temp database
340 | healthchecksdb
341 | /Fundamentals/ArgumentTypeBasics/My Project/launchSettings.json
342 |
--------------------------------------------------------------------------------
/Fundamentals/RibbonBasics/README.md:
--------------------------------------------------------------------------------
1 | # Ribbon Basics
2 |
3 | In this tutorial we will add a ribbon extension to an Excel-DNA add-in.
4 | The Office ribbon extensions are defined in an .xml markup format which we will add to the project.
5 | Then we define a class to process the ribbon callback methods, to react to commands like a button press.
6 |
7 | For this tutorial I will use a Visual Basic add-in; everything works similar in a C# project.
8 |
9 | There are some more advanced topics not covered in this tutorial:
10 | * Show how to change or enable elements of the interface based on some internal state.
11 | * Request a ribbon interface update from an event handler or external trigger.
12 | * Compare the native ribbon interface we use here, with the high-level wrapper provided by VSTO.
13 | * Explain internals of how the ribbon implementation works in Excel-DNA.
14 |
15 | ## Prepare
16 |
17 | Our starting point is a simple Excel-DNA add-in that declares a single UDF as a test.
18 | To prepare the environment for working on the ribbon extensions, we add two steps.
19 |
20 | 1. Install XML schemas (optional)
21 |
22 | To get IntelliSense help for the ribbon extension, we can either
23 | * install the `Excel-DNA XML Schemas` extension to Visual Studio, or
24 | * install the `ExcelDna.XmlSchemas` package in our add-in.
25 |
26 | The first approach requires admin permissions on the machine, but has the advantage of not adding any extra files to the project and only being done once.
27 |
28 | 2. Configure Excel to show interface errors (optional)
29 |
30 | Excel has a setting to display any errors in interface extensions like the ribbon. Enabling this settings is a great help while developing a ribbon extension.
31 | It can be found under **Tools -> Options -> Advanced: Show add-in user interface errors**.
32 |
33 | 
34 |
35 | ## Add the ribbon xml markup
36 |
37 | We now add a new `.xml` file to the project, which we will add to the .dna configuration file. This approach allows us to easily edit the .xml file in Visual Studio and is good for a simple add-in. Two other options for locating the same xml information are:
38 | * Put the xml text inline in the ribbon handler class.
39 | * Put the xml content in a separate file embedded in a resource.
40 |
41 | For more complicated add-ins, I prefer putting keeping the xml content in a separate file because it is easier to edit, and does not clutter the .dna file.
42 | But for this example I will take the simple approach with the ribbon markup inside the .dna file.
43 |
44 | Edit the `-AddIn.dna` file, and add the following markup under the `` tag:
45 |
46 | ```xml
47 |
48 |
49 |
50 |
51 |
52 |
53 |
54 |
55 |
56 |
57 |
58 |
59 |
60 | ```
61 |
62 | Note that there are two nested tags called `` and `` respectively.
63 |
64 | ## Add the Ribbon handler code
65 |
66 | Now we add code to handle the ribbon callback - in our example the button has an `onAction='OnSayHelloPressed'` attribute.
67 | So we need:
68 | * a class that derives from the `ExcelRibbon` base class, marked as `` and
69 | * a method called `OnSayHelloPressed` with the right signature to handle the `onAction` callback for a `button`.
70 |
71 | To implement this, add a new class to the project, with this content:
72 |
73 | ```vb
74 | Imports System.Runtime.InteropServices
75 | Imports ExcelDna.Integration.CustomUI
76 |
77 |
78 | Public Class Ribbon
79 | Inherits ExcelRibbon
80 |
81 | Public Sub OnSayHelloPressed(control As IRibbonControl)
82 | MsgBox("Hello from .NET!")
83 | End Sub
84 |
85 | End Class
86 | ```
87 |
88 | We can now build and run the add-in, to test the new ribbon.
89 |
90 | ## Interact with the Excel COM object model
91 |
92 | Typically you would run some macro command form the ribbon handler, which would interact with the Excel COM object model similar to a VBA macro.
93 |
94 | ### Reference the Excel COM interop assemblies
95 |
96 | First, we add a reference to the COM interop assemblies to our add-in. This will allow us to easily use the Excel COM object model from our add-in.
97 | To do this, add the NuGet package 'ExcelDna.Interop' to the project. It would also be possible to reference the COM libraries directly.
98 |
99 | The `ExcelDna.Interop` package includes the Excel 2010 version of the COM object model. This means an add-in that uses these features should work under any Excel 2010 and later versions. However, newer features are not available.
100 |
101 | ### Add macro code to the ribbon callback
102 |
103 | In the Excel-DNA case, this means we need to get hold of the root Application object with a call to `ExcelDnaUtil.Application`.
104 | From there we can use the object model in a similar way to VBA.
105 |
106 | Modify the example like this:
107 |
108 | ```vb
109 | ' Add these namespace imports at the top of the file
110 | Imports Microsoft.Office.Interop.Excel
111 | Imports ExcelDna.Integration
112 |
113 | ' And then change the method like this
114 |
115 | Public Sub OnSayHelloPressed(control As IRibbonControl)
116 | Dim app As Application
117 | Dim rng As Range
118 |
119 | app = ExcelDnaUtil.Application ' This gets the root Excel Application object from the Excel-DNA environment
120 | rng = app.Range("A1") ' Get a Range object for cell A1 on the ActiveSheet
121 |
122 | rng.Value = "Hello from .NET!" ' Set the value in that cell
123 | End Sub
124 |
125 | ```
126 |
127 | ## Add an image
128 |
129 | Next we add an image to display on the ribbon button.
130 |
131 | For this we adjust the markup
132 | 1. Add an image file to our project, (I put it an a project folder as `Images\MagicWand.png`) and set its `Copy to Output Directory` property to `Copy if Newer`. That ensures the image file will be available when debugging.
133 | 2. Add a `loadImage` callback to the `customUI` tag. Excel-DNA internally implements the `LoadImage` method on the `ExcelRibbon` base class.
134 | 3. Add an `image` attribute to the `button` to select the image.
135 | 4. Add an `Image` tag in the .dna file to identify and pack the image file, with the `Path` pointing to the location - in this case I've put it under an Images folder in the project, so I'll use `Path='Images\MagicWand.png`. I also add `Pack='true'` so that the image file will be included in the packed .xll file.
136 |
137 | The .dna file gets these changes:
138 |
139 | ```xml
140 |
141 |
142 |
143 |
144 |
145 |
146 |
147 |
148 |
149 |
150 |
151 |
152 |
153 |
154 |
155 |
156 |
157 | ```
158 |
159 | Now build and run to see the image added to the button in Excel.
160 |
161 | ## Ribbon xml and callback documentation
162 |
163 | Excel-DNA is responsible for loading the ribbon helper add-in, but is not otherwise involved in the ribbon extension. This means that the custom UI xml schema, and the signatures for the callback methods are exactly as documented by Microsoft. The best documentation for these aspects can be found in the three-part series on 'Customizing the 2007 Office Fluent Ribbon for Developers':
164 |
165 | * [Part 1 - Overview](https://msdn.microsoft.com/en-us/library/aa338202.aspx)
166 | * [Part 2 - Controls and callback reference](https://msdn.microsoft.com/en-us/library/aa338199.aspx)
167 | * [Part 3 - Frequently asked questions, including C# and VB.NET callback signatures](https://msdn.microsoft.com/en-us/library/aa722523.aspx)
168 |
169 | Information related to the Excel 2010 extensions to the ribbon can be found here:
170 |
171 | * [Customizing Context Menus in Office 2010](https://msdn.microsoft.com/en-us/library/office/ee691832.aspx)
172 | * [Customizing the Office 2010 Backstage View](https://msdn.microsoft.com/en-us/library/office/ee815851.aspx)
173 | * [Ribbon Extensibility in Office 2010: Tab Activation and Auto-Scaling](https://msdn.microsoft.com/en-us/library/office/ee691834.aspx)
174 |
--------------------------------------------------------------------------------
/SpecialTopics/IntelliSenseForVBAFunctions/README.md:
--------------------------------------------------------------------------------
1 | # IntelliSense for VBA functions
2 |
3 | This tutorial shows you how to enable in-sheet IntelliSense help for VBA Functions.
4 |
5 | ```vb
6 | Function TempFahrenheit(tempInCelsius)
7 | ...
8 | ```
9 |
10 | 
11 |
12 |
13 | [](http://www.youtube.com/watch?v=-BIOzl1igXU "Excel-DNA IntelliSense for VBA Functions")
14 |
15 |
16 | ## Background
17 |
18 | When you edit a formula on a worksheet, Excel has two mechanisms to assist you in entering the right function call information.
19 |
20 | ### The 'Function Arguments' dialog
21 |
22 | This helps you to to select a function and enter or select the right arguments for the function.
23 |
24 | 
25 |
26 | ### The in-sheet 'Formula AutoComplete' features
27 |
28 | While entering the formula in the cell, the function list and function details help is displayed as an IntelliSense-style popup.
29 |
30 | 
31 | 
32 |
33 |
34 | ### Descriptions and help information for user-defined functions (UDFs)
35 |
36 | UDFs that are declared in .xll add-ins (like those made in .NET with Excel-DNA) can be registered with function and argument descriptions, and these will display in the 'Insert Function' dialog. For Functions in VBA code (either in an .xlam add-in or in the workbook itself) you can is possible to use the `Application.MacroOptions` method to add function and argument descriptions.
37 |
38 | However, information added about UDFs with these mechanism only display in the 'Insert Function' dialog. Excel exposes no built-in mechanism that lets UDFs defined in .xll add-ins or VBA to also participate in the in-sheet 'Formula AutoComplete' feature.
39 |
40 | ## Excel-DNA IntelliSense extension
41 |
42 | To enable in-sheet help for UDFs, I developed the Excel-DNA IntelliSense extension. This extension allows functions defined in .xll add-ins as well as VBA functions to register and show IntelliSense information.
43 |
44 | You can find more details about the extension at the [Excel-DNA IntelliSense GitHub site](https://github.com/Excel-DNA/IntelliSense), but here I will focus on the use for VBA functions.
45 |
46 | ### Download the ExcelDna.IntelliSense(64).xll add-in
47 |
48 | The newest release of the IntelliSense add-in can be found here:
49 | https://github.com/Excel-DNA/IntelliSense/releases
50 |
51 | You need to check whether your version of Excel is a 32-bit or 64-bit version, then download the matching .xll file.
52 | To test you can just follow File -> Open and select the .xll file. Installing the add-in so that it opens automatically can be done in the `Alt+t, i` Add-Ins dialog - also at File -> Options -> Add-Ins, Manage: Excel add-ins.
53 |
54 | ### Example functions
55 |
56 | I will use these VBA functions as an example:
57 |
58 | ```vb
59 | Function TempCelsius(tempInFahrenheit As Double) As Double
60 | TempCelsius = (tempInFahrenheit - 32#) * 5# / 9#
61 | End Function
62 |
63 | Function TempFahrenheit(tempInCelsius As Double) As Double
64 | TempFahrenheit = (tempInCelsius / 5# * 9#) + 32#
65 | End Function
66 |
67 | Function TempDeltaFromHeat(heatDelta As Double, mass As Double, specificHeatCapacity As Double)
68 | TempDeltaFromHeat = heatDelta / mass / specificHeatCapacity
69 | End Function
70 | ```
71 |
72 | To enable the Excel-DNA IntelliSense you need to load the ExcelDna.IntelliSense.xll (or ExcelDna.IntelliSense64.xll) add-in.
73 | You then provide function descriptions in:
74 | * a special (possibly hidden) worksheet,
75 | * an extra file next to the workbook or add-in with the descriptions in xml format, or
76 | * the same xml format information saved in the 'CustomXML' properties of the workbook.
77 |
78 | #### Create function descriptions worksheet
79 |
80 | | | A | B | C | D | E | F | G | H | I |
81 | |-|-------------------|----------------|-----------------|----------------|------------------|------|----------------|----------------------|-------------------|
82 | |1| FunctionInfo | 1 | Temperature | | | | | | |
83 | |2| TempCelsius | converts ... | https://en.w... | tempFahrenheit | is the temper... | | | | |
84 | |3| TempFahrenheit | converts ... | https://en.w... | tempCelsius | is the temper... | | | | |
85 | |4| TempDeltaFromHeat | calculates ... | https://www... | heatDelta | is the amount... | mass | is the mass... | specificHeatCapacity | is the specific.. |
86 |
87 | Details of the sheet format are:
88 | * The name of the sheet must be '\_IntelliSense\_'; it may be a hidden sheet
89 | * The first cell (A1) must contain the string 'FunctionInfo'
90 | * The next cell across (B1) must contain the value 1
91 | * The next call across (C1) may contain a category for the functions (not read by the IntelliSense add-in, used only in the `MacroOptions` code shown below)
92 | * From the second row down, each row contains the information for a single function
93 | * Function name
94 | * Function description
95 | * Function help link
96 | * Argument1 name
97 | * Argument1 description
98 | * Argument2 name
99 | * Argument2 description
100 | * etc.
101 |
102 | #### Function descriptions xml file
103 | Another way you can provide the function information to the IntelliSense add-in is with an xml file next to the workbook or add-in file.
104 | For a workbook with the name 'MyWorkbook.xlsm' the IntelliSense file must be named 'MyWorkbook.intellisense.xml'.
105 |
106 | The contents of the xml file, matching the above example worksheet, would be
107 |
108 | ```xml
109 |
110 |
111 |
113 |
115 |
116 |
118 |
120 |
121 |
124 |
126 |
128 |
130 |
131 |
132 |
133 | ```
134 |
135 | #### Function descriptions xml in CustomXML part
136 |
137 | A third options for providing the function description details is to add the xml content as a `CustomXMLPart` of the workbook.
138 |
139 | This snippet can be used to embed the xml file in a workbook:
140 |
141 | ```vb
142 | Sub EmbedIntelliSense()
143 |
144 | Dim strFilename As String
145 | Dim strFileContent As String
146 | Dim iFile As Integer
147 |
148 | strFilename = "C:\Path\To\VBAFunctions.IntelliSense.xml"
149 | iFile = FreeFile
150 | Open strFilename For Input As #iFile
151 | strFileContent = Input(LOF(iFile), iFile)
152 | Close #iFile
153 |
154 | Debug.Print strFileContent
155 |
156 | ThisWorkbook.CustomXMLParts.Add strFileContent
157 |
158 | End Sub
159 | ```
160 |
161 |
162 | ### Application.MacroOptions
163 |
164 | Function and argument descriptions for VBA functions can be registered for display in the 'Function Arguments' dialog with the `Application.MacroOptions` method.
165 | If we have already defined this information on a worksheet as described above, it is convenient to add `MacroOptions` registration from the same sheet.
166 | A macro that would do this might look like this
167 |
168 | ```vb
169 |
170 | Sub RegisterMacroOptions()
171 | Dim ws As Worksheet
172 | Dim row As Range
173 | Dim rowi As Integer
174 | Dim coli As Integer
175 | Dim args As Integer
176 |
177 | Dim category As String
178 | Dim functionName As String
179 | Dim functionDescription As String
180 | Dim helpTopic As String
181 | Dim ArgDescriptions() As String
182 |
183 | Set ws = ThisWorkbook.Worksheets("_IntelliSense_")
184 | category = ws.Cells(1, 3)
185 | If category = "" Then
186 | category = ThisWorkbook.Name
187 | End If
188 |
189 | rowi = 2
190 |
191 | Do While True
192 | Set row = ws.Rows(rowi)
193 | functionName = row.Cells(1, 1).Value
194 | If functionName = "" Then
195 | Exit Do
196 | End If
197 |
198 | functionDescription = row.Cells(1, 2)
199 | helpTopic = row.Cells(1, 3)
200 |
201 | args = 0
202 | For coli = 5 To 45 Step 2
203 | If row.Cells(1, coli) = "" Then
204 | Exit For
205 | End If
206 |
207 | args = args + 1
208 | ReDim Preserve ArgDescriptions(args - 1)
209 | ArgDescriptions(args - 1) = row.Cells(1, coli)
210 | Next
211 |
212 | Application.MacroOptions functionName, functionDescription, False, "", False, "", "", "", "", helpTopic, ArgDescriptions
213 | rowi = rowi + 1
214 | Loop
215 | End Sub
216 | ```
217 |
218 | After running this routine, the descriptions will be saved together with the workbook. So you only have to run the routine again to update the descriptions.
219 |
220 | The end result is a workbook or add-in that has in-sheet IntelliSense when the `ExcelDna.IntelliSense(64).xll` add-in is loaded, and also shows the function descriptions in the Excel `Function Arguments` dialog.
221 |
222 | ## Conclusion
223 |
224 | We've shown how to add in-sheet IntelliSense for VBA functions using the Excel-DNA IntelliSense add-in.
225 |
226 | More information about the Excel-DNA IntelliSense add-in, including details on how to use it with .NET-based Excel-DNA add-ins see the [IntelliSense Github Repository](https://github.com/Excel-DNA/IntelliSense).
227 |
--------------------------------------------------------------------------------
/VBA-to-.NET/WebRequestBasics/Readme.md:
--------------------------------------------------------------------------------
1 | # VBA to .NET: Web Request Basics
2 |
3 | A common programming task is to retrieve some information from a remote system via an HTTP web request. This might be ease or difficult depending on the nature of the remote system, the type of data to be retrieved, the amount of processing required and the way the data will then be used. Overall this is a large topic, but at least we can often get started without too much trouble.
4 |
5 | This tutorial gives a high-level view of how to aproach this task, an example of how to get started with the simple case, and some pointers on where to look further.
6 |
7 | ## Introduction
8 |
9 | I use the term 'web-based resource' for any information that can be accessed via the standard HTTP protocol. This includes:
10 | * public web sites (reading the information would often be called 'web scraping'),
11 | * web-based services that can be accessed with an HTTP-based API,
12 | * internal services in a company, or even running on the same machine where it will be accessed.
13 |
14 | (While I won't discuss it further here, other protocols like FTP might also be required to access internet-based resources.)
15 |
16 | There is a huge variety of web-based resources, and reasons for wanting to access these resources. For example:
17 | * gather data from a web site into an Excel spreadsheet for further analysis or custom reporting,
18 | * periodically read data and store in a different database for further use,
19 | * perform some actions through a web-based interface, like uploading data or sending bulk email messages.
20 |
21 | Like the range of resources, and the various reasons for accessing these, the ease or difficulty in interacting with web-based resources also varies a lot. Some web site are very easy to access from a script or program, while others may be extremely difficult to interact with even for a human using a browser, and more so for an automated system. Into this mix also comes various types of security involved, including authentication of a user, various ways that website try to prevent being accessed by programs ('prove you're human') and throttling to prevent large amounts of (or sometimes any) data being accessed.
22 |
23 | This tutorial is not meant as a comprehensive guide to this wide range of cases, but rather has the following aims:
24 | * give a high-level view of the web-request topic, helping to strucutre your thoughts and programs when taking on such a task,
25 | * provide a basic example of how to go about the simple case,
26 | * explain the varous ways in which things become complicated, and point to resources that might help.
27 |
28 | ## A note about web requests from Excel and VBA
29 |
30 | Web requests can be made from Excel directly or using VBA in various ways. I list a few:
31 | * [`WEBSERVICE` function](https://support.microsoft.com/en-us/office/webservice-function-0546a35a-ecc6-4739-aed7-c0b7ce1562c4)
32 | * Excel [`QueryTables`](https://docs.microsoft.com/en-us/office/vba/api/excel.querytable.webtables) with a direct http connection
33 | * Using the `MSXML2.ServerXMLHTTP` or `MSXML2.XMLHTTP60` COM class from VBA
34 | * Using the `WinHttp.WinHttpRequest.5.1` COM class from VBA
35 | * Automate Internet Explorer from VBA
36 | * Use the Selenium web driver to automate any browser from VBA
37 |
38 | Google Sheets also has some handy functions to get web request data into the sheet:
39 | * [`importHTML`](https://support.google.com/docs/answer/3093339)
40 | * [`importXML`](https://support.google.com/docs/answer/3093342)
41 | * [`importDATA`](https://support.google.com/docs/answer/3093335)
42 |
43 | ## Bird's eye view
44 |
45 | I find it useful to structure the web-request programming tasks into three aspects - **Fetch**, **Process** and **Use**.
46 |
47 | #### Fetch
48 | The various calls and mechanism needed to interact with the remote system, including protocol settings, API keys, cookies or other security aspects.
49 |
50 | #### Process
51 | What to do with the results returned from the fetch phase to extract the information we want, or convert into a format or data structure we want to use. For example finding particular parts in an html result page, or parsing a JSON result string into a friendly data structure.
52 |
53 | #### Use
54 | This covers the program environment that will initiate the web request and receive the processed results for further use. For example this might be an Excel add-in which exposes user-defined function for accessing the web resource, or it might be a console application that is run periodically to donwload a data set and store into a local database.
55 |
56 | I think of these aspects in a relationship like this:
57 |
58 | :TODO:
59 |
60 |
61 | While the **Fetch** and **Process** aspects offer quite different technical challenges and need different tools, they tend to work as a pair when developing access to a particular web site or resource. A particuler web resource would follow a pattern for access (for example security, call pattern) when fectching different bits of information. Similarly, the web site structure and processing needed to get to the right bits of data would often change together when systems are updated. So it makes sense to encapsulate or bundle them together into an `XyzClient` library that can easily be used in different. For example we might have a `YahooFinanceClient` or a `FREDClient`. Indeed for many web resources _there might already be a client library for .NET available_ from the service provider, or as a project on GitHub.
62 |
63 | The **Use** aspect concerns the specific way we will run and use the client library and the results we get. I will not be focusing much on this aspect for the tutorial, but will pick a simple case for the example - press a button in Excel to download and put some data in a sheet. It's often useful to think of multiple ways in which the same client for a web resource can be used. Sometimes it might be interactively through a spreadsheet or other interface, while at other times the data will be fecthed and stored for later analysis, for example when a machine learning model will be trained against the data set. Of source the usage setting woud aslo drive the requirements for what information and format the client library should support.
64 |
65 | Generally the programming tools needed in the **Use** aspects are different and independent of those needed in the web-related client library. Results of the web requested data might be used from console applications or scripts (which are easy to automate), from Excel add-ins where the are directed by end-users or for storing in databases, which in turn might be on a local (like an Access, SQLite or SQL Server database), on a network or internet hosted service.
66 |
67 | ### Notes on program style
68 |
69 | There are some questions of program structure and style that I think are relevant to the topic and examples, so I'll mention these briefly.
70 |
71 | #### Using and exposing asynchronous calls
72 |
73 | Since web request mostly cross machine and often large geographic boundaries, they tend to have high latency, so a program that is making such requests will spend a lot of time (in computing terms) just waiting for the next response.
74 |
75 | Writing programs that are well structured but still interact well with such high-latency calls was historically quite difficult. But the excellent async/await programming model developed in .NET and now used in most programming platforms makes this kind of programming much easier. Async programming is another important topic to cover in the VBA to .NET context.
76 |
77 | I recommend that the wrapper client library also expose async methods, as these can easily be consumed both in settings where the async aspect is useful, and in places where a synchronous interface is better suited. So I will also follow that pattern in the example here.
78 |
79 | #### Interfaces and abstraction
80 |
81 | One question that might arise in structuring such a project is whether to have an abstract interface that defines the abilities and usage for an `XyzClient`, maybe an `IWebClient` interface. This would allow various clients to be interchanged as components in various useage scenarios.
82 |
83 | If a project will need many different web-resource clients that will all be used in a similar way, it might well make sense to abstract the usage through a common base class or by implementing common interfaces.
84 |
85 | I will not be adding this complexity in the examples here.
86 |
87 | #### Automated testing
88 |
89 | The web request client library often deals with external systems, which make automated testing more difficult. It can help to at least have a simple console program that uses the client library, as a way of using and testing the library witout the larger environment and other components involved. Conversely, for some projects it will help to have a mode or a mock version of the library that can be used to provide predictable results for automated test purposes, so that the mock version can be used instead of the real web requests in an automated test setting.
90 |
91 | ## Simple fetch from an http url
92 |
93 | Let's start with the simplest case, where we just want to read a string from an http request.
94 | The key class for this purpose in .NET is called [`HttpClient`](https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httpclient?view=netframework-4.8). (There is an older `WebClient` class, which has mostly been deprecated.)
95 |
96 | An important aspect of using `HttpClient` for web requests is to not make a new instance of the `HttpClient` class for each request. Rather think of an `HttpClient` as a mini-browser that you control with code, and then ask it to make verious requests. We'll keep an instance of `HttpClient` in our `Module` (similar to a `static` variable in C#) and then have the web request method use the single instance.
97 |
98 | So a simple module that uses an `HttpClient` might look like this:
99 |
100 | ```vb
101 |
102 |
103 | ```
104 |
105 | ## An example client library for OpenWeather
106 |
107 | As a more representative example, let's have a look at the OpenWeather website, and how we could access the information from a .NET library.
108 | There is an open-source library that already
109 |
110 | The OpenWeather site makes available a web request API, which makes it easier to retrieve the data from a program, rether than having to understand the html markup normally rendered in a browser.
111 |
112 | ### Fetch
113 |
114 |
115 | ### Process
116 |
117 | ### ***Use** from a console runner
118 |
119 | ### ***Use** from an Excel add-in
120 |
121 |
122 | ## Getting sophisticated and complications galore!
123 |
124 |
125 |
126 | I should mention that there is an open-source library that wraps
127 |
128 | While the basic case is quite easy to make work, web request programming can become very difficult and lead to great frustration. In the section I give some glimpse of the ladder of complexity one might climb down, and some pointers to the tools that might be useful along the way.
129 |
130 | ### Fetching
131 |
132 |
133 |
134 | ### Processing
135 |
136 |
137 | Single values
138 | Tables
139 | Download files
140 |
141 | ### F# library and discussion
142 | https://simontreanor.github.io/blog/20210205_FunStripe.html
143 |
144 |
145 | ### More about web scraping
146 | https://mihaisplace.blog/2021/10/03/the-state-of-web-scraping-in-2021/
147 |
--------------------------------------------------------------------------------
/VBA-to-.NET/FormulaEvaluateConvert/FormulaEvaluate/mExcelMacros.vb:
--------------------------------------------------------------------------------
1 | Option Explicit Off
2 | Imports Microsoft.Office.Interop.Excel
3 |
4 | Public Module mExcelMacros
5 |
6 | Sub Pascal()
7 | '***************************************************************************
8 | '*Macro: Pascal *
9 | '*Utilidad: Construye el triangulo de Pascal según la cantidad niveles que *
10 | '*se indique en la celda E1. *
11 | '*Construido por: Alvin Correa. *
12 | '*Fecha: *
13 | '*Observaciones: Esta rutina consiste solamente es el uso de la estrructura*
14 | '*For-Next, la cual se utiliza dos veces. la primera para llenar los unos *
15 | '*del triangulo y la segunda es un doble fornext anidado que genera el tri-*
16 | '*angulo como tal. *
17 | '***************************************************************************
18 | Application.ScreenUpdating = False
19 | 'Lee la cantidad de niveles:
20 | n = Cells(1, 5).Value
21 | ' Llena unos "1":
22 | For i = 1 To n
23 | Cells(i, 1).Value = 1
24 | Cells(i, i).Value = 1
25 | Next i
26 | ' Llena el resto:
27 | If n > 2 Then
28 | For i = 3 To n
29 | For j = 2 To i - 1
30 | Cells(i, j).Value = Cells(i - 1, j).Value + Cells(i - 1, j - 1).Value
31 | Next j
32 | Next i
33 | End If
34 | End Sub
35 | Sub Borrar()
36 | '***************************************************************************
37 | '* Rutina de Borrado. *
38 | '***************************************************************************
39 | Application.ScreenUpdating = False
40 | n = Cells(1, 5).Value
41 | For i = 1 To n
42 | For j = 1 To i
43 | Cells(i, j).Value = Nothing
44 | Next j
45 | Next i
46 | End Sub
47 | Sub G_2D()
48 | '***************************************************************************
49 | '*Macro: G_2D *
50 | '*Utilidad: Grafica una función en R^2 dada la regla de correspondencia es_*
51 | '*crita en la celda C2. *
52 | '*Construido por: Alvin Correa. *
53 | '*Fecha: *
54 | '*Observaciones: Esta rutina consiste en graficar en dos dimensiones una *
55 | '*funcion dada. *
56 | '* *
57 | '* *
58 | '***************************************************************************
59 | Application.ScreenUpdating = False
60 | Dim n As Integer
61 | Dim h As Double
62 | Dim formula As String
63 | Dim graf As Chart
64 | Dim chartsTemp As ChartObjects 'Contador de charts (gráficos) para eliminar el anterior
65 | Dim OK As Boolean
66 | Dim Fun As New clsMathParser
67 | n = Cells(6, 5).Value
68 | a = Cells(6, 3).Value
69 | b = Cells(6, 4).Value
70 | h = (b - a) / n
71 | formula = Cells(2, 3).Value
72 | OK = Fun.StoreExpression(formula) 'Lectura de la fórmula
73 | If Not OK Then GoTo Error_Handler
74 | For i = 0 To n
75 | Cells(6 + i, 1).Value = a + i * h
76 | Cells(6 + i, 2).Value = Fun.Eval1(a + i * h)
77 | Next i
78 | '----------------------- Eliminar gráficos anteriores-------------
79 | chartsTemp = ActiveSheet.ChartObjects
80 | If chartsTemp.Count > 0 Then
81 | chartsTemp.Item(chartsTemp.Count).Delete() ' VBA to .NET: Not sure why we need .Item here - looks like a bug in the COM definitions
82 | End If
83 | '-----------------------------------------------------------------
84 | datos = Range(Cells(6, 1), Cells(6 + n, 2)).Address
85 | 'rango a graficar
86 | graf = Charts.Add() 'gráfico y sus caraterísticas
87 | With graf
88 | .Name = "Gráfico"
89 | .ChartType = XlChartType.xlXYScatterSmoothNoMarkers
90 | .SetSourceData(Source:=Sheets("Graficas en 2D").Range(datos), PlotBy:=XlRowCol.xlColumns)
91 | .Location(Where:=XlChartLocation.xlLocationAsObject, Name:="Graficas en 2D")
92 | End With
93 | With ActiveChart()
94 | .HasTitle = False
95 | .Axes(XlAxisType.xlCategory, XlAxisGroup.xlPrimary).HasTitle = False
96 | .Axes(XlAxisType.xlValue, XlAxisGroup.xlPrimary).HasTitle = False
97 | End With
98 | 'Mostramos el procedimiento
99 | Application.ScreenUpdating = True
100 | ActiveChart.HasLegend = False
101 | '---------------------------------------------------------------
102 | If Err.Number <> 0 Then GoTo Error_Handler
103 | Error_Handler: Cells(1, 1).Value = Fun.ErrorDescription 'imprimir mensaje error
104 | '---------------------------------------------------------------
105 | End Sub
106 | Sub G3D()
107 | '***************************************************************************
108 | '*Macro: G3D *
109 | '*Utilidad: Grafica una función en R^3 dada la regla de correspondencia es_*
110 | '*crita en la celda B2. *
111 | '*Construido por: Alvin Correa. *
112 | '*Fecha: *
113 | '*Observaciones: Esta rutina consiste en graficar en dos dimensiones una *
114 | '*funcion dada. *
115 | '* *
116 | '* *
117 | '***************************************************************************
118 | ' Grafica en 3D
119 | Application.ScreenUpdating = False
120 | Dim xmin, xmax, ymin, ymax, hx, hy, xi, yi As Double
121 | Dim n As Integer
122 | Dim fxy As String 'función f(x,y)
123 | Dim graf As Chart
124 | Dim OK As Boolean
125 | Dim Fun As New clsMathParser ' Se utiliza para llamar al móduloque interpreta las funciones³
126 | fxy = Cells(2, 2).Value
127 | xmin = Cells(5, 3).Value
128 | xmax = Cells(5, 4).Value
129 | ymin = Cells(5, 5).Value
130 | ymax = Cells(5, 6).Value
131 | n = Cells(3, 2).Value ' núumero de puntos n x n
132 | hx = (xmax - xmin) / n
133 | hy = (ymax - ymin) / n
134 | If hx > 0 And hy > 0 And n > 0 Then
135 | For i = 0 To n
136 | xi = xmin + i * hx
137 | Cells(7, 2 + i).Value = xi
138 | For j = 0 To n
139 | yi = ymin + j * hy
140 | Cells(8 + j, 1).Value = yi
141 | OK = Fun.StoreExpression(fxy) 'formula actual es 'f(x,y)'
142 | If Not OK Then GoTo Error_Handler
143 | Fun.Variable("x") = xi
144 | Fun.Variable("y") = yi
145 | Cells(8 + j, 2 + i).Value = Fun.Eval() 'retorna f(xa,ya)
146 | Next j
147 | Next i
148 | End If
149 | '----------------------- eliminar gráficos anteriores-------------
150 | chartsTemp = ActiveSheet.ChartObjects
151 | If chartsTemp.Count > 0 Then
152 | chartsTemp(chartsTemp.Count).Delete
153 | End If
154 | '-----------------------------------------------------------------
155 | datos = Range(Cells(7, 1), Cells(7 + n, n + 2)).Address 'rango a graficar
156 | Range(datos).Select()
157 | Selection.NumberFormat = ";;;" 'ocular celdas
158 | Charts.Add()
159 | ActiveChart.ChartType = XlChartType.xlSurface
160 | ActiveChart.SetSourceData(Source:=Sheets("Graficas en 3D").Range(datos), PlotBy:=XlRowCol.xlColumns)
161 | ActiveChart.Location(Where:=XlChartLocation.xlLocationAsObject, Name:="Graficas en 3D")
162 | '---------------------------------------------------------------
163 | If Err.Number <> 0 Then GoTo Error_Handler
164 | Error_Handler: Cells(1, 1).Value = Fun.ErrorDescription 'enviar un mensaje de error
165 | '---------------------------------------------------------------
166 | ActiveChart.HasLegend = False
167 | End Sub
168 | Sub Romberg()
169 | Application.ScreenUpdating = False
170 | ' Integración de Romber
171 | Dim R(,) As Double
172 | Dim a, b, h, suma As Double
173 | Dim n As Integer
174 | Dim formula As String
175 | Dim OK As Boolean
176 | Dim Fun As New clsMathParser ' así se llama el módulo de clase aquí³
177 | formula = Cells(2, 2).Value
178 | a = Cells(2, 3).Value
179 | b = Cells(2, 4).Value
180 | n = Cells(2, 5).Value
181 | ReDim R(n, n)
182 | h = b - a
183 | OK = Fun.StoreExpression(formula) 'formula actual es 'formula'
184 | If Not OK Then GoTo Error_Handler
185 | '-------------------------------------------------------------------
186 | For i = 1 To 50 'limpiar
187 | For j = 1 To 50
188 | Cells(2 + i, j).Value = Nothing
189 | Next j
190 | Next i
191 | '-------------------------------------------------------------------
192 | R(1, 1) = h / 2 * (Fun.Eval1(a) + Fun.Eval1(b))
193 | 'paso3 de algoritmo de Romberg
194 | For i = 1 To n
195 | 'paso 4
196 | suma = 0
197 | For k = 1 To 2 ^ (i - 1)
198 | suma = suma + Fun.Eval1(a + h * (k - 0.5)) 'evalúa en la fórmula actual
199 | Next k
200 | R(2, 1) = 0.5 * (R(1, 1) + h * suma)
201 | 'paso5
202 | For j = 2 To i
203 | R(2, j) = R(2, j - 1) + (R(2, j - 1) - R(1, j - 1)) / (4 ^ (j - 1) - 1)
204 | Next j
205 | 'paso 6 salida R(2,j)
206 | For j = 1 To i
207 | Cells(3 + i - 1, j) = R(2, j) 'columnas 2,3,...n
208 | Next j
209 | 'paso 7
210 | h = h / 2
211 | 'paso 8
212 | For j = 1 To i
213 | R(1, j) = R(2, j)
214 | Next j
215 | Next i
216 | '---------------------------------------------------------------
217 | If Err.Number <> 0 Then GoTo Error_Handler
218 | Error_Handler: Cells(1, 1).Value = Fun.ErrorDescription
219 | '---------------------------------------------------------------
220 | End Sub
221 |
222 | End Module
--------------------------------------------------------------------------------
/SpecialTopics/DynamicArrays/ArrayResizer.cs:
--------------------------------------------------------------------------------
1 | using System;
2 | using ExcelDna.Integration;
3 | using static ExcelDna.Integration.XlCall;
4 |
5 | // This class defines a few test functions that can be used to explore the automatic array resizing under pre-dynamic arrays Excel
6 | public static class ResizeTestFunctions
7 | {
8 | // Makes an array, but automatically resizes the result
9 | public static object dnaMakeArrayAndResize(int rows, int columns, string unused, string unusedtoo)
10 | {
11 | object[,] result = ExampleFunctions.dnaMakeArray(rows, columns);
12 | return ArrayResizer.dnaResize(result);
13 |
14 | // Can also call Resize via Excel - so if the Resize add-in is not part of this code, it should still work
15 | // (though calling direct is better for large arrays - it prevents extra marshaling).
16 | // return XlCall.Excel(XlCall.xlUDF, "Resize", result);
17 | }
18 | }
19 |
20 | public class ArrayResizer
21 | {
22 | // This function will run in the UDF context
23 | public static object dnaResize(object[,] array)
24 | {
25 | var caller = Excel(xlfCaller) as ExcelReference;
26 | if (caller == null)
27 | return array;
28 |
29 | int rows = array.GetLength(0);
30 | int columns = array.GetLength(1);
31 |
32 | if (rows == 0 || columns == 0)
33 | return array;
34 |
35 | // For dynamic-array aware Excel we don't do anything if the caller is a single cell
36 | // Excel will expand in this case
37 | if (UtilityFunctions.dnaSupportsDynamicArrays() &&
38 | caller.RowFirst == caller.RowLast &&
39 | caller.ColumnFirst == caller.ColumnLast)
40 | return array;
41 |
42 | if ((caller.RowLast - caller.RowFirst + 1 == rows) &&
43 | (caller.ColumnLast - caller.ColumnFirst + 1 == columns))
44 | {
45 | // Size is already OK - just return result
46 | return array;
47 | }
48 |
49 | var rowLast = caller.RowFirst + rows - 1;
50 | var columnLast = caller.ColumnFirst + columns - 1;
51 |
52 | // Check for the sheet limits
53 | if (rowLast > ExcelDnaUtil.ExcelLimits.MaxRows - 1 ||
54 | columnLast > ExcelDnaUtil.ExcelLimits.MaxColumns - 1)
55 | {
56 | // Can't resize - goes beyond the end of the sheet - just return #VALUE
57 | // (Can't give message here, or change cells)
58 | return ExcelError.ExcelErrorValue;
59 | }
60 |
61 | // TODO: Add some kind of guard for ever-changing result?
62 | ExcelAsyncUtil.QueueAsMacro(() =>
63 | {
64 | // Create a reference of the right size
65 | var target = new ExcelReference(caller.RowFirst, rowLast, caller.ColumnFirst, columnLast, caller.SheetId);
66 | DoResize(target); // Will trigger a recalc by writing formula
67 | });
68 | // Return the whole array even if we plan to resize - to prevent flashing #N/A
69 | return array;
70 | }
71 |
72 | public static double[,] dnaResizeDoubles(double[,] array)
73 | {
74 | var caller = Excel(xlfCaller) as ExcelReference;
75 | if (caller == null)
76 | return array;
77 |
78 | int rows = array.GetLength(0);
79 | int columns = array.GetLength(1);
80 |
81 | if (rows == 0 || columns == 0)
82 | return array;
83 |
84 | // For dynamic-array aware Excel we don't do anything if the caller is a single cell
85 | // Excel will expand in this case
86 | if (UtilityFunctions.dnaSupportsDynamicArrays() &&
87 | caller.RowFirst == caller.RowLast &&
88 | caller.ColumnFirst == caller.ColumnLast)
89 | return array;
90 |
91 | if ((caller.RowLast - caller.RowFirst + 1 == rows) &&
92 | (caller.ColumnLast - caller.ColumnFirst + 1 == columns))
93 | {
94 | // Size is already OK - just return result
95 | return array;
96 | }
97 |
98 | var rowLast = caller.RowFirst + rows - 1;
99 | var columnLast = caller.ColumnFirst + columns - 1;
100 |
101 | if (rowLast > ExcelDnaUtil.ExcelLimits.MaxRows - 1 ||
102 | columnLast > ExcelDnaUtil.ExcelLimits.MaxColumns - 1)
103 | {
104 | // Can't resize - goes beyond the end of the sheet - just return null (for #NUM!)
105 | // (Can't give message here, or change cells)
106 | return null;
107 | }
108 |
109 | // TODO: Add guard for ever-changing result?
110 | ExcelAsyncUtil.QueueAsMacro(() =>
111 | {
112 | // Create a reference of the right size
113 | var target = new ExcelReference(caller.RowFirst, rowLast, caller.ColumnFirst, columnLast, caller.SheetId);
114 | DoResize(target); // Will trigger a recalc by writing formula
115 | });
116 | // Return what we have - to prevent flashing #N/A
117 | return array;
118 | }
119 |
120 | static void DoResize(ExcelReference target)
121 | {
122 | // Get the current state for reset later
123 | using (new ExcelEchoOffHelper())
124 | using (new ExcelCalculationManualHelper())
125 | {
126 | ExcelReference firstCell = new ExcelReference(target.RowFirst, target.RowFirst, target.ColumnFirst, target.ColumnFirst, target.SheetId);
127 |
128 | // Get the formula in the first cell of the target
129 | string formula = (string)Excel(xlfGetCell, 41, firstCell);
130 | bool isFormulaArray = (bool)Excel(xlfGetCell, 49, firstCell);
131 | if (isFormulaArray)
132 | {
133 | // Select the sheet and firstCell - needed because we want to use SelectSpecial.
134 | using (new ExcelSelectionHelper(firstCell))
135 | {
136 | // Extend the selection to the whole array and clear
137 | Excel(xlcSelectSpecial, 6);
138 | ExcelReference oldArray = (ExcelReference)Excel(xlfSelection);
139 |
140 | oldArray.SetValue(ExcelEmpty.Value);
141 | }
142 | }
143 | // Get the formula and convert to R1C1 mode
144 | bool isR1C1Mode = (bool)Excel(xlfGetWorkspace, 4);
145 | string formulaR1C1 = formula;
146 | if (!isR1C1Mode)
147 | {
148 | object formulaR1C1Obj;
149 | XlReturn formulaR1C1Return = TryExcel(xlfFormulaConvert, out formulaR1C1Obj, formula, true, false, ExcelMissing.Value, firstCell);
150 | if (formulaR1C1Return != XlReturn.XlReturnSuccess || formulaR1C1Obj is ExcelError)
151 | {
152 | string firstCellAddress = (string)Excel(xlfReftext, firstCell, true);
153 | Excel(xlcAlert, "Cannot resize array formula at " + firstCellAddress + " - formula might be too long when converted to R1C1 format.");
154 | firstCell.SetValue("'" + formula);
155 | return;
156 | }
157 | formulaR1C1 = (string)formulaR1C1Obj;
158 | }
159 | // Must be R1C1-style references
160 | object ignoredResult;
161 | //Debug.Print("Resizing START: " + target.RowLast);
162 | XlReturn formulaArrayReturn = TryExcel(xlcFormulaArray, out ignoredResult, formulaR1C1, target);
163 | //Debug.Print("Resizing FINISH");
164 |
165 | // TODO: Find some dummy macro to clear the undo stack
166 |
167 | if (formulaArrayReturn != XlReturn.XlReturnSuccess)
168 | {
169 | string firstCellAddress = (string)Excel(xlfReftext, firstCell, true);
170 | Excel(xlcAlert, "Cannot resize array formula at " + firstCellAddress + " - result might overlap another array.");
171 | // Might have failed due to array in the way.
172 | firstCell.SetValue("'" + formula);
173 | }
174 | }
175 | }
176 | }
177 |
178 | public class ExcelEchoOffHelper : XlCall, IDisposable
179 | {
180 | object oldEcho;
181 |
182 | public ExcelEchoOffHelper()
183 | {
184 | oldEcho = Excel(xlfGetWorkspace, 40);
185 | Excel(xlcEcho, false);
186 | }
187 |
188 | public void Dispose()
189 | {
190 | Excel(xlcEcho, oldEcho);
191 | }
192 | }
193 |
194 | public class ExcelCalculationManualHelper : XlCall, IDisposable
195 | {
196 | object oldCalculationMode;
197 |
198 | public ExcelCalculationManualHelper()
199 | {
200 | oldCalculationMode = Excel(xlfGetDocument, 14);
201 | Excel(xlcOptionsCalculation, 3);
202 | }
203 |
204 | public void Dispose()
205 | {
206 | Excel(xlcOptionsCalculation, oldCalculationMode);
207 | }
208 | }
209 |
210 | // Select an ExcelReference (perhaps on another sheet) allowing changes to be made there.
211 | // On clean-up, resets all the selections and the active sheet.
212 | // Should not be used if the work you are going to do will switch sheets, amke new sheets etc.
213 | public class ExcelSelectionHelper : XlCall, IDisposable
214 | {
215 | object oldSelectionOnActiveSheet;
216 | object oldActiveCellOnActiveSheet;
217 |
218 | object oldSelectionOnRefSheet;
219 | object oldActiveCellOnRefSheet;
220 |
221 | public ExcelSelectionHelper(ExcelReference refToSelect)
222 | {
223 | // Remember old selection state on the active sheet
224 | oldSelectionOnActiveSheet = Excel(xlfSelection);
225 | oldActiveCellOnActiveSheet = Excel(xlfActiveCell);
226 |
227 | // Switch to the sheet we want to select
228 | string refSheet = (string)Excel(xlSheetNm, refToSelect);
229 | Excel(xlcWorkbookSelect, new object[] { refSheet });
230 |
231 | // record selection and active cell on the sheet we want to select
232 | oldSelectionOnRefSheet = Excel(xlfSelection);
233 | oldActiveCellOnRefSheet = Excel(xlfActiveCell);
234 |
235 | // make the selection
236 | Excel(xlcFormulaGoto, refToSelect);
237 | }
238 |
239 | public void Dispose()
240 | {
241 | // Reset the selection on the target sheet
242 | Excel(xlcSelect, oldSelectionOnRefSheet, oldActiveCellOnRefSheet);
243 |
244 | // Reset the sheet originally selected
245 | string oldActiveSheet = (string)Excel(xlSheetNm, oldSelectionOnActiveSheet);
246 | Excel(xlcWorkbookSelect, new object[] { oldActiveSheet });
247 |
248 | // Reset the selection in the active sheet (some bugs make this change sometimes too)
249 | Excel(xlcSelect, oldSelectionOnActiveSheet, oldActiveCellOnActiveSheet);
250 | }
251 | }
252 |
253 | public static class UtilityFunctions
254 | {
255 | static bool? _supportsDynamicArrays;
256 | [ExcelFunction(IsHidden = false)]
257 | public static bool dnaSupportsDynamicArrays()
258 | {
259 | if (!_supportsDynamicArrays.HasValue)
260 | {
261 | try
262 | {
263 | var result = XlCall.Excel(614, new object[] { 1 }, new object[] { true });
264 | _supportsDynamicArrays = true;
265 | }
266 | catch
267 | {
268 | _supportsDynamicArrays = false;
269 | }
270 | }
271 | return _supportsDynamicArrays.Value;
272 | }
273 | }
274 |
--------------------------------------------------------------------------------
/SpecialTopics/RTD/README.md:
--------------------------------------------------------------------------------
1 | # What is RTD?
2 |
3 | Excel has a 'Real-Time Data' (RTD) feature lets us push data updates into an Excel sheet.
4 | A typical example for RTD is to provide a real-time stock ticker feed, but this powerful feature makes various interactions with the Excel sheet and calculation engine possible.
5 |
6 | You might already have noticed the `=RTD(...)` function on the list of worksheet functions, or seen me describe some Excel-DNA feature as 'RTD-based'.
7 | In this tutorial I'll explain what RTD is, how works under the covers and give an example of adding it to an Excel-DNA add-in.
8 |
9 | I can think of some reasons why the RTD feature of Excel is not so well known:
10 | * There are no built-in RTD data sources that ship with Office. There are only available from as part of third-party add-ins.
11 | * RTD Servers cannot be created in VBA, so they need another environment like C++ or .NET to create.
12 | * The COM-based nature of RTD means there are a few things to learn and take care with when making RTD Servers.
13 | * Registration of RTD server normally requires administrator permissions
14 |
15 | Despite the challenges in getting to know RTD, it is a very powerful feature of Excel that is closely integrated into the Excel calculation engine. Hence, it provides a foundation on which various high-level features can be built. But let me not run ahead of myself.
16 |
17 | ## What is an RTD Server?
18 |
19 | An RTD data source defined by code in a COM(\*) library that implements an 'RTD Server'. An RTD Server supports the interaction between Excel and the data source by implementing the `IRtdServer` interface. An RTD Server will then expose its data as one or more 'Topics', each of which is defined by an array of strings passed to the RTD Server when connecting to a new topic, and in return provides a stream of values back to Excel.
20 |
21 | > (*) What is COM?
22 | >
23 | > This is separate essay question... In brief, the Component Object Model (COM) is a standard that describes how software components can interact. The Excel COM object model is the set of interfaces that VBA uses to interact with Excel - this includes objects like `Application` and `Workbook`. Excel-DNA add-ins can also use the COM object model to interact with Excel. COM libraries are .dll libraries that work according to the COM standard. So in the context of RTD, it means that an RTD Server must follow these standard rules, so that Excel knows how to interact with it.
24 |
25 | Being a COM class, an RTD Server is identified by its COM 'ProgId'. These strings normally have a dotted form like 'MyCompany.RtdServer' or 'MyCompany.DataLink'. Behind the scenes there is also a Guid (a 'globally unique identifier') called the COM 'ClsId' for the RTD server, which normally looks like a long hexadecimal number 'B73B68BD-9DD0-4E9D-82A1-E9B2798AF8E5'.
26 |
27 | The combination of the `IRtdServer` interface and the `IRTDUpdateEvent` callback interface form the COM-based specification for how RTD Servers will iteract with Excel.
28 |
29 | The `IRtdServer` interface has these members:
30 | * `ServerStart` - create a new connection to the server (before any topics are connected)
31 | * `ServerTerminate` - end the connection to the server (after all topics are disconnected)
32 | * `ConnectData`- create a new topic according to the given topic strings
33 | * `DisconnectData` - notify the server that a topic is no longer connected to Excel
34 | * `RefreshData` - called to fetch updates for all topics
35 | * `Heartbeat` - check that the server is still running.
36 |
37 | The helper interface to notify Excel of any updates is called `IRTDUpdateEvent`, and is passed to the server in the `ServerStart` call.
38 | The server then notifies Excel that new data is ready, with a call to `IRTDUpdateEvent.UpdateNotify`.
39 |
40 | ## How does Excel interact with an RTD Server?
41 |
42 | We can now trace the interaction sequence between Excel and an RTD Server.
43 |
44 | A basic call sequence might look like this
45 | 
46 |
47 | Some notes:
48 | * The RTD mechanism is started by a cell formula that makes an `RTD` function call.
49 | * Excel then locates the RTD server with the COM activation. While COM allows the RTD Server to be out-of-process or even on another machine, I recommend, and Excel-DNA only supports, RTD servers that run in-process as part of the Excel add-in.
50 | * Excel calls `ServerStart` when an RTD Server is first activated, and `ConnectData` for each topic subscribed to.
51 | * The RTD Server might in turn connect to a data service that is local or remote, and which is polled by the RTD server or provides streaming updates.
52 | * The `UpdateNotify` call tell Excel that there is some data available from the RTD Server, but does not provide the individual data items. The means the RTD Server does not have to notify Excel for each individual data item.
53 | * When Excel is ready (the exact timing of this can be configured with the `ThrottleInterval` setting) Excel will fetch all updated values from the RTD Server in a single call.
54 | * Some care needs to be taken with the `UpdateNotify` callbacks to Excel. (This is the shaded part in the diagram.) Callbacks must be made on the main Excel thread, and must not be too frequent. Excel-DNA provides a base implementation of an RTD Server that assists in correct working of this part of the process.
55 | * Finally, Excel also provides `DisconnectData` and `ServerTerminate` calls to allow clean-up for a topic and the server respectively.
56 |
57 | These are some of the features of RTD that make it a uniquely powerful update feature for Excel.
58 | * High throughput to support many data items, and high update rates
59 | * Updates do not interfere with the user's interaction with Excel
60 | * Reliable tracking of formula locations, with notification when a data item is no longer referenced
61 |
62 | Alternative approaches like using the COM object model to update a workbook are far more limited.
63 |
64 | ## ExcelRtdServer helper class in Excel-DNA
65 |
66 | The Excel-DNA library contains a base class that can ease the implementation of an RTD server, in particular helping with the following:
67 |
68 | * It allows RTD servers to be used without prior admin registration of the COM library. This is done by making the COM registrations at runtime, and using the user keys in the registry if access to the machine keys are not available.
69 |
70 | * It provides internal data management for the updated topic values for the duration between the update call and the point where Excel reads the values with the `RefreshData` call. This includes the conversion of data types if need be, allowing long strings, errors and also (in Dynamic-Arrays versions of Excel) large arrays to be used in the RTD server as in normal UDFs.
71 |
72 | * It allowing the RTD Server topics to be updated topics from any thread, at any frequency. The callbacks to Excel are managed and called on the correct thread internally.
73 |
74 | In addition, the add-in can wrap the `=RTD(...)` call inside a user-friendly function, so instead of having the formula `=RTD("MyAddIn.RTD",,"MSFT")` the formula can be something like `=GetLiveData("MSFT")`.
75 |
76 | ## Build a basic RTD Server
77 |
78 | When implementing an RTD Server there are additional helpers in Excel-DNA and .NET libraries like the 'Reactive Extensions' to make it easier. But for this introduction I will show a simple implementation where the data source is just an object that has a timer to update the data values.
79 |
80 | We build an RTD server that provides two data topics:
81 | * A real-time ticking clock
82 | * A 'wave' of values changing in a cycle
83 |
84 | We've arrange the sample into three parts:
85 | * **DataSources** - does not depend on Excel or Excel-DNA, but encapsulates the data provider or, connection to back-end services.
86 | * **RTDServer** - implments the RTD Server code which interprets manages topic information and links the add-in to the data sources.
87 | * **Functions** - wrapper functions which make the RTD calls and present a friendly interface to the user.
88 |
89 | We'll look at each one in turn.
90 |
91 | ### The data source
92 |
93 | Our simple data source is implemented with a timer which will fire an event with the new value.
94 | An actual implementation might set up a link to a remote data source, and when an incoming message is received it fires an update event. Or it might make an asynchronous call, and notify when the call is complete.
95 |
96 | For the example we have two similar data sources - I'll show the `NowDataSource`
97 |
98 | ```cs
99 |
100 | // Represents a streaming source of 'current time' updates,
101 | // implementd by a simple timer
102 | public class NowDataSource: IDisposable
103 | {
104 | // This event 'publishes' new values of 'Now'
105 | public event Action NewValue;
106 |
107 | // The backing Timer object - it fires from a ThreadPool thread
108 | readonly Timer _timer;
109 |
110 | public NowDataSource()
111 | {
112 | _timer = new Timer(100);
113 | _timer.Elapsed += (s, e) => NewValue(DateTime.Now);
114 | _timer.Start();
115 | }
116 |
117 | // We use the IDisposable pattern to clean up any 'data source' resources
118 | // It's not really needed in this case, but shows where a clean-up step might appear
119 | public void Dispose()
120 | {
121 | _timer.Dispose();
122 | }
123 | }
124 |
125 | ```
126 |
127 | ### The RTD Server
128 |
129 | The Timer example's `RtdServer` class derives from the Excel-DNA base class for RTD servers, called `ExcelRtdServer`.
130 | The bulk of the implementation is in the `ConnectData` method, which handles the request to connect a new RTD topic.
131 |
132 | ```cs
133 | protected override object ConnectData(Topic topic, IList topicInfo, ref bool newValues)
134 | {
135 | var sourceName = topicInfo.FirstOrDefault();
136 | if (sourceName == "NOW")
137 | {
138 | var source = new NowDataSource();
139 | source.NewValue += dateTime => topic.UpdateValue($"{dateTime:HH:mm:ss}");
140 | _dataSources[topic] = source;
141 | return null; // We could also return an initial value
142 | }
143 |
144 | if (sourceName == "WAVE")
145 | {
146 | // Figure out the other topic parameters, which are strings in the topicInfo list.
147 | double amplitude = 1;
148 | double frequency = 1;
149 | if (topicInfo.Count >= 3)
150 | {
151 | double.TryParse(topicInfo[1], out amplitude);
152 | double.TryParse(topicInfo[2], out frequency);
153 | }
154 | var source = new WaveDataSource(amplitude, frequency);
155 | source.NewValue += val => topic.UpdateValue(val);
156 | _dataSources[topic] = source;
157 | return null;
158 | }
159 |
160 | // This is unexpected and an error in our code - the RTD Server is used with our own wrapper functions
161 | throw new ArgumentOutOfRangeException(nameof(topicInfo), $"Unknown topic {sourceName}");
162 | }
163 | ```
164 |
165 | Note that we don't need any registration step for the RTD server - Excel-DNA will take care of this at runtime.
166 |
167 | ### The wrapper functions
168 |
169 | Finally we define two user-defined functions that wrap the internal RTD call. The call the Excel-DNA RTD wrapper (which handles the runtime registration) by calling `XlCall.RTD`. These functions could also be marked up with the usual `ExcelFunction` and `ExcelArgument` attributes to provide descriptions etc.
170 |
171 | ```cs
172 | public static class Functions
173 | {
174 | public static object TimerNow()
175 | {
176 | return XlCall.RTD("TimerRTD.RtdServer", null, "NOW");
177 | }
178 |
179 | public static object TimerWave(double amplitude, double frequency)
180 | {
181 | return XlCall.RTD("TimerRTD.RtdServer", null, "WAVE", amplitude.ToString(), frequency.ToString());
182 | }
183 | }
184 | ```
185 |
186 | We can now call these functions from an Excel sheet as
187 |
188 | ```
189 | =TimerNow()
190 | =TimerWave(1, 0.5)
191 | ```
192 |
193 | ### Application.RTD.ThrottelInterval
194 |
195 | Excel has a setting that affects the rate at which values are refreshed from an RTD server.
196 | The default value is 2000 ms, which means available data from an RTD Server will be fetched at this interval.
197 | This setting can most easily be updated by opening the VBA interface, and entering the following into the immediate window:
198 |
199 | ```vba
200 | Application.RTD.ThrottleInterval = 500
201 | ```
202 |
203 | The will set the interval to 500 ms, allowing a good balance between update performance and system resources (a too short interval can lead to instability if Excel cannot recalulate and process the updates fast enough.
204 |
205 |
206 | ## References
207 |
208 | #### Excel-DNA samples
209 |
210 | The **RtdClocks** sample shows a number of implementation mechanisms
211 | https://github.com/Excel-DNA/Samples/tree/master/RtdClocks
212 |
213 | There is also a Visual Basic version of one of the RtdClocks projects at https://github.com/Excel-DNA/Samples/tree/master/RtdClocksVB/RtdClockVB-ExcelRtdServer
214 |
215 | #### Microsoft references
216 |
217 | For Excel 365 versions there were important [performance improvements](https://docs.microsoft.com/en-us/office/vba/excel/concepts/excel-performance/excel-performance-and-limit-improvements) made in early 2020. These include supporting RTD as a thread-safe function and improving the internal update performance in Excel. This will allow future versions of Excel-DNA to support thread-safe RTD wrapper functions.
218 |
219 | Some older information can be found here:
220 | * https://docs.microsoft.com/en-us/office/troubleshoot/excel/set-up-realtimedata-function
221 | * [Real-Time Data: Frequently asked questions](https://docs.microsoft.com/en-us/previous-versions/office/developer/office-xp/aa140060(v=office.10)) (from 2001!)
222 |
223 |
224 |
--------------------------------------------------------------------------------
/Testing/README.md:
--------------------------------------------------------------------------------
1 | # Excel-DNA Testing Helper
2 |
3 | _**Note: The Excel-DNA Testing Helper is in an early preview stage, and the design and functionality might change a lot in future. If you try it and have any feedback at all, positive or 'constructive' please let me know at govert@icon.co.za. If you already practice automated testing extensively I am particularly eager to hear of any suggestions you might have.**_
4 |
5 | [](http://www.youtube.com/watch?v=rUP15u9Z0ik "Excel-DNA Testing Helper - Preview")
6 |
7 | `ExcelDna.Testing` is a NuGet package and library that lets you develop automatic tests for Excel models and add-ins, including add-ins developed with Excel-DNA and VBA. Test code is written in C# or Visual Basic and is hosted by the popular [xUnit](https://xunit.net/) test framework, allowing automated tests to run from Visual Stuio or other standard test runners.
8 |
9 | Tests developed with the testing helper will run with the add-in loaded inside an Excel instance, and so allow you to test the interaction between an add-in and a real instance of Excel. This type of 'integration testing' can augment 'unit testing' where individual library features are tested in isolation. It is often in the interaction with Excel where the problematic aspects of an add-in are revealed, and developing automated testing for this environment has been difficult.
10 |
11 | The testing helper allows flexibility and power in designing automated Excel tests:
12 | * The test code can either run in a separate process that drives Excel through the COM object model, or can be loaded inside the Excel process itself, allowing use of both the COM object model and the C API from the test code.
13 | * Functions, macros and even ribbon commands can be tested.
14 | * Test projects can include pre-populated test workbooks containing spreadsheet models to test or test data.
15 |
16 | Running automated tests against Excel does introduce complications:
17 | * Testing requires a copy of Excel to be installed on the machine where the tests are run, so don't work well as automated test for 'continuous integration' environments.
18 | * Test outcomes can depend on the exact version of Excel the is used. This is both an advantage in identifying some
19 | * Integration tests with Excel can be quite slow to run compared to direct unit testing of functions.
20 |
21 | This tutorial will introduce the Excel-DNA testing helper, and show you how to create a test project for your Excel model or add-in.
22 |
23 | ## Background and prerequisites
24 |
25 | * **Visual Studio and Excel** -
26 | To use the testing helper you should already have Visual Studio 2019 and Excel (any version) installed.
27 | The example will mostly use C#, but Visual Basic is fully supported can also be used for creating your test project.
28 |
29 | * **xUnit** -
30 | [xUnit](https://xunit.net/) is a unit testing tool for the .NET Framework. The required xUnit libraries and runner will automatically installed with the `ExcelDna.Testing` package.
31 |
32 | If you are not familiar with unit test frameworks, or with xUnit in particular, you might want to look at or work through the XUnit Getting Started instructions for
33 | [Using .NET Framework with Visual Studio](https://xunit.net/docs/getting-started/netfx/visual-studio).
34 |
35 | ## Create a test project
36 | To start a new test project:
37 | * create a new 'Class Library (.NET Framework)' project (using C# or Visual Basic) and
38 | * install the `ExcelDna.Testing` package from the NuGet package manager (currently a pre-release package, so check the relevant checkbox or add the `-Pre` flag to the NuGet command line).
39 |
40 | After installing the `ExcelDna.Testing` package, the project will have the xUnit framework and Visual Studio runner for xUnit installed, so no additional packages are needed.
41 |
42 | ## Testing examples
43 |
44 | ### *ExcelTest* - A simple Excel test
45 |
46 | This is a simple test the exercises Excel to
47 |
48 | ```c#
49 | using System;
50 | using Xunit;
51 | using Microsoft.Office.Interop.Excel;
52 | using ExcelDna.Testing;
53 |
54 | // This attribute MUST be present somewhere in the test project to connect xUnit to the ExcelDna.Testing framework.
55 | [assembly: TestFramework("Xunit.ExcelTestFramework", "ExcelDna.Testing")]
56 |
57 | namespace ExcelTest
58 | {
59 | public class CalculationTests : IDisposable
60 | {
61 | Workbook _testWorkbook;
62 |
63 | public CalculationTests()
64 | {
65 | // Get hold of the Excel Application object and create a workbook
66 | _testWorkbook = Util.Application.Workbooks.Add();
67 | }
68 |
69 | public void Dispose()
70 | {
71 | // Clean up our workbook without saving changes
72 | _testWorkbook.Close(SaveChanges: false);
73 | }
74 |
75 | [ExcelFact]
76 | public void NumbersAddCorrectly()
77 | {
78 | // We'll just do our test on the first sheet
79 | var ws = _testWorkbook.Sheets[1];
80 |
81 | // Write two numbers to the active sheet, and a formula that adds them, together
82 | ws.Range["A1"].Value = 2.0;
83 | ws.Range["A2"].Value = 3.0;
84 | ws.Range["A3"].Formula = "= A1 + A2";
85 |
86 | // Read back the value from the cell with the formula
87 | var result = ws.Range["A3"].Value;
88 |
89 | // Check that we have the expected result
90 | Assert.Equal(5.0, result);
91 | }
92 | }
93 | }
94 | ```
95 |
96 | To run the tests in Visual Studio, open the Test Explorer tool window, check that the test is correctly discovered, and press Run.
97 |
98 | #### Discussion
99 |
100 | Some notable aspects of the above code snippet:
101 | * The `Xunit.ExcelTestFramework` is configured through the `Xunit.TestFramework` assembly-scope attribute.
102 | * Tests are public instance methods marked by an `[ExcelDna.Testing.ExcelFact]` attribute.
103 | * Test code can access Excel `Application` object with a call to `ExcelDna.Testing.Util.Application`. This will refer to the correct Excel root COM object, whether the test code is running in-process or out-of-process (see below).
104 | * We use the class constructor and `IDispose` interface to set up and tear down some
105 |
106 | ### *AddInTest* - Testing an Excel-DNA add-in
107 |
108 | For this test project we create a simple Excel-DNA add-in with a single UDF, and then implement a test project that exercises the add-in function inside Excel.
109 |
110 | ```c#
111 | using System;
112 | using Xunit;
113 | using ExcelDna.Testing;
114 | using Microsoft.Office.Interop.Excel;
115 |
116 | // This attribute MUST be present somewhere in the test project to connect xUnit to the ExcelDna.Testing framework.
117 | // It could also be placed in the Properties\AssemblyInfo.cs file.
118 | [assembly:Xunit.TestFramework("Xunit.ExcelTestFramework", "ExcelDna.Testing")]
119 |
120 | namespace Sample.Test
121 | {
122 | // The path give here is relative to the output directory of the test project.
123 | // Setting an AddIn options here will request the test runner to load this add-in into Excel before the tests start.
124 | // The name here excludes the ".xll" or "64.xll" suffix. The test runner will choose according to the Excel bitness where it runs.
125 | [ExcelTestSettings(AddIn = @"..\..\..\Sample\bin\Debug\Sample-AddIn")]
126 | public class ExcelTests : IDisposable
127 | {
128 | // This workbook will be available to all tests in the class
129 | Workbook _testWorkbook;
130 |
131 | // The test class constructor will configure the required environment for the tests in the class.
132 | // In this case it creates a new Workbook that will be shared by the tests
133 | public ExcelTests()
134 | {
135 | var app = Util.Application;
136 | _testWorkbook = app.Workbooks.Add();
137 | }
138 |
139 | // Clean-up for the class is in the IDisposable.Dispose implementation
140 | public void Dispose()
141 | {
142 | _testWorkbook.Close(SaveChanges: false);
143 | }
144 |
145 | // This test just interacts with Excel
146 | [ExcelFact]
147 | public void ExcelCanAddNumbers()
148 | {
149 | var ws = _testWorkbook.Sheets[1];
150 |
151 | ws.Range["A1"].Value = 2.0;
152 | ws.Range["A2"].Value = 3.0;
153 | ws.Range["A3"].Formula = "=A1 + A2";
154 |
155 | var result = ws.Range["A3"].Value;
156 |
157 | Assert.Equal(5.0, result);
158 | }
159 |
160 | // This test depends on the AddIn value set in the class's ExcelTestSettings attributes
161 | // With the Sample-AddIn loaded, the function should work correctly.
162 | [ExcelFact]
163 | public void AddInCanAddNumbers()
164 | {
165 | var ws = _testWorkbook.Sheets[1];
166 |
167 | ws.Range["A1"].Value = 2.0;
168 | ws.Range["A2"].Value = 3.0;
169 | ws.Range["A3"].Formula = "=AddThem(A1, A2)";
170 |
171 | var result = ws.Range["A3"].Value;
172 |
173 | Assert.Equal(5.0, result);
174 | }
175 |
176 | // Before this test is run, a pre-created workbook will be loaded
177 | // It has been added to the test project and configured to always be copied to the output directory
178 | [ExcelFact(Workbook = "TestBook.xlsx")]
179 | public void WorkbookCheckIsOK()
180 | {
181 | // Get the pre-loaded workbook using the Util.Workbook property
182 | var wb = Util.Workbook;
183 | var ws = wb.Sheets["Check"];
184 | Util.Application.CalculateFull();
185 |
186 | var result = ws.Range["A1"].Value;
187 |
188 | Assert.Equal("OK", result);
189 | }
190 | }
191 | }
192 |
193 | ```
194 |
195 | #### Discussion
196 |
197 | This snippet is from the accompanying sample solution, which also contains an Excel-DNA add-in project (creating the `Sample-AddIn` add-in referred to in the `ExcelTestSettings` attribute.
198 | The add-in contains a single function called `AddThem` which is given a first test in the sample test project.
199 |
200 | Note that the sample test project does not reference the add-in project - all interaction is through Excel. This ensures that we are truly testing the behaviour of the add-in when running in Excel.
201 |
202 | ## Solution layout suggestion
203 |
204 | For supporting both isolated unit testing and Excel-based integration testing, one possible solution layout is as follows:
205 |
206 | * **MyLibrary** - contains the core functionality, e.g. calculations or external data access methods. Does not reference Excel-DNA or Excel.
207 | * **MyLibrary.Test** - unit test project for the functionality in `MyLibrary`, using the standard `xunit` and `xunit.runner.visualstudio` packages as described in the [xUnit documentation](https://xunit.net/docs/getting-started/netfx/visual-studio).
208 | * **MyAddIn** - Excel AddIn to integrate the functionality from `MyLibrary` into Excel, using the `ExcelDna.AddIn` package. Functions declared here contain Excel-specific attributes and information, and deal with the Excel data types and error values if needed before calling into 'Library' methods.
209 | * **MyAddIn.Test** - integration testing project for 'MyAddIn', using the `ExcelDna.Testing` package. Does not reference the `MyAddIn` or `MyLibrary` projects, just interacts with them through the Excel tests.
210 |
211 | ## Reference
212 |
213 | ### Test helper classes
214 |
215 | These types are declared in the `ExcelDna.Testing` assembly.
216 |
217 | * *`Xunit.ExcelTestFramework`* - this is the xUnit integration class, and should be indicated in the assembly-scope TestFramework attribute inside the test project:
218 | ```c#
219 | [assembly:TestFramework("Xunit.ExcelTestFramework", "ExcelDna.Testing")]
220 | ```
221 |
222 | * *`ExcelDna.Testing.ExcelFactAttribute`* - this is the method-scope attribute to indicate that a method implements a test.
223 | ```c#
224 | [ExcelFact]
225 | public void NumbersAddCorrectly() { ... }
226 | ```
227 | * *`ExcelDna.Testing.ExcelTestSettingsAttribute`* - this is a class-scope attribute that configures settings for all tests in a class.
228 | ```c#
229 | [ExcelTestSettings(OutOfProcess=true)]
230 | public class CalculationTests { ... }
231 | ```
232 |
233 | * *`ExcelDna.Testing.Util`* - provides access to the root Excel Application object, any pre-loaded Workbook and the directory where the test assembly is located.
234 |
235 | ### In-process vs out-of-process test running
236 | The test methods can execute in two environments:
237 |
238 | * Inside the Excel process (the default) - The test runner will load a helper add-in (called ExcelAgent) into the Excel process, and ExcelAgent in turn will load the test library. Test will then run inside the Excel process, which improves performance and gives access to the the Excel C API - `XlCall.Excel(...)` - from the test code.
239 |
240 | * Out-of-Process - There is also an option to run tests out-of-process. This is indicated by setting the `OutOfProcess` property of the `ExcelFact` or `ExcelSettings` attribute on the method or class respectively. In this case the test assembly will run inside the xUnit test runner and communicate with Excel via the stardard cross-process COM interop. In this approach there is no additional test agent loaded into the Excel process.
241 |
242 | ### Error values - COM vs C API
243 |
244 | One of the motivations for doing integration testing of an add-in in Excel is to ensure the behaviour of a function when receiving various unexpected values from Excel is correct. In particular, a function running in Excel might receive input values like 'Empty', 'Missing' or some Excel-specific error value like '#VALUE'. Depending on how the test code is reading values from Excel, these additional data types would be represented in different ways.
245 | It is not discussed here, but when running inside the Excel process, the C API (XlCall.Excel) can often improve the performance of Excel sheet interactions, and simplify dealing with the various Excel error values.
246 |
247 | ### Thanks
248 |
249 | Thank you very much to Sergey Vlasov for developing the `ExcelDna.Testing` framework.
250 |
251 |
--------------------------------------------------------------------------------
/SpecialTopics/DynamicArrays/README.md:
--------------------------------------------------------------------------------
1 | # Excel-DNA and Dynamic Arrays
2 |
3 | The support for 'Dynamic Arrays' is a major new Excel feature available in the Office 365 versions of Excel since 2020.
4 | There are many excellent resources available that explore the power of dynamic arrays - I provide a few links below as introduction to the topic.
5 | In this tutorial I will show how dynamic arrays interact with user-defined functions defined in Excel-DNA add-ins.
6 |
7 | [](http://www.youtube.com/watch?v=XUoN5NUBL2M "Excel-DNA and Dynamic Arrays")
8 |
9 | ## Background
10 |
11 | For this tutorial I will assume you are already familiar with the fundamentals of Excel-DNA and the dynamic arrays feature in Excel.
12 | For general background on dynamic arrays, there are many excellent introductions available - I suggest a few below.
13 |
14 | #### Dynamic Array links
15 |
16 | [Excel dynamic arrays, functions and formulas](https://www.ablebits.com/office-addins-blog/2020/07/08/excel-dynamic-arrays-functions-formulas/) by Svetlana Cheusheva from AbleBits provides a friendly and comprehensive introduction to dynamic arrays.
17 |
18 | Some of Microsoft's notes on Dynamic Arrays:
19 | * [Preview of Dynamic Arrays in Excel](https://techcommunity.microsoft.com/t5/excel-blog/preview-of-dynamic-arrays-in-excel/ba-p/252944)
20 | * [Dynamic arrays and spilled array behavior](https://support.office.com/en-us/article/dynamic-arrays-and-spilled-array-behavior-205c6b06-03ba-4151-89a1-87a7eb36e531)
21 | * [Dynamic array formulas in non-dynamic aware Excel](https://support.office.com/en-us/article/dynamic-array-formulas-in-non-dynamic-aware-excel-696e164e-306b-4282-ae9d-aa88f5502fa2)
22 | * [Dynamic array formulas vs. legacy CSE array formulas](https://support.microsoft.com/en-us/office/dynamic-array-formulas-vs-legacy-cse-array-formulas-ca421f1b-fbb2-4c99-9924-df571bd4f1b4)
23 | * [Implicit intersection operator: @](https://support.office.com/en-us/article/implicit-intersection-operator-ce3be07b-0101-4450-a24e-c1c999be2b34)
24 |
25 | Bill Jelen (Mr. Excel) goes into the topic in great details in an [e-book about Dynamic Arrays](https://www.mrexcel.com/products/excel-dynamic-arrays-straight-to-the-point-2nd-edition/), and
26 | a [Youtube video](https://youtu.be/ViSEZLPmRvw) showing how powerful the dynamic arrays and mathcing new formulas are.
27 |
28 | Leila Gharani has an [Excel 365 and Dynamic Arrays video playlist](https://www.youtube.com/playlist?list=PLmHVyfmcRKyyPFY31LldHWcJdLzGUPTSP) with lots of tips and powerful applications.
29 |
30 | And you'll find lots more with a Bing search and on YouTube.
31 |
32 | ## Dynamic arrays and Excel-DNA user-defined functions
33 |
34 | The overall message is that dynamic arrays Excel and Excel-DNA add-ins work very well together.
35 | Making add-in functions 'array-friendly' provide elegant solutions to problems that required awkward workarounds in older Excel versions.
36 |
37 | ### Returning arrays
38 |
39 | I'll start with a simple function that returns an array result - just some strings with an array size that is determined by the input parameters.
40 |
41 | ```cs
42 | public static object dnaMakeArray(int rows, int cols)
43 | {
44 | object[,] result = new object[rows, cols];
45 | for (int i = 0; i < rows; i++)
46 | {
47 | for (int j = 0; j < cols; j++)
48 | {
49 | result[i, j] = $"{i},{j}";
50 | }
51 | }
52 | return result;
53 | }
54 | ```
55 |
56 | Used in a dynamic arrays version of Excel, the result will automatically spill to the right size.
57 | As the inputs change (the number of rows and columns) the resulting spill region automatically resizes.
58 |
59 | A few things to note:
60 | * Arrays with 0 size produce an error
61 | * Arrays with a single element don't result in a spill region (no shadow / blue border in the cell)
62 | * If there is no room to spill, we get a `#SPILL!` error
63 |
64 | ### Array inputs
65 |
66 | Next we look at a simple function that describes an array input value.
67 |
68 | ```cs
69 | // Describes the size of the input array
70 | public static object dnaDescribeArray(object[,] input)
71 | {
72 | var rows = input.GetLength(0);
73 | var cols = input.GetLength(1);
74 |
75 | return $"Input: {rows} rows, {cols} columns";
76 | }
77 | ```
78 |
79 | The function correctly gets the full (and dynamically resized) array when passed a spill reference like `=A1#`.
80 |
81 | If the input parameter is type `object`, Excle may pass a single value or array.
82 | And if the parameter is marked as `AllowReference=true` we might get a sheet reference in the form of an `ExcelReference` object.
83 | This function shows the exact type and details of the input.
84 | ```cs
85 | [ExcelFunction(IsMacroType =true)] // IsMacroType is only required for the handl xlfReftext call below.
86 | public static string dnaDescribe([ExcelArgument(AllowReference = true)] object arg)
87 | {
88 | if (arg is double)
89 | return "Double: " + (double)arg;
90 | else if (arg is string)
91 | return "String: " + (string)arg;
92 | else if (arg is bool)
93 | return "Boolean: " + (bool)arg;
94 | else if (arg is ExcelError)
95 | return "ExcelError: " + arg.ToString();
96 | else if (arg is object[,])
97 | // The object array returned here may contain a mixture of different types,
98 | // reflecting the different cell contents.
99 | return string.Format("Array[{0},{1}]", ((object[,])arg).GetLength(0), ((object[,])arg).GetLength(1));
100 | else if (arg is ExcelMissing)
101 | return "<>"; // Would have been System.Reflection.Missing in previous versions of ExcelDna
102 | else if (arg is ExcelEmpty)
103 | return "<>"; // Would have been null
104 | else if (arg is ExcelReference)
105 | // Calling xlfRefText here requires IsMacroType=true for this function.
106 | return "Reference: " + XlCall.Excel(XlCall.xlfReftext, arg, true);
107 | else
108 | return "!? Unheard Of ?!";
109 | }
110 | ```
111 |
112 | Trying this out with various array inputs, we can see the following:
113 | * a simple reference to the array root cell results in a single value
114 | * a spill reference with a `#`, like `A1#` will refer to the whole array
115 | * we don't get information that tells us the input is a spill reference - it is just a reference to the resulting spill region itself
116 |
117 | ### Implicit intersection
118 |
119 | Let's now look at implicit intersection and the @-operator, and how these work with Excel-DNA functions.
120 |
121 | The `AddThem` starter function takes two numbers and adding, and looks like this.
122 | ```cs
123 | public static double dnaAddThem(double val1, double val2)
124 | {
125 | return val1 + val2;
126 | }
127 | ```
128 |
129 | For a simple function like `dnaAddThem` we can see the difference between `=@dnaAddThem(...)` and `=dnaAddThem(...)`. The @-operator version performs the implicit intersection in the corresponding row / column of array inputs, which is the normal behaviour for formulas under pre-DA Excel. The plain `=dnaAddThem(..)` version will translate to a Ctrl+Shift+Enter array in pre-DA Excel. This difference will appear again in the `Range.Formula` vs `Range.Formula2` context below.
130 |
131 | ### Compatibility with non-dynamic arrays Excel versions
132 |
133 | To ensure compatibility in the calculation results for a workbook between DA Excel and pre-DA Excel, some formulas are transformed (actually displayed in different ways) between the versions. This particularly affects the new array-related built-in functions added in DA Excel, and any UDFs used (VBA or Excel-DNA based UDFs).
134 |
135 | Looking at the VersionCompare.xlsx workbook we see:
136 | * Every simple function call like `=dnaAddThem(1,2)` in DA Excel corresponds with a Ctrl+Shift+Enter call like `{=dnaAddThem(2,3)}`in pre-DA Excel.
137 | * A call with the implicit intersection @-operator like `=@dnaAddThem(1,2)` in DA Excel corresponds with a simple call like `=dnaAddThem(2,3)`in pre-DA Excel.
138 | * Functions not defined in pre-DA Excel appear in formulas as `=_xlfn.FILTER(...)`, while @-operator spill references appear as `=_xlfn.ANCHORARRAY(...)`.
139 | * Spill references (with #-references) are converted to fixed array formulas with the ???
140 |
141 | Below I discuss a partial implementation of resizing arrays that can be used in older Excel.
142 |
143 | ### COM Object Model - `Range.Formula2` to avoid '@'-formulas; `HasSpill` and `SpillRange`
144 |
145 | The COM object model has been extended with some extra members added to the `Range` object related to dynamic arrays.
146 | The first things to note is that a formula containing any UDF added to Excel like this:
147 | ```vb
148 | Application.Range("A1").Formula = "=dnaAddThem(1,2)"
149 | ```
150 | will be processed and displayed as `=@dnaAddThem(1,2)`, with the @-implicit intersection operator added.
151 | This transformation of the formula ensures that the code setting `Range.Formula` has exactly the same effect in older Excel versions as in DA Excel.
152 |
153 | DA Excel adds a new `Formula2` member to the `Range` object to set formulas that are compatible with dynamic arrays, e.g.
154 | ```vb
155 | Application.Range("A1").Formula = "=dnaAddThem(1,2)"
156 | ```
157 |
158 | Further information is available on the Microsoft page discussing [`Formula vs. Formula2`]([Formula vs Formula2](https://docs.microsoft.com/en-us/office/vba/excel/concepts/cells-and-ranges/range-formula-vs-formula2)
159 | ).
160 |
161 | Further Range information properties have been added to get information about the Spill range of a cell.
162 | ```vb
163 | Application.Range("A1").HasSpill
164 | Application.Range("A1").SpillRange
165 | ```
166 |
167 | ### Array aware functions
168 |
169 | It's possible to make a general-purpose function that transforms a single-input, single-output function like `dnaAddThem` into an array-aware version.
170 | With such a helper, we can write a formula like `=dnaArrayMap2(dnaAddThem, A1:A10, B1:B10)` where we pass the single-valued `dnaAddThem` function without parentheses into the transformation function, where it will be called for every pair of inputs.
171 | The [`ArrayMap`](https://github.com/Excel-DNA/Samples/tree/master/ArrayMap) sample project explores in more details how this can be done.
172 |
173 | ### `ExcelReference` inputs and results
174 |
175 | There are some cases where we don't need to know the input values, but can provide processing based on the input array size.
176 | An example would be a function that returns only the first few rows of an array:
177 |
178 | ```cs
179 | public static object dnaArrayGetHead([ExcelArgument(AllowReference=true)] object input, int numRows)
180 | {
181 | if (input is ExcelReference inputRef)
182 | {
183 | var rowFirst = inputRef.RowFirst;
184 | var rowLast = Math.Min(inputRef.RowFirst + numRows, inputRef.RowLast);
185 | return new ExcelReference(rowFirst, rowLast, inputRef.ColumnFirst, inputRef.ColumnLast, inputRef.SheetId);
186 | }
187 | else if (input is object[,] inputArray)
188 | {
189 | var rows = inputArray.GetLength(0);
190 | var cols = inputArray.GetLength(1);
191 |
192 | var resultRows = Math.Min(rows, numRows);
193 | var result = new object[resultRows, cols];
194 | for (int i = 0; i < resultRows; i++)
195 | {
196 | for (int j = 0; j < cols; j++)
197 | {
198 | result[i, j] = inputArray[i, j];
199 | }
200 | }
201 | return result;
202 | }
203 | else
204 | {
205 | // Just a scalar value
206 | if (numRows >= 1)
207 | {
208 | return input;
209 | }
210 | }
211 | // Otherwise we have an error - return #VALUE!
212 | return ExcelError.ExcelErrorValue;
213 | }
214 | ```
215 |
216 | ### RTD-based async and streaming functions
217 |
218 | Under dynamic arrays Excel, async and streaming functions that are implemented in Excel-DNA with the RTD feature, can return array results without any problems.
219 | In previous versions of Excel there were sometimes problems when arrays are returned in these cases, and the results could not be resized automatically.
220 | These issues are now successfully resolved.
221 |
222 | A small example of an async function returning an array after a specific delay:
223 |
224 | ```cs
225 | public static object dnaMakeArrayAsync(int delayMs, int rows, int cols)
226 | {
227 | var funcName = nameof(dnaMakeArrayAsync);
228 | var args = new object[] { delayMs, rows, cols };
229 |
230 | return ExcelAsyncUtil.Run(funcName, args, () =>
231 | {
232 | Thread.Sleep(delayMs);
233 | object[,] result = new object[rows, cols];
234 | for (int i = 0; i < rows; i++)
235 | {
236 | for (int j = 0; j < cols; j++)
237 | {
238 | result[i, j] = $"{i}|{j}";
239 | }
240 | }
241 | return result;
242 | });
243 | }
244 | ```
245 |
246 | ### 'Classic' ArrayResizer
247 |
248 | Before the advent of dynamic arrays in Excel, I created a helper function to manage array results from functions called the `ArrayResizer`.
249 | Find more details in the [ArrayResizer sample on GitHub](https://github.com/Excel-DNA/Samples?arrayResizer).
250 |
251 | One of the limitations of the ArrayResizer is that RTD-based async and streaming array functions are not supported.
252 |
253 | #### Testing for whether the running Excel instance supports dynamic arrays
254 |
255 | In the ArrayResizer sample, and otherwise, it might be useful to know if an Excel instance supports dynamic arrays.
256 | This (hidden) function check to the presence of the `=FILTER` built-in function to determine this:
257 |
258 | ```cs
259 | static bool? _supportsDynamicArrays;
260 | [ExcelFunction(IsHidden=true)]
261 | public static bool dnaSupportsDynamicArrays()
262 | {
263 | if (!_supportsDynamicArrays.HasValue)
264 | {
265 | try
266 | {
267 | var result = XlCall.Excel(614, new object[] { 1 }, new object[] { true });
268 | _supportsDynamicArrays = true;
269 | }
270 | catch
271 | {
272 | _supportsDynamicArrays = false;
273 | }
274 | }
275 | return _supportsDynamicArrays.Value;
276 | }
277 | ```
278 |
--------------------------------------------------------------------------------