De complete gids voor nopCommerce-plugin-ontwikkeling

Waarom nopCommerce-plugins belangrijk zijn

nopCommerce draait wereldwijd meer dan 60.000 online winkels. Het is het toonaangevende open-source e-commerceplatform op .NET — en de plugin-architectuur is de motor achter dat ecosysteem. Elke integratie met een betaalgateway, elke vervoerder, elke widget en elke aangepaste functie bestaat als een plugin.

Als u begrijpt hoe u nopCommerce-plugins bouwt, kunt u een van de krachtigste e-commerceplatforms op de markt uitbreiden — en er een bedrijf mee opbouwen. Deze gids behandelt alles, van uw eerste plugin-scaffold tot implementatiepatronen voor productie.

Wij bouwen al sinds 2009 nopCommerce-plugins, met 38+ plugins in onze catalogus — waaronder 12 Braziliaanse betaalgateway-integraties en de enige complete PIX-betaaloplossing op het platform. Deze gids weerspiegelt wat we hebben geleerd bij het bouwen van plugins die miljoenen transacties verwerken.

Plugin-architectuur: het fundament

De hiërarchie van plugin-interfaces

Elke nopCommerce-plugin begint met de IPlugin-interface in Nop.Services.Plugins. In plaats van dat u alles vanaf nul moet implementeren, biedt nopCommerce BasePlugin — een abstracte klasse die het standaardwerk afhandelt — en een reeks gespecialiseerde interfaces voor veelvoorkomende plugin-typen:

Kies de meest specifieke interface voor uw gebruikssituatie. IPaymentMethod biedt u de volledige betalingslevenscyclus — ProcessPaymentAsync, PostProcessPaymentAsync, RefundAsync, VoidAsync, CaptureAsync — terwijl IMiscPlugin de noodoplossing is voor alles wat niet in een standaardcategorie past.

Projectstructuur: stap voor stap

1. Maak het Class Library-project aan

Maak een nieuw Class Library-project dat gericht is op .NET 9. De aanbevolen naamgevingsconventie is Nop.Plugin.{Group}.{Name}:

Nop.Plugin.Payments.PayPalCommerce
Nop.Plugin.Shipping.FedEx
Nop.Plugin.Widgets.WhatsApp
Nop.Plugin.Misc.GoDaddy

Plaats het project in de map \Plugins in de hoofdmap van de solution (niet in \Nop.Web\Plugins, wat het implementatiedoel is). Stel het uitvoerpad van de .csproj in op $(SolutionDir)\Presentation\Nop.Web\Plugins\{PluginOutputDirectory} en schakel CopyLocalLockFileAssemblies in om ervoor te zorgen dat NuGet-afhankelijkheden naar de uitvoer worden gekopieerd.

2. Maak plugin.json aan

Elke plugin vereist een plugin.json-bestand met metadata:

{
  "Group": "Payment methods",
  "FriendlyName": "My Payment Gateway",
  "SystemName": "Payments.MyGateway",
  "Version": "1.00",
  "SupportedVersions": [ "4.90" ],
  "Author": "SplatDev",
  "DisplayOrder": 1,
  "FileName": "Nop.Plugin.Payments.MyGateway.dll",
  "Description": "Process payments via My Gateway"
}

De SystemName moet overeenkomen met de naam van uw assembly. SupportedVersions bepaalt welke nopCommerce-versies de plugin kunnen installeren. Als u nopCommerce upgradet en een plugin werkt niet meer, controleer dan eerst dit veld — veel plugins hebben alleen een update van hun ondersteunde versies nodig.

3. Implementeer de plugin-klasse

Maak een klasse die de juiste plugin-interface implementeert en overerft van BasePlugin:

public class MyPaymentProcessor : BasePlugin, IPaymentMethod
{
    public override Task InstallAsync()
    {
        // Insert settings, locale resources, or database tables
        return base.InstallAsync();
    }

    public override Task UninstallAsync()
    {
        // Clean up settings, locale resources, or database tables
        return base.UninstallAsync();
    }

    public override Task UpdateAsync(string currentVersion, string targetVersion)
    {
        // Handle version migrations
        return base.UpdateAsync(currentVersion, targetVersion);
    }

    public Task<ProcessPaymentResult> ProcessPaymentAsync(ProcessPaymentRequest request)
    {
        // Your payment logic here
    }

    public override string GetConfigurationPageUrl()
    {
        return _nopUrlHelper.RouteUrl(MyDefaults.Route.Configuration);
    }
}

De overrides InstallAsync, UninstallAsync en UpdateAsync zijn uw levenscyclus-hooks. Roep altijd de basisimplementatie aan — base.InstallAsync() handelt de registratie in het pluginsysteem af.

4. Voeg configuratie toe (admin-UI)

Maak voor plugins met instellingen een MVC-controller, een model en een Razor-view aan:

