راهنمای جامع توسعه افزونه اختصاصی برای ناپ کامرس

افزونه اختصاصی چیست و چرا باید آن را توسعه دهید؟

افزونه اختصاصی برای ناپ کامرس به مجموعه‌ای از کدها و فایل‌های مستقل گفته می‌شود که قابلیت‌های جدیدی را به فروشگاه شما اضافه می‌کنند، بدون اینکه ساختار اصلی سیستم تغییر کند. این افزونه‌ها می‌توانند هر چیزی باشند، از یک ویجت ساده که پیام "سلام دنیا" را در فروشگاه نمایش می‌دهد تا یک سیستم کامل مدیریت تخفیف‌های پیچیده و پیشرفته .

دلایل اصلی برای توسعه افزونه اختصاصی عبارتند از:

• یکپارچه‌سازی با سیستم‌های خاص: اتصال فروشگاه به نرم‌افزارهای حسابداری، انبارداری یا CRM که در افزونه‌های آماده وجود ندارد.
• پیاده‌سازی فرآیندهای تجاری منحصربه‌فرد: اعمال قوانین قیمت‌گذاری، تخفیف یا ارسال که مختص کسب‌وکار شماست.
• افزایش امنیت و عملکرد: کاهش وابستگی به افزونه‌های شخص ثالث و بهینه‌سازی برای نیازهای خاص.
• قابلیت به‌روزرسانی آسان: با جداسازی کدهای سفارشی از هسته اصلی، می‌توانید ناپ کامرس را به‌روزرسانی کنید بدون اینکه کدهای شما از بین بروند .

پیش‌نیازهای توسعه افزونه اختصاصی

قبل از شروع فرآیند توسعه افزونه اختصاصی برای ناپ کامرس، باید موارد زیر را فراهم کنید:

محیط توسعه

• سورس کد ناپ کامرس: آخرین نسخه را از وب‌سایت رسمی یا گیت‌هاب دانلود کنید .
• Microsoft Visual Studio: نسخه ۲۰۲۲ یا جدیدتر برای توسعه بر اساس .NET .
• .NET SDK: نسخه متناسب با نسخه ناپ کامرس خود (برای نسخه ۴.۹۰، .NET 9.0) .
• SQL Server: برای پایگاه داده فروشگاه .

دانش فنی مورد نیاز

• آشنایی با C# و ASP.NET Core MVC: زیرا ناپ کامرس بر پایه این فناوری‌ها ساخته شده است .
• آشنایی با معماری ناپ کامرس: درک ساختار پوشه‌ها، سیستم افزونه‌ها و الگوی Repository .
• آشنایی با Dependency Injection: ناپ کامرس از این الگو به طور گسترده استفاده می‌کند .

مراحل گام‌به‌گام توسعه یک افزونه اختصاصی

برای ایجاد یک افزونه اختصاصی برای ناپ کامرس، مراحل زیر را به ترتیب دنبال کنید:

گام اول: ایجاد پروژه افزونه

در Visual Studio، روی پوشه Plugins در Solution Explorer کلیک راست کرده و Add → New Project را انتخاب کنید. پروژه را از نوع Class Library انتخاب کنید .

برای نام‌گذاری پروژه، از استانداردهای ناپ کامرس پیروی کنید. ساختار نام باید به صورت زیر باشد :

مثال:

Nop.Plugin.[GroupName].[PluginName]

به عنوان مثال، اگر می‌خواهید یک افزونه برای مدیریت تخفیف‌ها بسازید: Nop.Plugin.DiscountRules.CustomRule.

مسیر پروژه را روی /src/Plugins/ تنظیم کنید .

گام دوم: پیکربندی فایل پروژه

پس از ایجاد پروژه، فایل .csproj را باز کرده و محتوای آن را با کد استاندارد جایگزین کنید :

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net9.0</TargetFramework>
        <OutputPath>$(SolutionDir)\Presentation\Nop.Web\Plugins\[PLUGIN_OUTPUT_DIRECTORY]</OutputPath>
        <OutDir>$(OutputPath)</OutDir>
    </PropertyGroup>
</Project>

