nopCommerce प्लगइन डेवलपमेंट की संपूर्ण गाइड

nopCommerce प्लगइन क्यों महत्वपूर्ण हैं

nopCommerce दुनिया भर में 60,000 से अधिक ऑनलाइन स्टोर को संचालित करता है। यह .NET पर अग्रणी ओपन-सोर्स ई-कॉमर्स प्लेटफ़ॉर्म है — और इसका प्लगइन आर्किटेक्चर उस पूरे इकोसिस्टम के पीछे का इंजन है। हर पेमेंट गेटवे इंटीग्रेशन, हर शिपिंग कैरियर, हर विजेट और हर कस्टम फ़ीचर एक प्लगइन के रूप में मौजूद रहता है।

यदि आप समझते हैं कि nopCommerce प्लगइन कैसे बनाए जाते हैं, तो आप बाज़ार के सबसे सक्षम ई-कॉमर्स प्लेटफ़ॉर्म में से एक का विस्तार कर सकते हैं — और इसके माध्यम से एक व्यवसाय भी खड़ा कर सकते हैं। यह गाइड आपके पहले प्लगइन स्कैफ़ोल्ड से लेकर प्रोडक्शन डिप्लॉयमेंट पैटर्न तक सब कुछ कवर करती है।

हम 2009 से nopCommerce प्लगइन बना रहे हैं, और हमारे कैटलॉग में 38+ प्लगइन हैं — जिनमें 12 ब्राज़ीलियाई पेमेंट गेटवे इंटीग्रेशन और इस प्लेटफ़ॉर्म पर एकमात्र संपूर्ण PIX पेमेंट सॉल्यूशन शामिल है। यह गाइड उन प्लगइनों को बनाते हुए हमने जो सीखा है उसे दर्शाती है जो लाखों लेनदेन प्रोसेस करते हैं।

प्लगइन आर्किटेक्चर: बुनियाद

प्लगइन इंटरफ़ेस पदानुक्रम

हर nopCommerce प्लगइन Nop.Services.Plugins में मौजूद IPlugin इंटरफ़ेस से शुरू होता है। सब कुछ शुरू से लागू करवाने के बजाय, nopCommerce आपको BasePlugin देता है — एक abstract क्लास जो boilerplate को संभालती है — और सामान्य प्लगइन प्रकारों के लिए विशेष इंटरफ़ेसों का एक सेट देता है:

अपने उपयोग के मामले के लिए सबसे विशिष्ट इंटरफ़ेस चुनें। IPaymentMethod आपको संपूर्ण पेमेंट जीवनचक्र देता है — ProcessPaymentAsync, PostProcessPaymentAsync, RefundAsync, VoidAsync, CaptureAsync — जबकि IMiscPlugin उन सभी चीज़ों के लिए विकल्प है जो किसी मानक श्रेणी में फ़िट नहीं होतीं।

प्रोजेक्ट संरचना: चरण-दर-चरण

1. क्लास लाइब्रेरी प्रोजेक्ट बनाएँ

.NET 9 को लक्षित करते हुए एक नया Class Library प्रोजेक्ट बनाएँ। अनुशंसित नामकरण परंपरा Nop.Plugin.{Group}.{Name} है:

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

प्रोजेक्ट को सॉल्यूशन रूट पर \Plugins डायरेक्टरी में रखें (न कि \Nop.Web\Plugins के अंदर, जो डिप्लॉयमेंट लक्ष्य है)। .csproj आउटपुट पाथ को $(SolutionDir)\Presentation\Nop.Web\Plugins\{PluginOutputDirectory} पर सेट करें और यह सुनिश्चित करने के लिए कि NuGet निर्भरताएँ आउटपुट में कॉपी हों, CopyLocalLockFileAssemblies को सक्षम करें।

2. plugin.json बनाएँ

हर प्लगइन को मेटाडेटा के साथ एक plugin.json फ़ाइल की आवश्यकता होती है:

{
  "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"
}

SystemName आपके असेंबली नाम से मेल खाना चाहिए। SupportedVersions यह निर्धारित करता है कि कौन-से nopCommerce संस्करण प्लगइन को इंस्टॉल कर सकते हैं। यदि आप nopCommerce को अपग्रेड करते हैं और कोई प्लगइन टूट जाता है, तो सबसे पहले इस फ़ील्ड की जाँच करें — कई प्लगइनों को केवल अपने समर्थित संस्करणों को अपडेट करने की आवश्यकता होती है।

3. प्लगइन क्लास लागू करें

एक ऐसी क्लास बनाएँ जो उपयुक्त प्लगइन इंटरफ़ेस को लागू करती हो और BasePlugin से derive होती हो:

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);
    }
}

