Jeremy Davis
Jeremy Davis
Sitecore, C# and web development
Article printed from: https://blog.jermdavis.dev/posts/2022/statiq-extensions-folder-names

A bug caused by a feature from the future?

Turns out, unwritten code can still trip you up...

Published 01 August 2022
Statiq Bug ~2 min. read

One of the challenges you often deal with using software that's under active development, is that as you take the lastest updates you can find that they subtly change (or break) the behaviour of the tool - affecting stuff that used to work for you. I had a classic example of this recently with this blog. An update to the Statiq engine fixed something in the core library code and created a subtle issue for my website. Since the docs for Statiq don't make this obvious, here's some information for anyone else finding this problem:

The issue

Every so often the nuget packages for Statiq get updated, when the project adds new features or fixes bugs. I try to keep on top of these, and ensure that my project for building this site is up to date. When v1.0.0-beta-49 of the Statiq.Web project appeared recently I updated my project to use this, and tried running the generator to test for issues. Initially it looked fine: no visible errors, and browsing the resulting site didn't look wrong, so I committed this change and went back to work.

However when I came to publish my next post I reallised something was wrong. Creating an entirely new post (where the files didn't already exist) allowed me to notice that some key things had stopped working: New social media preview images weren't being generated, the HTML wasn't being "pretiffied" and the syntax highlighter for code blocks wasn't working correctly. It took me a few minutes to realise what linked these three things: They're all done by pipeline extensions that I added to the base Statiq code as part of my blog project.

So what was up?

A diagnosis

I went back to my solution to check that the new nuget package had been correctly applied, and to look for build errors or warnings, and I noticed this:

Build properties for a class showing 'None' rather than 'C# Compiler' action

When I looked at any of the C# files for my extensions to the Statiq pipelines, their Build Action was set to "None", rather than "C# compiler". That would entirely explain why my extensions weren't running - if they're not compiled they can't be executed.

But why were they no longer being compiled? My first reaction was that I'd messed something up, and I needed to set them back to "C# compiler" to fix it. But trying to choose that option from the dropdowns didn't work:

When selecting 'C# compiler' as the build action, it is denied with an error dialog.

It throws up an error dialog which says:

An error has occurred while saving the edited properties listed below:
	Build Action
One or more values are invalid. Cannot add 'extensions\Enlighter\CustomMarkdownCodeBlockFormatterConfigurator.cs' to
the project, because the path is explicitly excluded from the project 
(C:\Users\Jeremy\.nuget\packages\statiq.web\1.0.0-beta.49\buildTransitive\netcoreapp3.1\Statiq.Web.targets (4,5)).

					

And that error gives some good insight as to what's up: One of the files brought in by the Statiq.Web package includes a .targets file which is excluding my code. So what's in that file then? Well:

<Project>
  <ItemGroup>
    <Compile Remove="theme\**" />
    <Compile Remove="extensions\**" />
    <Compile Remove="archetypes\**" />
  </ItemGroup>
  <ItemGroup>
    <None Include="theme\**">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </None>
    <None Include="extensions\**">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </None>
    <None Include="archetypes\**">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </None>
  </ItemGroup>
  <ItemGroup Condition="'$(Language)' == 'C#' AND ('$(ImplicitUsings)' == 'true' or '$(ImplicitUsings)' == 'enable')">
    <Using Include="Statiq.Web" />
  </ItemGroup>
</Project>

					

It's not mentioning my files specificallly, but it excludes some folders and one of them is extensions - which is the folder/namesapce I'd used for my additional pipelines. So that explains why the weren't getting compiled...

The fix

Having discussed this with Statiq's maintainers, this change was caused by a bug fix to enable a future feature of the project. There's a proposed feature where the extensions folder would be used for dynamically compiled plug-ins that were added by themes. The fact that I'd been able to put code in this folder and have it work before was a bug, which has been fixed by this recent release. This isn't made clear in the documentation yet, hence it catching me out. (And hence this post)

So the fix was to rename my folder/namespace for my extra pipelines from extensions to customisations - and with that done it all goes back to working as expected.

It's not often that a feature that's not yet been implemented trips you up, but it can happen...

↑ Back to top