1. Controllers/{Name}Controller.cs — voorzien van [AuthorizeAdmin] en [Area(AreaNames.ADMIN)]. Overerf van BasePluginController.
2. Models/ConfigurationModel.cs — een eenvoudige klasse met de eigenschappen van uw instellingen en [NopResourceDisplayName]-attributen voor lokalisatie.
3. Views/Configure.cshtml — gebruikt de _ConfigurePlugin-layout. Neem ook _ViewImports.cshtml op (kopieer van een bestaande plugin).

Registreer de configuratieroute in een RouteProvider.cs die IRouteProvider implementeert:

public class RouteProvider : IRouteProvider
{
    public void RegisterRoutes(IEndpointRouteBuilder endpointRouteBuilder)
    {
        endpointRouteBuilder.MapControllerRoute(
            name: MyDefaults.Route.Configuration,
            pattern: "Admin/MyGateway/Configure",
            defaults: new { controller = "MyGateway", action = "Configure", area = AreaNames.ADMIN });
    }

    public int Priority => 0;
}

Een betaalplugin bouwen: het praktijkpatroon

Betaalplugins zijn het meest voorkomende — en meest complexe — plugin-type. Hier is het productiepatroon dat we bij SplatDev gebruiken:

Kerncomponenten

1. Settings-klasse: Een klasse die ISettings implementeert met eigenschappen voor API-sleutels, URL's, modi (sandbox/productie) en functieschakelaars. Bewaar geheimen in ISettingService — codeer nooit gegevens hard in.
2. Defaults-klasse: Een statische klasse met constanten — routenamen, systeemnaam, configuratie-URL's, API-eindpunten. Houdt magische strings buiten uw logica.
3. Service-klasse: Uw eigenlijke integratielogica — HTTP-aanroepen naar de betaalgateway, het parsen van antwoorden, webhook-afhandeling. Injecteer via DI en houd het testbaar (interface + implementatie).
4. Event consumers: Implementeer IConsumer<OrderPlacedEvent> en soortgelijke interfaces om te reageren op winkelevenementen — verstuur transactiebevestigingen, activeer workflows na betaling.

Betalingsflow: de methoden die u moet implementeren

Voorbeeld van een Braziliaanse betaalplugin: PIX

Het Braziliaanse PIX-systeem voor directe betalingen vereist een specifieke flow: genereer een QR-code met een payload (EMV-string), toon deze aan de klant en luister naar een webhook-bevestiging wanneer de betaling is ontvangen. Hier is het patroon:

1. ProcessPaymentAsync: Roep de PSP (PagSeguro, MercadoPago, enz.) aan om een PIX-betaling aan te maken. Sla de transactie-ID (txid) en de EMV-payload op.
2. PostProcessPaymentAsync: Geef de QR-code weer (gegenereerd uit de EMV-payload) en de "kopieer-plak"-code. Stel de betalingsstatus in op Pending.
3. Webhook-handler: De PSP verstuurt een webhook wanneer PIX de betaling bevestigt. Werk de orderstatus bij en activeer OrderPaidEvent.

Dit is het patroon achter alle 12 Braziliaanse betaalplugins van SplatDev — die PIX, boleto en creditcardbetalingen in termijnen verwerken via PagSeguro, MercadoPago, Cielo, Banco Inter, Pagar.me, Rede, GetNet, PicPay, NuPay, Braspag en InfinityPay.

Widgets: UI toevoegen zonder thema's aan te raken

Widget-plugins implementeren IWidgetPlugin en moeten aangeven in welke widgetzones ze worden weergegeven:

public Task<IList<string>> GetWidgetZonesAsync()
{
    return Task.FromResult<IList<string>>(new List<string>
    {
        PublicWidgetZones.HomepageBeforeBestSellers,
        PublicWidgetZones.ProductDetailsAfterPictures
    });
}

Implementeer vervolgens GetPublicViewComponentAsync om de HTML van de widget terug te geven. Het widgetsysteem roept deze methode aan voor elke zone die u hebt geregistreerd.

Veelvoorkomende widgetpatronen: pop-ups voor nieuwsbriefaanmelding, livechatknoppen, keurmerken, cookie-toestemmingsbanners, zwevende WhatsApp-knoppen, recent bekeken producten en meldingen voor sociaal bewijs.

Databasetoegang: IRepository<T> en migraties

nopCommerce gebruikt een repository-patroon via IRepository<T> voor gegevenstoegang. Voor plugins die aangepaste tabellen nodig hebben:

1. Definieer uw entiteitsklasse (moet een Id-eigenschap hebben).
2. Maak een ObjectContext aan die uw entiteit registreert bij Entity Framework Core.
3. Gebruik in InstallAsync de aanroep _dbContext.InstallAsync() om de tabellen aan te maken.
4. Gebruik in UninstallAsync de aanroep _dbContext.UninstallAsync() om ze te verwijderen.

Overweeg voor schemamigraties tussen plugin-versies een MigrationManager toe te voegen aan uw UpdateAsync-override die de huidige schemaversie controleert en de benodigde ALTER TABLE-statements toepast. Dit is eenvoudiger dan FluentMigrator voor plugins en houdt uw migratielogica op één plek.

