Skip to content

Commit bea3896

Browse files
author
sagi
committed
Add SDK-style guide, .NET vs .NET6 article, Getting Started page
1 parent f7edfc2 commit bea3896

File tree

8 files changed

+296
-2
lines changed

8 files changed

+296
-2
lines changed

‎docs/getting-started.md‎

Lines changed: 101 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,104 @@
11
---
22
sidebar_position: 1
33
title: "Getting Started"
4-
---
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
The easiest way to make an Excel-DNA addin is to create to follow these simple steps:
10+
11+
### Create a Project in Visual Studio
12+
13+
1. Select **Create a new project** and then select **Class Library** in either Visual Basic, C# or F#.
14+
2. Enter a name for the project.
15+
3. Under Framework, select the **.NET 6.0 (Long-term support)** option.
16+
17+
### Write the Addin Code
18+
19+
1. Depending on the language of choice, in the .csproj, .vbproj, or .fsproj file, change the value between the *TargetFramework* tags to **net6.0-windows**.
20+
21+
2. Add the following under </PropertyGroup\>:
22+
23+
```xml
24+
<ItemGroup>
25+
<PackageReference Include="ExcelDna.Addin" Version="*-*"/>
26+
</ItemGroup>
27+
```
28+
29+
Depending on the language of choice (C#, Visual Basic.NET or F#), add the following code to the class file (.cs, .vb or .fs):
30+
31+
<Tabs>
32+
<TabItem value="csharp" label="C#">
33+
34+
```csharp
35+
using ExcelDna.Integration;
36+
37+
public static class MyFunctions
38+
{
39+
[ExcelFunction(Description = "My first .NET function")]
40+
public static string SayHello(string name)
41+
{
42+
return "Hello " + name;
43+
}
44+
}
45+
```
46+
</TabItem>
47+
<TabItem value="vbnet" label="VB.Net">
48+
49+
```vbnet
50+
Imports ExcelDna.Integration
51+
52+
Public Module MyFunctions
53+
<ExcelFunction(Description:="My first .NET function")>
54+
Public Function SayHello(ByVal name As String) As String
55+
Return "Hello " & name
56+
End Function
57+
End Module
58+
```
59+
</TabItem>
60+
<TabItem value="fsharp" label="F#">
61+
62+
```fsharp
63+
module MyFunctions =
64+
open Excel.Integration
65+
66+
[<ExcelFunction(Description = "My first .NET function")>]
67+
let SayHello name = "Hello " + name
68+
```
69+
70+
</TabItem>
71+
</Tabs>
72+
73+
### Compile and Run
74+
75+
1. To compile the solution, ensure to explicitly select **Build Solution**, under the **Build** menu item at the top menu bar. Alternatively, press the Ctrl+Shift+B key combination.
76+
77+
2. To run the code after compilation, select **Start Debugging**, under the **Debug** menu item at the top menu bar. Alternatively, press F5.
78+
79+
3. When the solution is running, Excel will open and a security notice will pop-up. Select the **Enable this add-in for this session only.** option.
80+
81+
4. In Excel, open a new workbook and use the newly created function:
82+
83+
```
84+
=SayHello("World!")
85+
```
86+
87+
### Debug
88+
89+
It is possible to debug the solution through Visual Studio. To do so, follow these simple steps while the solution is running:
90+
91+
1. In Visual Studio, navigate to the line of code that is required debugging.
92+
2. Create a breakpoint by selecting **Toggle Breakpoint**, under the **Debug** menu item at the top menu bar. Alternatively, press F9. The line of code would be highlighted in red.
93+
3. In Excel, use the function that is needed to be debugged. The execution of the function will be caught by Visual Studio at the breakpoint. The line of code would be highlighted in yellow.
94+
4. In Visual Studio, inspect the code and change it as required. Once done, select **Continue**, under the **Debug** menu item at the top bar. Alternatively, press F5.
95+
5. Finally, see the new results reflect in Excel upon completion of execution of the debugged function.
96+
97+
### Distribution
98+
99+
In order to use the newly created add-in, users would require the .NET 6 runtime to be installed. Additionally, the correct architecture (32bit or 64bit) of the installation should be taken into consideration.
100+
101+
### Transitioning to .NET 6
102+
103+
In recent years, Microsoft has moved from the older .NET Framework to the newer, cross-platform .NET 6. The transition brings new features, better performance, and a simpler project format. For more details, see [.NET Framework vs. .NET 6](../../../dotnet_framework_vs_dotnet6) and the walkthrough guide [Updating Project File to SDK-style](./guides-basic/updating-project-file-to-sdk-style).
104+

‎docs/guides-basic/assets/sdk_style1.png‎

14.5 KB
Loading

‎docs/guides-basic/assets/sdk_style2.png‎

102 KB
Loading

‎docs/guides-basic/assets/sdk_style3.png‎

14.8 KB
Loading

‎docs/guides-basic/assets/sdk_style4.png‎

7.05 KB
Loading

‎docs/guides-basic/updating-project-file-to-sdk-style.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: "Updating Project File to SDK-Style"
3+
---
4+
5+
.NET SDK-style projects are a new project format introduced with .NET Core 2.0, which allows developers to build and manage .NET projects in a simplified way. Unlike the traditional .NET Framework project format, which requires a complex XML-based configuration file, SDK-style projects use a simpler and more intuitive format based on a set of pre-defined templates.
6+
7+
Each project is inherently different however, at times the steps taken toward updating the project may be similar in various cases. The steps below demonstrate the steps taken to convert [RTDClock-IExcelObervable](https://github.com/Excel-DNA/Samples/tree/master/RtdClocks/RtdClock-IExcelObservable) (part of the RTDClocks solution, which can be found in [Excel-DNA's Samples repository](https://github.com/Excel-DNA/Samples)) from the XML-based configuration file to its equivalent SDK-style:
8+
9+
## Conversion Steps
10+
11+
1. Open the RtdClocks solution in Visual Studio. While loading the solution, a question regarding unsupported framework may pop-up for each of the projects within the solution. In that case, select 'Do not load this project.' for all other projects but RtdClock-IExcelObervable, where the selection should be as per the figure below:
12+
![Capture](./assets/sdk_style1.png)
13+
14+
2. When selecting RtdClock-IExcelObervable in the Solution Explorer window (notice: all projects will be marked as unloaded), the .csproj file content will appear, showing the traditional XML-based syntax like so:
15+
![Capture](./assets/sdk_style2.png)
16+
17+
**Note:** To view the content of a .csproj file for projects that are not formatted with the .NET SDK-style, it is required that the project be unloaded in Visual Studio.
18+
19+
3. Replace the content of the file with the following:
20+
21+
```xml
22+
<Project Sdk="Microsoft.NET.Sdk">
23+
24+
<PropertyGroup>
25+
<TargetFrameworks>net472;net6.0-windows</TargetFrameworks>
26+
</PropertyGroup>
27+
28+
</Project>
29+
```
30+
Notice that between the <TargetFramworks\> tags 2 values exist. By targeting both frameworks, the project can be built and run on both older Windows systems that support .NET Framework 4.7.2, as well as newer systems that support .NET 6.0. that is optimised specifically for Windows. depends on the
31+
32+
**Note:** Replacing the old XML format with the new SDK-style does not require the target framework to change. It is also important to remember that the targeted framework values are dependent on several factors, such as the features and APIs required by the project, the platform on which the application will be deployed, and the compatibility requirements of any libraries or dependencies used by the project.
33+
34+
4. Reload the project by right-clicking on the project in Solution Explorer and selecting 'Reload Project':
35+
![Capture](./assets/sdk_style3.png)
36+
37+
5. A list of dependencies exists in the packages.config file:
38+
39+
```xml
40+
<?xml version="1.0" encoding="utf-8"?>
41+
<packages>
42+
<package id="ExcelDna.AddIn" version="1.1.1" targetFramework="net45" developmentDependency="true" />
43+
<package id="ExcelDna.Integration" version="1.1.0" targetFramework="net45" />
44+
</packages>
45+
```
46+
47+
These dependencies need to be included in the SDK-style .csproj file. Specifically for this project, only ExcelDna.AddIn is required. Include the following lines to the .csproj between the <Project\> tags:
48+
49+
```xml
50+
<ItemGroup>
51+
<PackageReference Include="ExcelDna.Addin" Version="*-*" />
52+
</ItemGroup>
53+
```
54+
55+
6. Delete the following files from the project as they are no longer needed:
56+
57+
* packages.json
58+
* RtdClock-IExcelObservable-AddIn.dna
59+
* Properties/AssemblyInfo.cs
60+
* Properties/ExcelDna.Build.props (**Note:** Any customized content should be added to the .csproj file)
61+
62+
7. Similar to Step 4, right-click on the project in Solution Explorer and select 'Rebuild'.
63+
64+
8. Once the project was built successfully, it is possible to select which of the target frameworks (were set in Step 3), should the project run under:
65+
66+
![Capture](./assets/sdk_style4.png)
67+
68+
69+
70+
## Converting the Entire Solution
71+
72+
Converting the entire solution requires a few modifications to the steps described above.
73+
74+
* In Step 1, ensure to select the same update option for all projects rather than 'Do not load this project.'.
75+
76+
* In Step 5, specifically for [RtdClock-Rx](https://github.com/Excel-DNA/Samples/tree/master/RtdClocks/RtdClock-Rx) and [RtdClock-Rx-Registration](https://github.com/Excel-DNA/Samples/tree/master/RtdClocks/RtdClock-Rx-Registration), the dependencies list includes a few more libraries. Ensure to include them in addition to further modifications as per below:
77+
78+
**RtdClock-Rx**
79+
80+
```xml
81+
<!-- Add a PropertyGroup that will only be active for the net472 target framework
82+
Set up the additional assemblies to pack
83+
We want to include all libraries in the output directory
84+
(For .NET 6 we use the .deps.json file to find the assemblies to pack, so this property is not needed)
85+
-->
86+
<PropertyGroup Condition="'$(TargetFramework)' == 'net472'">
87+
<ExcelAddInInclude>System.Reactive.dll;System.Runtime.CompilerServices.Unsafe.dll;System.Threading.Tasks.Extensions.dll</ExcelAddInInclude>
88+
</PropertyGroup>
89+
90+
<ItemGroup>
91+
<PackageReference Include="ExcelDna.Addin" Version="*-*" />
92+
<PackageReference Include="System.Reactive" Version="*-*" />
93+
</ItemGroup>
94+
```
95+
96+
**RtdClock-Rx-Registration**
97+
98+
```xml
99+
<!-- This property prevents the auto-registration of Excel functions (by default all public static functions)
100+
We will use the Registration helper and a call in the AutoOpen method to register functions explicitly
101+
-->
102+
<PropertyGroup>
103+
<ExcelAddInExplicitRegistration>true</ExcelAddInExplicitRegistration>
104+
</PropertyGroup>
105+
106+
<!-- Add a PropertyGroup that will only be active for the net472 target framework
107+
Set up the additional assemblies to pack
108+
We want to include all libraries in the output directory
109+
(For .NET 6 we use the .deps.json file to find the assemblies to pack, so this property is not needed)
110+
-->
111+
<PropertyGroup Condition="'$(TargetFramework)' == 'net472'">
112+
<ExcelAddInInclude>ExcelDna.Registration.dll;System.Reactive.dll;System.Runtime.CompilerServices.Unsafe.dll;System.Threading.Tasks.Extensions.dll</ExcelAddInInclude>
113+
</PropertyGroup>
114+
115+
<ItemGroup>
116+
<PackageReference Include="ExcelDna.Addin" Version="*-*" />
117+
<PackageReference Include="ExcelDna.Registration" Version="*-*" />
118+
<PackageReference Include="System.Reactive" Version="*-*" />
119+
</ItemGroup>
120+
```
121+
122+
* In Step 6, make sure the relevant .dna files are deleted.
123+

‎src/components/HomepageFeatures/index.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ export default function HomepageFeatures() {
177177
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Pz915C0iZL4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="true"></iframe>
178178
</ol>
179179
<h3>Distribution</h3>
180-
<p>In order to use the newly created add-in, users would require the .NET 6 runtime to be installed. Additionally, the correct architecutre (32bit or 64bit) of the installation should be taken into consideration.</p>
180+
<p>In order to use the newly created add-in, users would require the .NET 6 runtime to be installed. Additionally, the correct architecture (32bit or 64bit) of the installation should be taken into consideration.</p>
181181
</div>
182182
<hr />
183183
<div>

‎src/pages/dotnet_framework_vs_dotnet6.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
2+
3+
# .NET Framework vs .NET 6
4+
5+
.NET Framework and .NET 6 are two different versions of Microsoft's .NET technology stack.
6+
7+
.NET Framework is a software framework that was first released in 2002. It has been widely used for developing Windows desktop applications, web applications, and services. However, it is now considered a legacy technology and is being phased out by Microsoft.
8+
9+
.NET 6 is the latest version of the .NET technology stack and was released in 2021. It is an open-source, cross-platform framework that can be used for developing applications for Windows, Linux, and macOS. .NET 6 is designed to be faster, more flexible, and more feature-rich than its predecessor, and it includes many new features and improvements.
10+
11+
## Key differences between .NET Framework and .NET 6
12+
13+
* **Platform support:** While .NET Framework is primarily designed for Windows, .NET 6 can be used to develop applications for multiple platforms, including Windows, Linux, and macOS.
14+
* **Performance:** .NET 6 is designed to be faster than .NET Framework, with improved performance in areas such as startup time and memory usage.
15+
* **Features:** .NET 6 includes many new features that are not available in .NET Framework, such as support for C# 10 and F# 6, new libraries, and improved support for cloud-native applications.
16+
* **Support lifecycle:** Microsoft has announced that it will end support for .NET Framework on October 2023, whereas .NET 6 is a long-term support (LTS) release with support until November 2026.
17+
18+
Overall, .NET 6 is considered to be the future of the .NET technology stack, and developers are encouraged to transition to it from .NET Framework.
19+
20+
## XML-style Project File vs SDK-style Project File
21+
22+
In the past, .NET projects were defined using an XML-style project file format, which contained a lot of boilerplate code and was hard to read and maintain. In recent versions of .NET, a new SDK-style project format has been introduced, which is simpler and easier to work with.
23+
24+
**Example XML-style**
25+
26+
```xml
27+
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
28+
<PropertyGroup>
29+
<OutputType>Exe</OutputType>
30+
<TargetFramework>netcoreapp3.1</TargetFramework>
31+
<RuntimeIdentifiers>win-x64;linux-x64;osx-x64</RuntimeIdentifiers>
32+
</PropertyGroup>
33+
<ItemGroup>
34+
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="3.1.4" />
35+
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="3.1.4" />
36+
</ItemGroup>
37+
<ItemGroup>
38+
<Compile Include="Program.cs" />
39+
<Compile Include="MyClass.cs" />
40+
</ItemGroup>
41+
</Project>
42+
```
43+
44+
**Example SDK-style**
45+
46+
```xml
47+
<Project Sdk="Microsoft.NET.Sdk">
48+
<PropertyGroup>
49+
<OutputType>Exe</OutputType>
50+
<TargetFramework>net6.0</TargetFramework>
51+
<RuntimeIdentifiers>win-x64;linux-x64;osx-x64</RuntimeIdentifiers>
52+
</PropertyGroup>
53+
<ItemGroup>
54+
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="6.0.0" />
55+
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="6.0.0" />
56+
</ItemGroup>
57+
<ItemGroup>
58+
<Compile Include="Program.cs" />
59+
<Compile Include="MyClass.cs" />
60+
</ItemGroup>
61+
</Project>
62+
63+
```
64+
65+
From the examples above it can be noticed that the new SDK-style project file format is simpler and more concise. The <Project\> tag includes an Sdk attribute, which specifies the SDK to use. The <PropertyGroup\> and <ItemGroup\> tags are used to group related settings and items, respectively.
66+
67+
As mentioned earlier, one of the main benefits of the SDK-style project file format is that it eliminates a lot of the boilerplate code that was required in the XML-style format. For example, in the XML-style format, it was needed to specify the tools version, the namespace for MSBuild, and the project type. In the SDK-style format, these are all handled automatically by the SDK.
68+
69+
An additional benefit of the SDK-style format is that it is easier to customize and extend. For example, it is possible to create custom tasks and targets by adding them to the project file.
70+
71+
For further information regarding the style differences and how could an Excel-DNA project be converted from the XML-style to the SDK-style see the [Updating Project to SDK-Style](../..//docs/guides-basic/updating-project-file-to-sdk-style) guide.

0 commit comments

Comments
 (0)