Jak napsat plugin pro nopCommerce
Pluginy slouží k rozšíření funkčnosti nopCommerce. nopCommerce má několik typů pluginů. Například platební metody (jako PayPal), poskytovatelé daní, metody výpočtu dopravy (jako UPS, USP, FedEx), widgety (jako blok „live chat“) a mnoho dalších. nopCommerce je již distribuován s mnoha různými pluginy. Na oficiálním webu nopCommerce můžete také vyhledávat různé pluginy a zjistit, zda už někdo nevytvořil plugin, který vyhovuje vašim potřebám. Pokud ne, tento článek vás provede procesem vytvoření vlastního pluginu.
Struktura pluginu, potřebné soubory a jejich umístění
Jako první musíte vytvořit v řešení (solution) nový projekt typu
Class Library. Osvědčeným postupem je umístit všechny pluginy do adresáře\Pluginsv kořeni řešení (nezaměňujte s podadresářem\Pluginsv adresáři\Nop.Web, který se používá pro již nasazené pluginy). Osvědčeným postupem je umístit všechny pluginy do složky řešeníPlugins.Doporučený název projektu pluginu je
Nop.Plugin.{Group}.{Name}.{Group}je skupina vašeho pluginu (například Payment nebo Shipping).{Name}je název vašeho pluginu (například PayPalCommerce). Například platební plugin PayPal Commerce má následující název:Nop.Plugin.Payments.PayPalCommerce. Upozorňujeme však, že to není povinné. Pro plugin můžete zvolit libovolný název. NapříkladMyGreatPlugin.
Po vytvoření projektu pluginu musíte otevřít jeho soubor
.csprojv libovolném textovém editoru a nahradit jeho obsah následujícím:<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>net9.0</TargetFramework> <Copyright>SOME_COPYRIGHT</Copyright> <Company>YOUR_COMPANY</Company> <Authors>SOME_AUTHORS</Authors> <PackageLicenseUrl>PACKAGE_LICENSE_URL</PackageLicenseUrl> <PackageProjectUrl>PACKAGE_PROJECT_URL</PackageProjectUrl> <RepositoryUrl>REPOSITORY_URL</RepositoryUrl> <RepositoryType>Git</RepositoryType> <OutputPath>$(SolutionDir)\Presentation\Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY</OutputPath> <OutDir>$(OutputPath)</OutDir> <!--Set this parameter to true to get the dlls copied from the NuGet cache to the output of your project. You need to set this parameter to true if your plugin has a nuget package to ensure that the dlls copied from the NuGet cache to the output of your project--> <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> <ImplicitUsings>enable</ImplicitUsings> </PropertyGroup> <ItemGroup> <ProjectReference Include="$(SolutionDir)\Presentation\Nop.Web.Framework\Nop.Web.Framework.csproj" /> <ClearPluginAssemblies Include="$(SolutionDir)\Build\ClearPluginAssemblies.proj" /> </ItemGroup> <!-- This target executes after "Build" target --> <Target Name="NopTarget" AfterTargets="Build"> <!-- Delete unnecessary libraries from plugins path --> <MSBuild Projects="@(ClearPluginAssemblies)" Properties="PluginPath=$(OutDir)" Targets="NopClear" /> </Target> </Project>Tip
Kde PLUGIN_OUTPUT_DIRECTORY je třeba nahradit názvem pluginu, například
Payments.PayPalCommerce.Děláme to takto, abychom mohli využít nový přístup k přidávání referencí třetích stran, který byl zaveden v .NET Core. Ve skutečnosti to však není povinné. Navíc se reference z již odkazovaných knihoven načtou automaticky. Je to tedy velmi pohodlné.
Dalším krokem je vytvoření souboru
plugin.json, který je vyžadován pro každý plugin. Tento soubor obsahuje metainformace popisující váš plugin. Stačí tento soubor zkopírovat z jakéhokoli jiného existujícího pluginu a upravit jej podle svých potřeb. Informace o souboruplugin.jsonnajdete v části Soubor plugin.jsonPosledním povinným krokem je vytvoření třídy, která implementuje rozhraní
IPlugin(jmenný prostorNop.Services.Plugins). nopCommerce obsahuje tříduBasePlugin, která již implementuje některé metodyIPlugina umožňuje vyhnout se duplikaci zdrojového kódu. nopCommerce také poskytuje některá specifická rozhraní odvozená odIPlugin. Například máme rozhraníIPaymentMethod, které se používá k vytváření nových pluginů platebních metod. Obsahuje některé metody, které jsou specifické pouze pro platební metody, napříkladProcessPaymentAsync()neboGetAdditionalHandlingFeeAsync(). V současnosti má nopCommerce následující specifická rozhraní pluginů:IPaymentMethod. Tyto pluginy se používají ke zpracování plateb.
IShippingRateComputationMethod. Tyto pluginy se používají k získání podporovaných způsobů doručení a odpovídajících cen dopravy. Například UPS, UPS, FedEx atd.
IPickupPointProvider. Tyto pluginy se používají k poskytování výdejních míst.
ITaxProvider. Poskytovatelé daní se používají k získání daňových sazeb.
IExchangeRateProvider. Používá se k získání směnného kurzu měny.
IDiscountRequirementRule. Umožňuje vytvářet nová pravidla slev, například „Fakturační země zákazníka musí být…“
IExternalAuthenticationMethod. Používá se k vytváření externích metod ověřování, jako jsou Facebook, X (Twitter), OpenID atd.
IMultiFactorAuthenticationMethod. Používá se k vytváření metod vícefaktorového ověřování, jako je GoogleAuthenticator atd.
Poznámka
Jde o nové rozhraní; od verze 4.40 poskytujeme odpovídající infrastrukturu pro integrace MFA přímo v základu.
IWidgetPlugin. Umožňuje vytvářet widgety. Widgety se vykreslují v určitých částech vašeho webu. Může jít například o blok „Live chat“ v levém sloupci webu.
IMiscPlugin. Pokud váš plugin neodpovídá žádnému z výše uvedených rozhraní.
Důležité
Po každém sestavení projektu vyčistěte řešení (solution) před provedením změn. Některé prostředky budou uloženy v cache, což může vývojáře přivést k šílenství.
Po přidání pluginu může být nutné řešení znovu sestavit. Pokud v Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY nevidíte knihovny DLL svého pluginu, musíte řešení znovu sestavit. nopCommerce nezobrazí váš plugin na stránce Lokální pluginy (Local Plugins), pokud vaše knihovny DLL neexistují ve správné složce v Nop.Web.
Zpracování požadavků. Controllery, modely a view
Nyní můžete plugin zobrazit v Administrace → Konfigurace → Lokální pluginy (Admin area → Configuration → Local Plugins). Jak jste ale jistě uhodli, náš plugin nic nedělá. Nemá ani uživatelské rozhraní pro svou konfiguraci. Vytvořme tedy stránku pro konfiguraci pluginu.
Nyní potřebujeme vytvořit controller, model a view.
- MVC controllery odpovídají za reakci na požadavky odeslané na web ASP.NET Core MVC. Každý požadavek prohlížeče je namapován na konkrétní controller.
- View obsahuje HTML značky a obsah, který se odesílá do prohlížeče. Při práci s aplikací
ASP.NET Core MVCje view ekvivalentem stránky. - MVC model obsahuje veškerou logiku vaší aplikace, která není obsažena ve view ani v controlleru.
Více informací o vzoru MVC najdete zde.
Pojďme tedy na to:
Vytvořte model. Přidejte do nového pluginu složku Models a poté přidejte novou třídu modelu, která vyhovuje vašim potřebám.
Vytvořte view. Přidejte do nového pluginu složku Views a poté přidejte soubor
*.cshtmls názvemConfigure.cshtml. Nastavte vlastnost "Build Action" souboru view na "Content" a vlastnost "Copy to Output Directory" na "Copy always". Upozorňujeme, že konfigurační stránka by měla používat layout_ConfigurePlugin.Ujistěte se také, že máte v adresáři \Views soubor
_ViewImports.cshtml. Stačí jej zkopírovat z jakéhokoli jiného existujícího pluginu.Vytvořte controller. Přidejte do nového pluginu složku Controllers a poté přidejte novou třídu controlleru. Osvědčeným postupem je pojmenovávat controllery pluginů
{Group}{Name}Controller.cs. Například PaymentPayPalStandardController. Pojmenovávat controllery tímto způsobem samozřejmě není povinné (jde pouze o doporučení). Poté vytvořte příslušnou akční metodu pro konfigurační stránku (v administraci). Pojmenujme jiConfigure. Připravte třídu modelu a předejte ji následujícímu view pomocí fyzické cesty k view:~/Plugins/{PluginOutputDirectory}/Views/Configure.cshtml.Pro svou akční metodu použijte následující atributy:
[AutoValidateAntiforgeryToken] [AuthorizeAdmin] //confirms access to the admin panel [Area(AreaNames.ADMIN)] //specifies the area containing a controller or action public class PayPalCommerceController : BasePluginController { public async Task<IActionResult> Configure(bool showtour = false) { return View("~/Plugins/Payments.PayPalCommerce/Views/Admin/Configure.cshtml"); } }Tip
Tyto atributy můžete přidat také přímo ke controlleru. V takovém případě není nutné jimi označovat každou metodu.
Otevřete například platební plugin
PayPalCommercea podívejte se na jeho implementaciPayPalCommerceController.
Poté byste pro každý plugin, který má konfigurační stránku, měli určit konfigurační URL. Základní třída BasePlugin má metodu GetConfigurationPageUrl, která vrací konfigurační URL:
private readonly INopUrlHelper _nopUrlHelper;
public PayPalCommercePaymentMethod(INopUrlHelper nopUrlHelper)
{
_nopUrlHelper = nopUrlHelper;
}
public override string GetConfigurationPageUrl()
{
return _nopUrlHelper.RouteUrl(PayPalCommerceDefaults.Route.Configuration);
}
Pro routing mimo controllery se nyní používá INopUrlHelper. Názvy standardních cest (routes) jsou uloženy jako konstanty ve výchozích hodnotách pluginu (defaults).
/// <summary>
/// Represents the plugin constants
/// </summary>
public class PayPalCommerceDefaults
{
/// <summary>
/// Represents the route names
/// </summary>
public class Route
{
/// <summary>
/// Gets the configuration route name
/// </summary>
public static string Configuration => "Plugin.Payments.PayPalCommerce.Configure";
}
}
Registrace cesty ke konfigurační stránce pluginu bude vypadat takto.
endpointRouteBuilder.MapControllerRoute(name: PayPalCommerceDefaults.Route.Configuration,
pattern: "Admin/PayPalCommerce/Configure",
defaults: new { controller = "{CONTROLLER_NAME}", action = "{ACTION_NAME}", area = AreaNames.ADMIN });
Kde je název vašeho controlleru a je název akce (obvykle Configure).
Jakmile plugin nainstalujete a přidáte konfigurační metodu, najdete odkaz na konfiguraci pluginu v Administrace → Konfigurace → Lokální pluginy (Admin → Configuration → Local Plugins).
Tip
Nejjednodušší způsob, jak výše popsané kroky provést, je otevřít jakýkoli jiný plugin a zkopírovat tyto soubory do projektu svého pluginu. Poté stačí přejmenovat příslušné třídy a adresáře.
Například struktura projektu pluginu PayPalCommerce vypadá jako na obrázku níže:

Zpracování metod "InstallAsync", "UninstallAsync" a "UpdateAsync"
Tento krok je volitelný. Některé pluginy mohou během instalace vyžadovat dodatečnou logiku. Plugin může například vložit nové lokalizační prostředky. Otevřete tedy svou implementaci IPlugin (ve většině případů bude odvozena od třídy BasePlugin) a přepište následující metody:
- InstallAsync. Tato metoda se zavolá během instalace pluginu. Zde můžete inicializovat jakákoli nastavení, vložit nové lokalizační prostředky nebo vytvořit nové databázové tabulky (pokud je to potřeba).
- UninstallAsync. Tato metoda se zavolá během odinstalace pluginu.
- UpdateAsync. Tato metoda se zavolá během aktualizace pluginu (když se změní jeho verze v souboru
plugin.json).
Důležité
Pokud některou z těchto metod přepíšete, nezakrývejte její základní implementaci.
Například přepsaná metoda InstallAsync by měla obsahovat následující volání metody: base.Install(). Metoda InstallAsync pluginu PayPalStandard vypadá jako kód níže
public override async Task InstallAsync()
{
await _settingService.SaveSettingAsync(new PayPalStandardPaymentSettings
{
UseSandbox = true
});
await _localizationService.AddOrUpdateLocaleResourceAsync(new Dictionary<string, string>
{
...
});
await base.InstallAsync();
}
Tip
Seznam nainstalovaných pluginů se nachází v \App_Data\plugins.json. Seznam se vytváří během instalace.
Cesty (routes)
Zde se podíváme, jak registrovat cesty (routes) pluginu. Routing v ASP.NET Core odpovídá za mapování příchozích požadavků prohlížeče na konkrétní akce MVC controllerů. Více informací o routingu najdete zde. Postupujte tedy podle následujících kroků:
Pokud potřebujete přidat vlastní cestu, vytvořte soubor RouteProvider.cs. Ten informuje systém nopCommerce o cestách pluginu. Například následující třída RouteProvider přidává novou cestu, ke které lze přistoupit otevřením webového prohlížeče a přechodem na URL http://www.yourStore.com/Plugins/PayPalCommerceWebhook/WebhookHandler :
public class RouteProvider : IRouteProvider
{
/// <summary>
/// Register routes
/// </summary>
/// <param name="endpointRouteBuilder">Route builder</param>
public void RegisterRoutes(IEndpointRouteBuilder endpointRouteBuilder)
{
...
endpointRouteBuilder.MapControllerRoute(name: PayPalCommerceDefaults.Route.Webhook,
pattern: "Plugins/PayPalCommerce/Webhook",
defaults: new { controller = "PayPalCommerceWebhook", action = "WebhookHandler" });
}
/// <summary>
/// Gets a priority of route provider
/// </summary>
public int Priority => 0;
}
Aktualizace nopCommerce může pluginy rozbít
Některé pluginy mohou zastarat a přestat fungovat s novější verzí nopCommerce. Pokud máte po aktualizaci na novější verzi problémy, plugin smažte a navštivte oficiální web nopCommerce, abyste zjistili, zda je k dispozici novější verze. Mnoho autorů pluginů své pluginy aktualizuje, aby vyhovovaly novější verzi, někteří to však neudělají a jejich pluginy se s vylepšeními nopCommerce stanou zastaralými. Ve většině případů však stačí otevřít příslušný soubor plugin.json a aktualizovat pole SupportedVersions.
Závěr
Doufáme, že vám to pomůže začít s nopCommerce a připraví vás na tvorbu propracovanějších pluginů.
Šablona pluginu
Pro nové pluginy nopCommerce můžete použít naši šablonu pro Visual Studio. Vývojářům může ušetřit spoustu času, protože již nemusí ručně provádět všechny úvodní kroky. Například vytváření složek (Controllers, Views, Models atd.), dalších potřebných souborů (PluginNopStartup.cs, _ViewImports.cshtml, ObjectContex, plugin.json, konfigurace, reference projektu atd.).