Testen: behandel uw plugin als een product

Bij SplatDev behandelen we elke plugin als een product met zijn eigen testsuite:

• Unittests (xUnit): Test uw servicelaag in isolatie. Mock ISettingService, IRepository<T> en eventuele HTTP-clients. Uw betalingslogica, belastingberekeningen en berekeningen van verzendtarieven zouden 100% unittestdekking op de bedrijfslogica moeten hebben.
• Integratietests: Start een test-nopCommerce-instantie op en verifieer dat uw plugin installeert, configureert en de volledige levenscyclus doorloopt. Gebruik sandbox-/testgegevens voor betaalgateways.
• Lokalisatietests: Verifieer dat alle locale-resources bestaan voor elke taal die u beweert te ondersteunen. Ontbrekende resource-strings zijn de meest voorkomende plugin-bug.
• StyleCop-compliance: nopCommerce verwacht StyleCop-compliance. Voer het uit in uw CI-pijplijn — het vangt subtiele problemen op vóór de code review.

Veelvoorkomende valkuilen (en hoe u ze vermijdt)

1. base.InstallAsync() niet aanroepen

Als u InstallAsync overschrijft zonder de basis aan te roepen, wordt uw plugin niet geregistreerd bij het pluginsysteem en verschijnt deze niet in de admin. Neem altijd await base.InstallAsync() op aan het einde van uw override.

2. Inloggegevens hardcoderen

Bewaar API-sleutels, tokens en geheimen in ISettingService — codeer ze nooit hard in plugin.json of als klasseconstanten. De instellingenpagina moet beheerders in staat stellen deze waarden te configureren, en ze moeten waar nodig versleuteld worden opgeslagen.

3. Versiecompatibiliteit negeren

nopCommerce-versies breken plugins. Het veld SupportedVersions in plugin.json is niet decoratief — nopCommerce controleert het voordat uw plugin wordt geladen. Test bij het upgraden van nopCommerce uw plugin tegen de nieuwe versie en werk dit veld bij. Verhoog het nummer niet zomaar zonder te testen.

4. De request-thread blokkeren

Alle plugin-methoden zijn asynchroon om een reden. Als uw betalingsverwerker een externe API aanroept, moet die aanroep asynchroon zijn. Het blokkeren van de thread met .Result of .Wait() verslechtert de prestaties onder belasting en kan deadlocks veroorzaken.

5. Geen event consumers

Plugins die alleen een configuratiepagina bieden, missen de essentie. De echte kracht van nopCommerce-plugins komt van event consumers — reageren op winkelevenementen zoals OrderPlacedEvent, CustomerRegisteredEvent of ShipmentDeliveredEvent. Koppel uw plugin aan de bedrijfsevenementen van de winkel, niet alleen aan de admin-UI.

nopCommerce 4.90: wat is er nieuw voor plugin-ontwikkelaars

nopCommerce 4.90 richt zich op .NET 9 en brengt verschillende verbeteringen voor plugin-ontwikkelaars:

• .NET 9-runtime: Uw plugins draaien op de snelste .NET tot nu toe — en profiteren automatisch van JIT-verbeteringen, dynamische aanpassing van de GC en lus-optimalisaties.
• C# 13-ondersteuning: Gebruik params-collecties, ref struct-interfaces en partiële eigenschappen in uw plugin-code.
• Bijgewerkte NuGet-afhankelijkheden: Onderliggende pakketten (Autofac, FluentValidation, enz.) zijn bijgewerkt. Test de afhankelijkheidsboom van uw plugin.
• IMultiFactorAuthenticationMethod: MFA-plugins zijn nu een first-class concept met hun eigen interface.
• Verbeterde plugin-template: De officiële nopCommerce-plugin-template voor Visual Studio is bijgewerkt voor 4.90 — gebruik deze als uitgangspunt.

Hoe nu verder

nopCommerce-plugin-ontwikkeling is een vaardigheid waarmee u een carrière opbouwt. De nopCommerce-marktplaats is actief en groeit, en goed gebouwde plugins genereren terugkerende inkomsten via updates en ondersteuning. Bij SplatDev vormen plugins onze kernactiviteit — onze Store op store.splatdev.com biedt 38+ plugins, en we zijn al jarenlang Gold Solutions Partner.

Als u een e-commerceproject op nopCommerce bouwt, hoeft u niet alles vanaf nul te bouwen. Onze catalogus omvat Braziliaanse betalingen, verzending (Correios, JadLog, Braspress), ERP-integraties en aangepaste functionaliteit. Als u iets nodig hebt wat we niet hebben, bouwen we ook aangepaste plugins.

Klaar om uw nopCommerce-winkel te bouwen of uit te breiden? Ons team doet dit al sinds 2009 — langer dan bijna iedereen in het ecosysteem.

Werk samen met ons nopCommerce-team

Of blader door onze plugin-catalogus: store.splatdev.com