This page gives some best practices for writing Cake addins. Each guideline describes either a good or bad practice.
The wording of each guideline indicates how strong the recommendation is:
Do guidelines should nearly always be followed. You need a really unusual case for breaking a Do guideline.
Consider guidelines should generally be followed. You can deviate from a Consider guideline if you fully understand the meaning behind the guideline and have a good reason to do so.
Avoid guidelines indicates something you should almost never do.
§1.1 Do use
Cake.xxx as the naming schema for addins, where
xxx is a meaningful and unique name that describes what the addin does.
Why? Following a convention makes it easier for users to find and work with addins. The automated AddinDiscoverer, which is used for auditing and keeping website up to date, also uses this convention to identify Cake addins.
Cake.Emailis the name that clearly identifies the addin for Cake that allows to send emails from the build script. This name is used in the GitHub repo, it's the name of the solution file, it's the name of the project file, the name of the generated assembly and finally, it's also the name of the NuGet package.
§1.2 Do use the same name for the GitHub repo, the C# solution name, the assembly generated from the project and the NuGet package.
Why? Using the same name across different artifacts makes it easier for users and improves results of automated processes.
§2.1 Do reference the lowest version of Cake with API compatibility to the latest version (currently
Why? This gives the best support for different versions of Cake. Addins built against newer versions of Cake might not be compatible with previous versions of Cake and vice-versa, addins built against older versions might not be compatible with future versions of Cake (this is especially true when a future version of Cake introduces breaking changes).
Cake versions which are API compatible with a specific addin will be shown when the addin is added to the Cake website.
§2.2 Do reference a newer version than Cake
1.0.0 if the addin requires a specific functionality.
Why? If a specific feature of Cake is required in an addin the lowest version of Cake which introduces this feature should be referenced to have access to the feature and the best support for different versions of Cake.
§2.3 Do update addin to a newer version of Cake if a version of Cake with breaking changes becomes available.
Why? Cake will output a warning that the addin was built against an incompatible version of Cake and the addin might no longer work. It is incumbent on addin authors to upgrade their references and publish new version of their NuGet packages
§2.4 Avoid dependencies to
Cake.Common in the NuGet package.
Why? Those references are being implicitly added by the Cake engine.
Cake.Commonneed to be marked as private assets in the project file:
<ItemGroup> <PackageReference Include="Cake.Core" Version="1.0.0" PrivateAssets="All" /> <PackageReference Include="Cake.Common" Version="1.0.0" PrivateAssets="All" /> </ItemGroup>
When using a
nuspecfile omit the references to
.NET target version
§2.5 Do target at least
Why? Targeting to
netstandard2.0should work for most addins to support all available Cake runners, operating systems and platforms. Depending on the addin it might be required to target additional platforms.
§2.6 Consider to additionally target
Why? Since .NET Framework < 4.7.2 has issues with running .NET Standard assemblies, and Cake itself can run on .NET Framework 4.6.1 multi-target addins to
net461will give the maximum compatibility.
§2.7 Consider to additionally target
netstandard2.0allows you to use features provided by newer platforms when running on .NET 5.
§3.1 Do define an icon for the NuGet package.
Why? Icons helps the user to identify Cake addins.
§3.2 Consider using the Cake Contrib icon.
Why? When the addin doesn't have an own product icon, using the Cake Contrib icon gives a common branding to Cake addins.
§3.3 Avoid using the Cake icon.
Why? The Cake icon is reserved for core Cake packages.
§3.4 Do embed the icon in the package.
Why? Using an icon embedded in the package is more reliable then linking to an icon an external web site which hosts the icon.
This can be done with the following line in the addins
.csprojshould also contain a reference to the
<ItemGroup> <None Include="..\PackageIcon.png" Pack="true" PackagePath="" /> </ItemGroup>
Packattribute, this is particularly important to ensure the file is embedded in the NuGet package.
Until early 2019, the recommendation was to reference the Cake Contrib icon hosted on the rawgit CDN but rawgit announced that it would shutdown in October 2019 therefore the recommendation changed to reference the Cake Contrib icon hosted on the jsDelivr CDN. This recommendation changed once again in the fall of 2019 when NuGet started supporting embedded icons.
§3.5 Do add
cake-addin to the NuGet-Tags.
Why? NuGet can show instructions on how to install a package in Cake since NuGet/NuGetGallery#8381. Only if the correct tag is used, the correct installation instructions can be shown.
§4.1 Do follow the Cake Documentation Guidelines.
Why? Proper XML comments and usage of CakeAliasCategoryAttribute is important to be able to show documentation for the addin when the it is added to the Cake website.
§4.2 Do add documentation XML files to the NuGet package.
Why? XML documentation XML files are used to show documentation for the aliases and API provided by the addin on the Cake website.
§5.1 Do test the addin with the different runners.
Why? .NET Tool, script runners and Cake Frosting have slight differences on what dependencies are loaded by the runner and how dependencies are loaded.
Runners with which an addin is not compatible should be documented in the XML comment of the class containing the aliases.
§5.2 Do test the addin on all operating systems supported by the different Cake runners.
Why? Different platforms have differences in for example file system or available tools.
Operating systems with which an addin is not compatible should be documented in the XML comment of the class containing the aliases.
§5.3 Do test the addin on all platforms supported by the different Cake runners.
Why? Different platforms have slight differences in implementation and might break an addin. If required, targeting additional frameworks (e.g.
net5.0) might be required.
Platforms, supported by Cake, with which an addin is not compatible should be documented in the XML comment of the class containing the aliases.