Document F# support with <PackageReference ...>

[govert]

In recent Visual Studio versions (some time in 2020) the F# "Library (.NET Framework)" template was changed to use SDK-style projects and only support <PackageReference .../> NuGet references, thus breaking the Excel-DNA NuGet package.

Some steps to manually configure such a project:

• Install the ExcelDna.AddIn package
• In the .fsproj file, add the following Properties:

  <PropertyGroup>
    <ExcelDnaAllowPackageReferenceProjectStyle>true</ExcelDnaAllowPackageReferenceProjectStyle>
    <RunExcelDnaSetDebuggerOptions>false</RunExcelDnaSetDebuggerOptions>
  </PropertyGroup>

• Add a new file to the project, called <MyProject>-AddIn.dna with the following content:

<?xml version="1.0" encoding="utf-8"?>
<DnaLibrary Name="MyProject Add-In" RuntimeVersion="v4.0" xmlns="http://schemas.excel-dna.net/addin/2018/05/dnalibrary">
  <ExternalLibrary Path="MyProject.dll" ExplicitExports="false" LoadFromBytes="true" Pack="true" IncludePdb="false" />
</DnaLibrary>

• The name of the .dna file will be used as the root name for the add-in. The NuGet package would normally set this as '<ProjectName>-AddIn.dna`, but it could be 'Anything.dna' too.

• You might want to customize the <DnaLibrary Name="..." .../> and check that the <ExternalLibrary Path=..." /> refers to the correct output .dll file name.

• Add some code to the .fs file:

module MyFunctions

open ExcelDna.Integration

[<ExcelFunction(Description="My first .NET function")>]
let HelloDna name =
    "Hello " + name

• Configure debugging in the project properties:

  • Set the 'Launch' option to 'Executable'
  • Set the Executable as the path to Excel, e.g. for 32-bit Excel I used: C:\Program Files (x86)\Microsoft Office\root\Office16\EXCEL.EXE
  • Set the Application Arguments to be the '<MyProject>-AddIn.xll' file in the output directory (or <MyProject>-AddIn64.xll is your Excel version is 64-bit).

• Press F5 to compile, start Excel, load the add-in.

• Check that the =HelloDna(...) function works.

[matthewcrews]

I am getting a FS00039: The namespace or module 'ExcelDna' is not defined.

Repo here: https://github.com/matthewcrews/ExcelTestAddIn

[govert]

OK - I thought this was unimportant, but you need to fix the PackageReference in the .fsproj file to remove the <IncludeAssets .../> tag.

  <ItemGroup>
    <PackageReference Include="ExcelDna.AddIn" Version="1.1.1">
      <PrivateAssets>all</PrivateAssets>
      <!--<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>-->
    </PackageReference>
  </ItemGroup>

I don't know why the F# reference would add it.

Without it, the project should compile and everything work. But the is then a Warning icon in the solution Explorer next to the package. I don't know how to see where the warning comes from.

[matthewcrews]

Can confirm this works. Here's what I ended up with: https://github.com/matthewcrews/ExcelTestAddIn/blob/master/TestAddIn/TestAddIn.fsproj

  <ItemGroup>
    <PackageReference Include="ExcelDna.AddIn" Version="1.1.1" PrivateAssets="All" />
  </ItemGroup>

[govert]

The <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages> property is particularly useful for F# projects, to prevent the extra bunch of localized resource directories.

  <PropertyGroup>
    <TargetFramework>net472</TargetFramework>
    <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

[tforkmann]

Hi there!

Is net5. supported as well?

[govert]

@tforkmann Not yet, but I'm working on it. Things might work a bit different for .NET 5 though, and might also not be free. Let me know if you want to be an early tested in the next few months.

[tforkmann]

@govert Sure :) I already have a test project. So let me know when I should give it a try :)

[govert]

It looks like the .dna file needs to appear in the project file as

<ItemGroup> <None Include="<MyProject>-AddIn.dna" /> </ItemGroup>

This lets the file be copied to the output, and then the Excel-DNA build tasks detect and process from there.