How to Port a nopCommerce Plugin from 4.90 to 5.0

You open your 4.90 plugin in Visual Studio 2026, point it at the nopCommerce 5.00 source and build. The error list fills up: AutoMapper is gone, the repository has no Insert any more, and the project targets a framework the solution no longer uses.

Nothing is wrong with your code. The platform moved underneath it, and that is a different kind of problem, because it has an order you can follow.

This guide ports a plugin in the order the build breaks, so each step clears the next error. Every snippet comes from the nopCommerce 4.90.8 and 5.00.0 source, compared on the plugins that ship with the platform. We took our own plugins through this same sequence when 5.00 came out.

It assumes you build plugins in Visual Studio against the nopCommerce source and know the layout: Controllers, Models, Services, Views and plugin.json. If you need that groundwork first, our guide to creating a nopCommerce plugin covers it.

Retarget the Project: .NET 10 and plugin.json

Start with the two edits that need no thought. The 4.90.8 Facebook Pixel plugin targets net9.0, and the 5.00.0 plugins, PayPal Commerce among them, target net10.0. The release notes name the toolchain: Visual Studio 2026 (v18.0), the .NET 10 SDK 10.0.401 and ASP.NET Core Runtime 10.0.12.

<!-- Nop.Plugin.Your.Plugin.csproj -->
<TargetFramework>net10.0</TargetFramework>

Then declare the new version in plugin.json. Your plugin's own Version is yours to set: the 5.00.0 PayPal Commerce plugin ships as 5.00.6.

{
  "SystemName": "Your.Plugin",
  "Version": "5.00.1",
  "SupportedVersions": [ "5.00" ]
}

Rebuild straight away, before you touch anything else. The error count is your honest estimate of the port: every error that mentions AutoMapper belongs to the next section, and every missing Insert or GetById to the one after.

Swap AutoMapper Profiles for Mapster

In 4.90 a plugin's mapping profile derived from AutoMapper's Profile and implemented IOrderedMapperProfile to declare an Order. In 5.00 nopCommerce maps with Mapster, and the base class changes with it. This is the 4.90.8 Facebook Pixel profile, trimmed to one map.

using AutoMapper;
using Nop.Core.Infrastructure.Mapper;

public class MapperConfiguration : Profile, IOrderedMapperProfile
{
    public MapperConfiguration()
    {
        CreateMap<FacebookPixelConfiguration, FacebookPixelModel>()
            .ForMember(model => model.StoreName, options => options.Ignore());
    }

    public int Order => 1;
}

The same file in 5.00.0 loses the using, the interface and the Order property. Nothing else moves.

using Nop.Core.Infrastructure.Mapper;

public class MapperConfiguration : BaseMapperProfile
{
    public MapperConfiguration()
    {
        CreateMap<FacebookPixelConfiguration, FacebookPixelModel>()
            .ForMember(model => model.StoreName, options => options.Ignore());
    }
}

Code that called the old AutoMapper instance directly now calls MapperConfiguration.Mapper, a MapsterMapper mapper that the profiles feed at startup. The base class sets Order to 0, and an Init() method is available to override; the Facebook Pixel plugin simply keeps its rules in the constructor.

Admin controllers usually move between entities and view models with ToModel and ToEntity. In the platform's own admin area those live in MappingExtensions and call MapperConfiguration.Mapper, so a plugin that wraps the mapper the same way should call that one shared instance.

From the BSS team

When we port a plugin, the profile swap is the quickest part, so we do not trust it until a model has made a round trip. We open each configuration page, save it once and reload it. If you would rather hand over the whole port, our nopCommerce services include plugin upgrades.

Move Repository Calls to Async

The 4.90 IRepository<TEntity> offered both flavours: GetById, GetAll, Insert, Update and Delete next to their async twins. The 5.00 interface lists only the async versions. A plugin that called a synchronous one stops compiling, and the fix is a one-line change at each call site.

Making a caller async spreads upward: the controller action, the service method and the interface above it all take Task. That is normal, and it is why we start from the lowest call and work out.

Work one service at a time and rebuild after each. A half-converted service gives errors that point at the wrong file, while a finished one leaves the next error list shorter and easier to read.

Resist adding .Result or .GetAwaiter().GetResult() to silence the compiler. The 4.90 view location expander did exactly that with GetWorkingThemeNameAsync().Result inside PopulateValues, and the 5.00 version no longer does.

When a call site truly cannot be async

5.00 adds ISyncCodeHelper in Nop.Services.Helpers for synchronous code. It exposes InsertEntity, UpdateEntity, DeleteEntity, GetAllEntities, GetAllLanguages and GetCurrentStore. Treat it as a bridge for code you cannot change yet, never as the new default.

Catch the Breakages the Compiler Misses

A green build proves the types line up. It does not prove the plugin still behaves, and 5.00 moved three things that a clean compile can hide.

If your plugin used the news, poll or forum services, reference the matching plugin and check that the store has it installed. Otherwise the code compiles against a feature that is not there at run time.

The first one bites any plugin that copied or subclassed the expander, or that used its protected constants: the names are now NopThemeDefaults.ThemeKey and NopThemeDefaults.HttpContextThemeCacheKey. The second fails to compile where you read PictureId, which is the lucky case. A plugin that writes those tables with raw SQL gets no help from the compiler at all.

Search before you read. These three commands, run from the plugin folder, size the quiet part of the port in a minute:

grep -rn "AutoMapper" --include="*.cs" .
grep -rn "PictureId" --include="*.cs" --include="*.cshtml" .
grep -rn "ThemeableViewLocationExpander" --include="*.cs" .

From the BSS team

In the themes and plugins we ship, views are where a major version surprises us, so we render every public view under a theme and under the default theme before we call a port finished. Our compatibility testing guide has the full routine.

Build, Install and Test Like a Customer

Build against the 5.00 source, copy the output to a 5.00 test store and install it from Local plugins. Then go through the journeys the plugin owns, not only the ones that compile.

Keep the test store close to production: the same theme, the same payment sandbox settings and the other plugins your store runs. A plugin that works alone and fails beside another one is a normal port finding, not a surprise.

For a plugin you depend on but do not own, the choice is whether to port, ask the vendor or buy a build that is already updated. This is how the three compare.

BSS plugin

BSS Stripe Payment

A payment gateway is the plugin where a failed port costs real orders. Ours is updated for nopCommerce 5.0, so it is one plugin off your port list.

View the plugin

If the port is bigger than you expected, you can hire a .NET developer from BSS to take it while your own engineers stay on the roadmap.

Frequently Asked Questions

Final Thoughts

The red error list from the start is a to-do list in disguise. Retarget the project, swap the profile base class and await the repository calls.

Then check the three quiet changes, which no error list will show you, and test the plugin on a 5.00 store with the same theme and plugins as production. Once it installs, saves its settings and renders under a theme, it is ready for the version everything else is moving to.

For the store-level steps around it, read our 4.90 to 5.0 upgrade guide, and for what else the release changes, what is new in nopCommerce 5.0. If you are new to the plugin structure itself, start with how nopCommerce is layered.