این تنظیمات باعث می‌شود که خروجی کامپایل (فایل‌های DLL) مستقیماً در پوشه Plugins وب‌سایت ناپ کامرس قرار گیرد .

گام سوم: ایجاد فایل plugin.json

این فایل حاوی اطلاعات متا (Meta-Information) افزونه شماست و ناپ کامرس از آن برای شناسایی و نمایش افزونه در پنل مدیریت استفاده می‌کند .

یک فایل plugin.json در ریشه پروژه خود ایجاد کنید و محتوای زیر را در آن قرار دهید :

{
    "Group": "Misc",
    "FriendlyName": "نام دوستانه افزونه",
    "SystemName": "Nop.Plugin.Misc.YourPluginName",
    "Version": "1.00",
    "Author": "نام شما",
    "DisplayOrder": 1,
    "FileName": "Nop.Plugin.Misc.YourPluginName.dll",
    "Description": "توضیحات مختصر درباره افزونه"
}

نکات مهم در مورد فایل plugin.json :

• SystemName: باید منحصربه‌فرد باشد و با فضای نام پروژه هماهنگ باشد.
• FileName: نام فایل DLL خروجی پروژه باید دقیقاً همین باشد.
• Group: دسته‌بندی افزونه در پنل مدیریت را مشخص می‌کند.

گام چهارم: ایجاد کلاس اصلی افزونه

هر افزونه باید یک کلاس اصلی داشته باشد که اینترفیس IPlugin را پیاده‌سازی کند. معمولاً از کلاس BasePlugin که اینترفیس را پیاده‌سازی کرده، ارث‌بری می‌کنیم .

یک فایل به نام YourPluginNamePlugin.cs در ریشه پروژه ایجاد کنید :

using Nop.Services.Plugins;
using Nop.Web.Framework;

namespace Nop.Plugin.Misc.YourPluginName
{
    public class YourPluginNamePlugin : BasePlugin
    {
        public override string GetConfigurationPageUrl()
        {
            return $"{Nop.Web.Framework.Constants.NopTab.AdminArea}/YourPluginName/Configure";
        }

        public override async Task InstallAsync()
        {
            // کدهای نصب افزونه (ایجاد جداول، تنظیمات اولیه و ...)
            await base.InstallAsync();
        }

        public override async Task UninstallAsync()
        {
            // کدهای حذف افزونه (حذف جداول، تنظیمات و ...)
            await base.UninstallAsync();
        }
    }
}

متد GetConfigurationPageUrl آدرس صفحه تنظیمات افزونه را در پنل مدیریت مشخص می‌کند . متدهای InstallAsync و UninstallAsync به ترتیب هنگام نصب و حذف افزونه اجرا می‌شوند و معمولاً برای ایجاد یا حذف جداول پایگاه داده و تنظیمات اولیه استفاده می‌شوند .

گام پنجم: افزودن کنترلر، مدل و ویو

برای ایجاد رابط کاربری برای افزونه خود، باید یک کنترلر، مدل و ویو بسازید .

ساختار پوشه‌ها

در ریشه پروژه، پوشه‌های زیر را ایجاد کنید :

• Controllers: برای کنترلرهای MVC.
• Models: برای مدل‌های داده.
• Views: برای فایل‌های cshtml (صفحات نمایشی).

ایجاد کنترلر

در پوشه Controllers، یک کلاس کنترلر به نام YourPluginNameController.cs ایجاد کنید :

using Microsoft.AspNetCore.Mvc;
using Nop.Web.Framework.Controllers;

namespace Nop.Plugin.Misc.YourPluginName.Controllers
{
    public class YourPluginNameController : BasePluginController
    {
        public IActionResult Configure()
        {
            return View("~/Plugins/Misc.YourPluginName/Views/Configure.cshtml");
        }
    }
}

ایجاد ویو (صفحه تنظیمات)

در پوشه Views، فایل Configure.cshtml را ایجاد کنید :

@{
    Layout = "_AdminLayout";
}
<div class="content-header clearfix">
    <h1>تنظیمات افزونه شما</h1>
</div>
<div class="content">
    <!-- محتوای صفحه تنظیمات -->
