How to get a custom DocumentProcessor or PostProcessor to work

[michfuchs]

One appraoch to solve #9238 seems to be implementing a custom PostProcessor, as described in the Documentation.

However, I don't seem to be able to load my post processor.

My docfx.json configuration for the post processors looks like this:

"postProcessors": [ "ExtractSearchIndex", "MyPostProcessor" ]

Since ExtractSearchIndex works, I'm confident it's in the right spot.

Step 4 in the documentation specifies where the built dll of the assembly containing the preprocessor should be copied to:

I tried several folder options, none seem to work:

I am consistently getting the following error:

1>Searching custom plugins in directory ****\802_Documentation\templates\my-template\plugins...
1>6 plug-in(s) loaded.
1>Post processor ExtractSearchIndex loaded.
1>EXEC : warning : Can't import: MyPostProcessor, System.Composition.Hosting.CompositionFailedException: No export was found for the contract 'IPostProcessor "MyPostProcessor"'.
1>   at System.Composition.CompositionContext.GetExport(CompositionContract contract)
1>   at System.Composition.CompositionContext.GetExport(Type exportType, String contractName)
1>   at Docfx.Common.CompositionContainer.GetExport(CompositionHost container, Type type, String name) in /_/src/Docfx.Build.Engine/CompositionContainer.cs:line 41
1>EXEC : warning : Can't find the post processor: MyPostProcessor

It was always 6 plug-ins, even before I added the processor, so the plug-in is definitely not picked up.

[filzrev]

One approach to solve #9238 seems to be implementing a custom PostProcessor, as described in the Documentation.

It seems Document is a little outdated and needs updating.

Current docfx implementation load plugin DLLs from following locations. (it's described at this page)

Global: the Docfx executable directory.
Non-global: a folder you create with the name plugins under a template folder.

And the message 6 plug-in(s) loaded. is a little misleading.
It simply prints the number of DocumentProcessor, not the number of plugins.

docfx/src/Docfx.Build.Engine/DocumentBuilder.cs

Lines 40 to 44 in f205a44

	Logger.LogInfo($"{Processors.Count()} plug-in(s) loaded.");
	foreach (var processor in Processors)
	{
	Logger.LogVerbose($"\t{processor.Name} with build steps ({string.Join(", ", from bs in processor.BuildSteps orderby bs.BuildOrder select bs.Name)})");
	}

[michfuchs]

I also tried to put it right next to the executable, same error. The build log would suggest another folder way down from docfx.exe, but that one also doesn't work.

Strange thing is, if I serve the site up, docfx is actually locking the file so that I can't delete it. So it does seem like the file is being checked, but the error message still stands as it is, and no code seems to be executed in the processor.

[filzrev]

I've detected another obsoleted documentation issue.
https://dotnet.github.io/docfx/tutorial/howto_add_a_customized_post_processor.html#step0-preparation

If your plugin project referencing Microsoft.Composition NuGet package.
It should be removed. And use System.Composition namespace instead.

As far as confirmed by your screenshot information.
Plugin DLL seems be successfully loaded. But exported interface failed to be imported by CompositionContainer.

The situation makes sense. If your plugin using Microsoft.Composition version.

[michfuchs]

Thanks for your answer. Unfortunately that's not it, I already have System.Composition package referenced.

[filzrev]

What's version .NET global tools installed (e.g. 2.70.3)

It seems that problems are occurred when custom plugin referencing newer version of Docfx.Plugins (2.70.4) .
Try to update docfx version or downgrade Docfx.Plugins NuGet package.

[michfuchs]

Updated the tool to 2.70.4 and it works. Thank you!
Maybe you could check this in the build and issue a warning, if versions need to be equal to the last digit.

[filzrev]

Currently plugin DLL loading failure is reported as Verbose level message. so it's not shown by default.

Scanning assembly file C:\Projects\docfx\samples\seed\template\plugins\Sample.Docfx.Plugins.dll...
Skipping file C:\Projects\docfx\samples\seed\template\plugins\Sample.Docfx.Plugins.dll due to load failure: Unable to load one or more of the requested types.
Could not load file or assembly 'Docfx.Plugins, Version=2.70.4.0, Culture=neutral, PublicKeyToken=null'.

It might be better to change log level to Warning.

[billybooth]

We were experiencing the same with a post-processor we've been using for some time now after updating docfx:

C:\Projects\xxx\EssSharp>docfx --version
2.73.2+8a60af927dcb1a034de840021cc7268c309f9d17

After updating all packages, we ended up here:

C:\Projects\xxx\EssSharp.PostProcessor>dotnet list EssSharp.PostProcessor.sln package
Project 'EssSharp.PostProcessor' has the following package references
   [net7.0]:
   Top-level Package                   Requested   Resolved
   > Docfx.Plugins                     2.73.2      2.73.2
   > Newtonsoft.Json                   13.0.3      13.0.3
   > System.Collections.Immutable      8.0.0       8.0.0
   > System.Composition                8.0.0       8.0.0

Even when the Docfx.Plugins version matched the docfx version (2.73.2), we received an identical error to the above (which was not very helpful) until we downgraded System.Composition to version 7.0.0:

Searching custom plugins in directory C:\Projects\xxx\EssSharp\docfx\templates\EssSharp\plugins...
warning: Can't import: EssSharpPostProcessor, System.Composition.Hosting.CompositionFailedException: No export was found for the contract 'IPostProcessor "EssSharpPostProcessor"'.
   at System.Composition.CompositionContext.GetExport(CompositionContract contract)
   at System.Composition.CompositionContext.GetExport(Type exportType, String contractName)
   at Docfx.Common.CompositionContainer.GetExport(CompositionHost container, Type type, String name) in /_/src/Docfx.Build/CompositionContainer.cs:line 41
warning: Can't find the post processor: EssSharpPostProcessor

Just leaving this here in case it's helpful for anyone else.

Edit: In case it wasn't clear, downgrading System.Collections.Immutable and System.Composition to version 7.0.0 corrected the issue. It feels (unfortunately) like we are now in a position where we need to pin docfx to version 2.73.2 and, in the future, coordinate all docfx updates with updates to our plugin.