InstallAsync, UninstallAsync और UpdateAsync ओवरराइड आपके जीवनचक्र हुक हैं। हमेशा बेस इम्प्लीमेंटेशन को कॉल करें — base.InstallAsync() प्लगइन सिस्टम में पंजीकरण को संभालता है।

4. कॉन्फ़िगरेशन जोड़ें (Admin UI)

सेटिंग्स वाले प्लगइनों के लिए, एक MVC कंट्रोलर, एक मॉडल और एक Razor व्यू बनाएँ:

1. Controllers/{Name}Controller.cs — [AuthorizeAdmin] और [Area(AreaNames.ADMIN)] से सज्जित। BasePluginController से इनहेरिट करें।
2. Models/ConfigurationModel.cs — आपकी सेटिंग्स प्रॉपर्टीज़ और स्थानीयकरण के लिए [NopResourceDisplayName] एट्रिब्यूट्स वाली एक सादा क्लास।
3. Views/Configure.cshtml — _ConfigurePlugin लेआउट का उपयोग करता है। साथ ही _ViewImports.cshtml भी शामिल करें (किसी मौजूदा प्लगइन से कॉपी करें)।

IRouteProvider को लागू करने वाली RouteProvider.cs में कॉन्फ़िगरेशन रूट पंजीकृत करें:

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;
}

पेमेंट प्लगइन बनाना: वास्तविक-दुनिया का पैटर्न

पेमेंट प्लगइन सबसे सामान्य — और सबसे जटिल — प्लगइन प्रकार हैं। यहाँ वह प्रोडक्शन पैटर्न है जिसका उपयोग हम SplatDev में करते हैं:

मुख्य घटक

1. Settings क्लास: ISettings को लागू करने वाली एक क्लास जिसमें API कीज़, URLs, मोड (sandbox/production) और फ़ीचर टॉगल के लिए प्रॉपर्टीज़ हों। सीक्रेट्स को ISettingService में संग्रहीत करें — क्रेडेंशियल्स को कभी हार्ड-कोड न करें।
2. Defaults क्लास: स्थिरांकों वाली एक static क्लास — रूट नाम, सिस्टम नाम, कॉन्फ़िगरेशन URLs, API एंडपॉइंट्स। यह मैजिक स्ट्रिंग्स को आपके लॉजिक से बाहर रखती है।
3. Service क्लास: आपका वास्तविक इंटीग्रेशन लॉजिक — पेमेंट गेटवे को HTTP कॉल, रिस्पॉन्स पार्सिंग, webhook हैंडलिंग। DI के माध्यम से inject करें और इसे टेस्ट करने योग्य रखें (इंटरफ़ेस + इम्प्लीमेंटेशन)।
4. Event consumers: स्टोर इवेंट्स पर प्रतिक्रिया देने के लिए IConsumer<OrderPlacedEvent> और समान इंटरफ़ेस लागू करें — लेनदेन की पुष्टि भेजें, पेमेंट के बाद के वर्कफ़्लो ट्रिगर करें।

पेमेंट फ़्लो: वे विधियाँ जिन्हें आपको लागू करना ही होगा

ब्राज़ीलियाई पेमेंट प्लगइन उदाहरण: PIX

ब्राज़ील की PIX त्वरित पेमेंट प्रणाली को एक विशिष्ट फ़्लो की आवश्यकता होती है: एक payload (EMV स्ट्रिंग) के साथ QR कोड जनरेट करें, इसे ग्राहक को दिखाएँ, और पेमेंट प्राप्त होने पर webhook पुष्टिकरण की प्रतीक्षा करें। यहाँ पैटर्न है:

1. ProcessPaymentAsync: PIX चार्ज बनाने के लिए PSP (PagSeguro, MercadoPago, आदि) को कॉल करें। लेनदेन ID (txid) और EMV payload को संग्रहीत करें।
2. PostProcessPaymentAsync: QR कोड (EMV payload से जनरेट किया गया) और "copy-paste" कोड रेंडर करें। पेमेंट स्थिति को Pending पर सेट करें।
3. Webhook handler: जब PIX पेमेंट की पुष्टि करता है तब PSP एक webhook भेजता है। ऑर्डर स्थिति अपडेट करें और OrderPaidEvent ट्रिगर करें।

यही पैटर्न SplatDev के सभी 12 ब्राज़ीलियाई पेमेंट प्लगइनों के पीछे है — जो PagSeguro, MercadoPago, Cielo, Banco Inter, Pagar.me, Rede, GetNet, PicPay, NuPay, Braspag और InfinityPay के माध्यम से PIX, boleto और किस्त-आधारित क्रेडिट कार्ड पेमेंट प्रोसेस करते हैं।

