Skip to content

🍰 🧩 📦 Cake addin that makes ExcelDnaPack available as a tool in Cake build scripts

License

Notifications You must be signed in to change notification settings

cake-contrib/Cake.ExcelDnaPack

Repository files navigation

README.md

Cake.ExcelDnaPack

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.

NuGet Version Stack Overflow Cake Build Stack Overflow Excel-DNA

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.

Join in the discussion on the Cake repository

Release History

Click on the Releases tab on GitHub.


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