cake-contrib / Cake.ExcelDnaPack

:cake: :jigsaw: :package: Cake addin that makes ExcelDnaPack available as a tool in Cake build scripts

README.md

Cake.ExcelDnaPack

Addin for the Cake build automation system that enables you to use ExcelDnaPack for packing Excel-DNA addins into a single .xll file. Cake.ExcelDnaPack targets .NET 6.0 and .NET 7.0, and runs on Windows.

Give a Star! ⭐

If you like or are using this project please give it a star. Thanks!

Getting started 🚀

This addin exposes the functionality of ExcelDnaPack to the Cake DSL by being a very thin wrapper around its command line interface; this means that you can use Cake.ExcelDnaPack in the same way as you would normally use ExcelDnaPack, but with a Cake-friendly interface.

First of all, you need make the ExcelDnaPack tool available to your Cake build process by using the tool directive:

#tool "nuget:?package=ExcelDnaPack&version=1.5.1"

Make sure the &version= attribute references the latest version of ExcelDnaPack available on nuget.org.

Then, you need to load Cake.ExcelDnaPack in your build script by using the addin directive:

#addin "nuget:?package=Cake.ExcelDnaPack&version=3.0.0"

Make sure the &version= attribute references the latest version of Cake.ExcelDnaPack compatible with the Cake runner that you are using. Check the compatibility table to see which version of Cake.ExcelDnaPack to choose_.

Finally, call ExcelDnaPack() in order to pack all the files that compose your Excel-DNA addin into a single file:

#tool "nuget:?package=ExcelDnaPack&version=1.5.1"
#addin "nuget:?package=Cake.ExcelDnaPack&version=3.0.0"

Task("Example")
    .Does(context =>
{
    ExcelDnaPack("MyAddin.dna");
});

RunTarget("Example");

ExcelDnaPack settings you can customize

Property	Type	Description
DnaFilePath	FilePath	The path to the primary .dna file for the Excel-DNA add-in. e.g. MyAddin.dna
PromptBeforeOverwrite	bool?	Enable interactive prompt to overwrite the output .xll file, if it already exists
NoCompression	bool?	Disable compression (LZMA) of resources
NoMultiThreading	bool?	Disable multi-threading to ensure deterministic order of packing
OutputXllFilePath	FilePath	The output path for the packed .xll file

By default, the ExcelDnaPack tool prompts the user before overwriting an existing .xll output file unless the /Y argument is specified. Because Cake.ExcelDnaPack is designed to be used in build scenarios (usually non-interactive) it sets /Y by default, to overwrite the output .xll file if it already exists, in order to suppress the interactive prompt. To change this behavior set PromptBeforeOverwrite to true.

For more details on how ExcelDnaPack works, check its documentation.

Using Cake.ExcelDnaPack with custom settings

You can define your settings using an instance of ExcelDnaPackSettings, for example:

var settings = new ExcelDnaPackSettings
{
    DnaFilePath = @"C:\MyProject\MyAddin.dna",
    PromptBeforeOverwrite = true,
    NoCompression = true,
    NoMultiThreading = true,
    OutputXllFilePath = @"C:\MyProject\MyAddin-SingleFile.xll",
};

ExcelDnaPack(settings);

Alternatively, you can define your settings using Cake's configurator pattern:

ExcelDnaPack(@"C:\MyProject\MyAddin.dna", settings => settings
    .PromptBeforeOverwrite()
    .NoCompression()
    .NoMultiThreading()
    .SetOutputXllFilePath(@"C:\MyProject\MyAddin-SingleFile.xll")
);

Compatibility

Cake.ExcelDnaPack is compatible with all Cake runners, and below you can find which version of Cake.ExcelDnaPack you should use based on the version of the Cake runner you're using.

Cake runner	Cake.ExcelDnaPack	Cake addin directive
3.0.0 or higher	3.0.0 or higher	#addin "nuget:?package=Cake.ExcelDnaPack&version=3.0.0"
2.0.0 - 2.3.0	2.0.0	#addin "nuget:?package=Cake.ExcelDnaPack&version=2.0.0"
1.0.0 - 1.3.0	1.0.0 - 1.0.1	#addin "nuget:?package=Cake.ExcelDnaPack&version=1.0.1"
0.33.0 - 0.38.5	0.1.0	#addin "nuget:?package=Cake.ExcelDnaPack&version=0.1.0"
< 0.33.0	N/A	(not supported)

Discussion

For questions and to discuss ideas & feature requests, use the GitHub discussions on the Cake GitHub repository, under the Extension Q&A category.

Release History

Click on the Releases tab on GitHub.

---

Copyright © 2021-2023 C. Augusto Proiete & Contributors - Provided under the MIT License.