</div>

نکته مهم: فایل _ViewImports.cshtml را از یک افزونه موجود کپی کرده و در پوشه Views قرار دهید تا ویوها بتوانند از توابع و کلاس‌های کمکی ناپ کامرس استفاده کنند .

گام ششم: اضافه کردن منطق کسب‌وکار (سرویس‌ها)

برای افزودن منطق پیچیده‌تر مانند دریافت داده از پایگاه داده، بهتر است سرویس‌های جداگانه ایجاد کنید. ناپ کامرس از الگوی Repository برای دسترسی به داده استفاده می‌کند .

در پوشه Services (که باید ایجاد کنید)، یک اینترفیس و کلاس پیاده‌سازی آن ایجاد کنید :

// ICustomService.cs
public interface ICustomService
{
    Task<List<CustomModel>> GetCustomDataAsync();
}

// CustomService.cs
public class CustomService : ICustomService
{
    private readonly IRepository<CustomTable> _customRepository;

    public CustomService(IRepository<CustomTable> customRepository)
    {
        _customRepository = customRepository;
    }

    public async Task<List<CustomModel>> GetCustomDataAsync()
    {
        // منطق دریافت داده از پایگاه داده
    }
}

گام هفتم: ثبت سرویس‌ها در Dependency Injection

برای اینکه ناپ کامرس بتواند سرویس‌های شما را شناسایی کند، باید آن‌ها را در DI Container ثبت کنید .

یک کلاس به نام PluginNopStartup.cs در پوشه Infrastructure ایجاد کنید :

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Nop.Core.Infrastructure;

public class PluginNopStartup : INopStartup
{
    public void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        services.AddScoped<ICustomService, CustomService>();
    }

    public int Order => 1000;
}

این کلاس به طور خودکار در زمان راه‌اندازی برنامه اجرا می‌شود و سرویس‌های شما را ثبت می‌کند .

گام هشتم: بیلد و تست افزونه

پس از اتمام کدنویسی، پروژه را بیلد (Build) کنید. اگر همه چیز به درستی تنظیم شده باشد، فایل‌های DLL خروجی به صورت خودکار در پوشه Nop.Web\Plugins\[PLUGIN_OUTPUT_DIRECTORY] کپی می‌شوند .

برای تست افزونه:

1. پروژه ناپ کامرس را اجرا کنید.
2. به پنل مدیریت بروید و به Configuration → Local Plugins بروید.
3. افزونه خود را در لیست پیدا کرده و روی دکمه Install کلیک کنید .
4. پس از نصب، افزونه فعال می‌شود و می‌توانید آن را پیکربندی کنید.

انواع افزونه‌های اختصاصی

ناپ کامرس اینترفیس‌های مختلفی برای انواع افزونه‌ها ارائه می‌دهد که هر کدام کاربرد خاصی دارند :

IPaymentMethod (افزونه پرداخت)

برای ایجاد درگاه‌های پرداخت جدید. متدهایی مانند ProcessPaymentAsync و GetAdditionalHandlingFeeAsync را پیاده‌سازی می‌کند .

IShippingRateComputationMethod (افزونه حمل‌ونقل)

برای محاسبه نرخ حمل‌ونقل از سرویس‌هایی مانند UPS، FedEx و غیره .

IWidgetPlugin (ویجت)

برای نمایش المان‌های UI در نقاط مشخصی از فروشگاه (Widget Zones) مانند نوار کناری، فوتر یا هدر .

IDiscountRequirementRule (افزونه تخفیف)

برای ایجاد قوانین جدید تخفیف مانند تخفیف بر اساس کشور مشتری یا تاریخ تولد .

ITaxProvider (افزونه مالیات)

برای محاسبه نرخ‌های مالیات بر اساس قوانین خاص .

IMiscPlugin (سایر افزونه‌ها)

برای افزونه‌هایی که در هیچ یک از دسته‌های بالا قرار نمی‌گیرند .

تکنیک‌های پیشرفته در توسعه افزونه

دسترسی به پایگاه داده