विजेट: थीम को छुए बिना UI जोड़ना

विजेट प्लगइन IWidgetPlugin को लागू करते हैं और उन्हें यह निर्दिष्ट करना होता है कि वे किन विजेट ज़ोन में रेंडर होते हैं:

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

फिर विजेट का HTML लौटाने के लिए GetPublicViewComponentAsync लागू करें। विजेट सिस्टम आपके द्वारा पंजीकृत प्रत्येक ज़ोन के लिए इस विधि को कॉल करता है।

सामान्य विजेट पैटर्न: newsletter साइनअप पॉपअप, live chat बटन, ट्रस्ट बैज, कुकी सहमति बैनर, WhatsApp फ़्लोटिंग बटन, हाल ही में देखे गए उत्पाद, और सोशल प्रूफ़ नोटिफ़िकेशन।

डेटाबेस एक्सेस: IRepository<T> और माइग्रेशन

nopCommerce डेटा एक्सेस के लिए IRepository<T> के माध्यम से एक repository पैटर्न का उपयोग करता है। उन प्लगइनों के लिए जिन्हें कस्टम टेबल्स की आवश्यकता होती है:

1. अपनी एंटिटी क्लास परिभाषित करें (इसमें एक Id प्रॉपर्टी होनी चाहिए)।
2. एक ObjectContext बनाएँ जो आपकी एंटिटी को Entity Framework Core के साथ पंजीकृत करे।
3. InstallAsync में, टेबल्स बनाने के लिए _dbContext.InstallAsync() का उपयोग करें।
4. UninstallAsync में, उन्हें drop करने के लिए _dbContext.UninstallAsync() का उपयोग करें।

प्लगइन संस्करणों के बीच स्कीमा माइग्रेशन के लिए, अपने UpdateAsync ओवरराइड में एक MigrationManager जोड़ने पर विचार करें जो वर्तमान स्कीमा संस्करण की जाँच करे और आवश्यक ALTER TABLE स्टेटमेंट लागू करे। यह प्लगइनों के लिए FluentMigrator की तुलना में सरल है और आपके माइग्रेशन लॉजिक को एक ही स्थान पर रखता है।

टेस्टिंग: अपने प्लगइन को एक उत्पाद की तरह मानें

SplatDev में, हम हर प्लगइन को उसके अपने टेस्ट सूट के साथ एक उत्पाद की तरह मानते हैं:

• यूनिट टेस्ट (xUnit): अपनी सर्विस लेयर को अलग-थलग होकर टेस्ट करें। ISettingService, IRepository<T> और किसी भी HTTP क्लाइंट को mock करें। आपके पेमेंट लॉजिक, कर गणनाओं और शिपिंग दर गणनाओं में बिज़नेस लॉजिक पर 100% यूनिट टेस्ट कवरेज होनी चाहिए।
• इंटीग्रेशन टेस्ट: एक टेस्ट nopCommerce इंस्टेंस चालू करें और सत्यापित करें कि आपका प्लगइन पूरे जीवनचक्र के माध्यम से इंस्टॉल, कॉन्फ़िगर और प्रोसेस करता है। पेमेंट गेटवे के लिए sandbox/टेस्ट क्रेडेंशियल्स का उपयोग करें।
• स्थानीयकरण टेस्ट: सत्यापित करें कि आप जिस भी भाषा के समर्थन का दावा करते हैं उसके लिए सभी locale संसाधन मौजूद हैं। गायब संसाधन स्ट्रिंग्स सबसे सामान्य प्लगइन बग है।
• StyleCop अनुपालन: nopCommerce StyleCop अनुपालन की अपेक्षा करता है। इसे अपने CI पाइपलाइन में चलाएँ — यह कोड रिव्यू से पहले सूक्ष्म समस्याओं को पकड़ लेता है।

सामान्य खामियाँ (और उनसे कैसे बचें)

1. base.InstallAsync() को कॉल न करना

यदि आप बेस को कॉल किए बिना InstallAsync को ओवरराइड करते हैं, तो आपका प्लगइन प्लगइन सिस्टम के साथ पंजीकृत नहीं होगा और एडमिन में दिखाई नहीं देगा। अपने ओवरराइड के अंत में हमेशा await base.InstallAsync() शामिल करें।

2. क्रेडेंशियल्स को हार्ड-कोड करना

API कीज़, टोकन और सीक्रेट्स को ISettingService में संग्रहीत करें — उन्हें कभी plugin.json में या क्लास स्थिरांकों के रूप में हार्ड-कोड न करें। सेटिंग्स पेज को एडमिनों को इन मानों को कॉन्फ़िगर करने की अनुमति देनी चाहिए, और उपयुक्त होने पर उन्हें एन्क्रिप्टेड रूप में संग्रहीत किया जाना चाहिए।

