Converting Single Extension For BE 3.0

This is walk-through on how to convert older BlogEngine.NET extensions built for website project to compiled extension that can be installed in version 3.0 and up.

Simple Case

Simplest possible extension is a single class added to App_Code folder so ASP.NET will dynamically compile it under website project. Difference with web application, which 3.0 became, is that all classes must be compiled before deployment. So we need to build this class into class library and deploy it as DLL. Example would be SimpleDownloadCounter extension from gallery. In NuGet Package Explorer it looks like this.

Start by downloading latest stable BlogEngine.NET source code. When project built and tested in Visual Studio, add new class library for extension.

1. Right-click solution -> add new project -> class library -> SimpleDownloadCounter

2. In this new project, add references to BlogEngine.Core and System.Web.

3. Copy extension file from NuGet package (SimpleDownloadCounter.cs) to new project (you can rename it to .zip and open as regular zip file).

4. Build in release mode, this will produce DLL under project "bin/release".

5. Using Package Explorer, create new NuGet package, fill in meta data, under "content" menu add "lib" folder and include resulting DLL.

When new package uploaded to online gallery, it can be installed from admin UI as normal and will work in BlogEngine.NET 3.0 just as before. 

Here file "Picasa.zip" was uploaded to the server with package installed and, after first download, counter was displayed as expected.

It is recommended to set first two digits in package version to the same as BE version it was built for and use latest numbers as package version. For example package build for "2.9.X.X", the "X.X" digits can be used as package version. This is just for users easier identify if package is outdated and compatible with there install.

Dealing with supporting files

Some extensions have supporting files, like images, scripts, styles etc. They all need to be added to the package too. For example MoveToTop extension has an image it displays on the page. It puts it in the "pics" folder, which is not desirable because this is an application folder.

To convert this extension to run under 3.0 we would go through the same steps as in section above. To handle image, we can add it to "Custom/Extensions/MoveToTop" folder. And change reference in the class from "pics/MovetoTop.png" to "Custom/Extensions/MoveToTop/MovetoTop.png".

No need to add picture to Visual Studio project, we just need package it to NuGet and deploy along with DLL. Similar situation with scripts, styles and other files extension can rely on. We add them all to "Custom/Extensions/ExtensionName" folder and change references to use new location. This way, when blog upgraded to new version extension keeps working with not changes.

One exception is when extension has other DLLs it needs to deploy. Those go to "lib" folder, just as extension DLL itself. Everything in "lib" will be deployed by NuGet to application "/bin" folder, everything in "content" will go to application root.

Custom extension admin pages

Some extensions have custom admin UI, they usually included in "User controls/ExtensionName". Because web page depends on code behind, there is no easy way to migrate this to BE 3.0 model. Recommendations are:

1. Remove custom page from extension so it will be using standard BE settings page.

2. Convert custom admin page to single page with no code behind.

Note that it is possible to move code from code-behind class to server-side script in admin page, but this is messy and often not reliable solution, requiring many modifications anyway.


Comments are closed