برای دسترسی به پایگاه داده در افزونه خود، از الگوی Repository استفاده کنید. ناپ کامرس کلاس‌های IRepository<T> را برای تمام موجودیت‌ها فراهم می‌کند .

برای ایجاد جداول جدید، از متد InstallAsync استفاده کنید و کدهای ایجاد جدول را با استفاده از Entity Framework یا SQL خام بنویسید.

افزودن آیتم به منوی مدیریت

برای اضافه کردن آیتم منوی اختصاصی به پنل مدیریت، باید از طریق افزونه خود عمل کنید. مستندات رسمی ناپ کامرس راهنمای کاملی برای این کار ارائه داده است .

افزودن فایل‌های CSS و JS

برای افزودن فایل‌های استایل و اسکریپت به افزونه خود، از سیستم مدیریت منابع ناپ کامرس استفاده کنید .

ابزارهای کمکی برای توسعه افزونه

برای تسریع فرآیند توسعه افزونه اختصاصی برای ناپ کامرس، می‌توانید از ابزارهای زیر استفاده کنید:

NopCommerce CLI (nopcli)

این ابزار خط فرمان به شما امکان می‌دهد یک پروژه افزونه را در کمتر از ۵ دقیقه ایجاد کنید :

npm install -g nopcli
nopcli new -g=[GROUP NAME] -p=[PLUGIN NAME]

کپی از افزونه‌های موجود

یک راهکار سریع و مطمئن برای شروع، کپی کردن یک افزونه موجود (با عملکرد مشابه) و جایگزینی متن‌ها با نام افزونه جدید است. این کار باعث می‌شود که تنظیمات مهم مانند _ViewImports.cshtml و پیکربندی‌های اولیه از قلم نیفتند .

نکات مهم و بهترین شیوه‌ها

جدا کردن کد از هسته اصلی

همیشه سعی کنید تغییرات خود را از طریق افزونه‌ها اعمال کنید و هرگز فایل‌های هسته ناپ کامرس را مستقیماً ویرایش نکنید. این کار باعث می‌شود که به‌روزرسانی‌های آینده به سادگی قابل اعمال باشند .

تست کامل

پیش از نصب افزونه در محیط زنده (Production)، آن را در محیط توسعه (Development) به طور کامل تست کنید. از ابزارهای Debugging Visual Studio برای عیب‌یابی استفاده کنید.

پشتیبان‌گیری

همیشه قبل از نصب یا به‌روزرسانی هر افزونه‌ای، از پایگاه داده و فایل‌های فروشگاه خود پشتیبان کامل تهیه کنید.

پاکسازی پروژه پس از هر بیلد

برخی از منابع در ناپ کامرس کش می‌شوند. پس از هر بار بیلد، پروژه را Clean کنید تا از بروز خطاهای ناشی از کش جلوگیری شود .

جمع‌بندی

توسعه یک افزونه اختصاصی برای ناپ کامرس فرآیندی قدرتمند و انعطاف‌پذیر است که به شما امکان می‌دهد فروشگاه خود را دقیقاً مطابق با نیازهای کسب‌وکارتان شخصی‌سازی کنید. با پیروی از این راهنمای جامع و استفاده از مستندات رسمی ناپ کامرس، می‌توانید افزونه‌های حرفه‌ای و کارآمدی ایجاد کنید که تجربه کاربری را بهبود بخشیده و مزیت رقابتی قابل توجهی برای شما ایجاد کند.

به یاد داشته باشید که سیستم افزونه‌ای ناپ کامرس به گونه‌ای طراحی شده که تقریباً هر جنبه‌ای از فروشگاه را می‌توانید از طریق افزونه‌ها گسترش دهید . چه نیاز به یک درگاه پرداخت جدید داشته باشید، چه یک سیستم تخفیف پیچیده یا یک ویجت تعاملی، مسیر توسعه افزونه همیشه در دسترس شماست. از جامعه بزرگ توسعه‌دهندگان ناپ کامرس نیز برای رفع سوالات و مشکلات خود کمک بگیرید و همواره با به‌روزرسانی افزونه‌های خود، فروشگاهی امن و کارآمد را برای مشتریان خود فراهم آورید.