3. संस्करण संगतता को अनदेखा करना

nopCommerce संस्करण प्लगइनों को तोड़ देते हैं। plugin.json में SupportedVersions फ़ील्ड सजावटी नहीं है — nopCommerce आपके प्लगइन को लोड करने से पहले इसकी जाँच करता है। nopCommerce को अपग्रेड करते समय, नए संस्करण के विरुद्ध अपने प्लगइन को टेस्ट करें और इस फ़ील्ड को अपडेट करें। बिना टेस्ट किए केवल संख्या न बढ़ाएँ।

4. रिक्वेस्ट थ्रेड को ब्लॉक करना

सभी प्लगइन विधियाँ एक कारण से async हैं। यदि आपका पेमेंट प्रोसेसर किसी बाहरी API को कॉल करता है, तो वह कॉल async होनी चाहिए। .Result या .Wait() के साथ थ्रेड को ब्लॉक करने से लोड के तहत प्रदर्शन घट जाएगा और deadlock हो सकते हैं।

5. कोई इवेंट कंज़्यूमर नहीं

जो प्लगइन केवल एक कॉन्फ़िगरेशन पेज प्रदान करते हैं वे मूल बात से चूक जाते हैं। nopCommerce प्लगइनों की असली ताकत इवेंट कंज़्यूमरों से आती है — OrderPlacedEvent, CustomerRegisteredEvent या ShipmentDeliveredEvent जैसे स्टोर इवेंट्स पर प्रतिक्रिया देने से। अपने प्लगइन को केवल एडमिन UI में नहीं, बल्कि स्टोर के बिज़नेस इवेंट्स में जोड़ें।

nopCommerce 4.90: प्लगइन डेवलपरों के लिए क्या नया है

nopCommerce 4.90 .NET 9 को लक्षित करता है और प्लगइन डेवलपरों के लिए कई सुधार लाता है:

• .NET 9 रनटाइम: आपके प्लगइन अब तक के सबसे तेज़ .NET पर चलते हैं — JIT सुधारों, GC डायनामिक अनुकूलन और लूप ऑप्टिमाइज़ेशन का स्वतः लाभ उठाते हुए।
• C# 13 समर्थन: अपने प्लगइन कोड में params कलेक्शन, ref struct इंटरफ़ेस और partial प्रॉपर्टीज़ का उपयोग करें।
• अपडेटेड NuGet निर्भरताएँ: अंतर्निहित पैकेज (Autofac, FluentValidation, आदि) अपडेट किए गए हैं। अपने प्लगइन के निर्भरता वृक्ष को टेस्ट करें।
• IMultiFactorAuthenticationMethod: MFA प्लगइन अब अपने स्वयं के इंटरफ़ेस के साथ एक first-class अवधारणा हैं।
• बेहतर प्लगइन टेम्पलेट: आधिकारिक nopCommerce प्लगइन Visual Studio टेम्पलेट को 4.90 के लिए अपडेट किया गया है — इसे अपने शुरुआती बिंदु के रूप में उपयोग करें।

यहाँ से आगे कहाँ जाएँ

nopCommerce प्लगइन डेवलपमेंट एक करियर-निर्माण कौशल है। nopCommerce मार्केटप्लेस सक्रिय और बढ़ता हुआ है, और अच्छी तरह से बनाए गए प्लगइन अपडेट और सपोर्ट के माध्यम से आवर्ती राजस्व उत्पन्न करते हैं। SplatDev में, प्लगइन हमारा मुख्य व्यवसाय हैं — हमारा स्टोर store.splatdev.com पर 38+ प्लगइन रखता है, और हम वर्षों से एक Gold Solutions Partner रहे हैं।

यदि आप nopCommerce पर एक ई-कॉमर्स प्रोजेक्ट बना रहे हैं, तो आपको सब कुछ शुरू से बनाने की आवश्यकता नहीं है। हमारा कैटलॉग ब्राज़ीलियाई पेमेंट, शिपिंग (Correios, JadLog, Braspress), ERP इंटीग्रेशन और कस्टम कार्यक्षमता को कवर करता है। यदि आपको कुछ ऐसा चाहिए जो हमारे पास नहीं है, तो हम कस्टम प्लगइन भी बनाते हैं।

अपने nopCommerce स्टोर को बनाने या विस्तार करने के लिए तैयार हैं? हमारी टीम यह 2009 से कर रही है — इकोसिस्टम में लगभग किसी भी अन्य से अधिक समय से।

हमारी nopCommerce टीम के साथ काम करें

या हमारे प्लगइन कैटलॉग को ब्राउज़ करें: store.splatdev.com