• نویسنده
• آگوست 09, 2019

راهنمای کامل استفاده از ActiveX در برنامه‌های NET. 

تکنولوژی ActiveX، گرچه یک فناوری قدیمی‌تر محسوب می‌شود، اما هنوز هم در بسیاری از پروژه‌ها و برای توزیع API توسط شرکت‌های مختلف کاربرد دارد. ادغام کنترل‌های ActiveX در برنامه‌های Windows Forms با ویژوال استودیو بسیار ساده است. با این حال، استفاده از ActiveX در برنامه‌های NET. مانند Console Application یا Class Library چالش‌های خاص خود را به همراه دارد. 🤔

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

ActiveX چیست و چرا هنوز اهمیت دارد؟

ActiveX یک فریمورک مبتنی بر (Component Object Model) COM از مایکروسافت است. این فناوری به توسعه‌دهندگان اجازه می‌دهد تا کامپوننت‌های نرم‌افزاری قابل استفاده مجدد (reusable) ایجاد کنند. این کامپوننت‌ها می‌توانند در برنامه‌های مختلف و حتی در صفحات وب (در گذشته با Internet Explorer) به کار گرفته شوند.

مزیت‌ها و کاربردهای ActiveX

اگرچه تکنولوژی‌های جدیدتری ظهور کرده‌اند، اما ActiveX هنوز در سناریوهای خاصی ارزشمند است.

• ✅ توسعه سریع: استفاده از کامپوننت‌های آماده، سرعت توسعه نرم‌افزار را به شدت افزایش می‌دهد.
• 🤝 سازگاری با کدهای قدیمی: بسیاری از سیستم‌های بزرگ و قدیمی (Legacy Systems) بر پایه ActiveX ساخته شده‌اند. بنابراین، برای تعامل با آن‌ها همچنان به این فناوری نیاز است.
• ⚙️ ادغام سخت‌افزار: بسیاری از تولیدکنندگان سخت‌افزار (مانند دوربین‌های مداربسته یا دستگاه‌های صنعتی)، API خود را در قالب یک کنترل ActiveX ارائه می‌دهند.
• 🧩 قابلیت استفاده مجدد: یک کنترل ActiveX می‌تواند توسط زبان‌های برنامه‌نویسی مختلفی که از COM پشتیبانی می‌کنند، استفاده شود.

پیش‌نیاز اصلی: ثبت (Register) کردن کنترل ActiveX

قبل از هر کاری، کنترل ActiveX باید روی سیستم شما ثبت شود. در غیر این صورت، برنامه شما در زمان اجرا با خطای Class not registered مواجه خواهد شد. این کنترل‌ها معمولاً در قالب فایل‌های .ocx یا .dll عرضه می‌شوند.

چگونه ActiveX را ثبت یا حذف کنیم؟

برای این کار باید از ابزار regsvr32.exe در Command Prompt استفاده کنید.

1. اجرای CMD با دسترسی Admin: منوی Start را باز کرده، cmd را تایپ کنید. سپس روی Command Prompt راست‌کلیک کرده و Run as administrator را بزنید. این مرحله برای جلوگیری از خطای دسترسی 0x80040200 ضروری است.
2. اجرای دستور ثبت: برای رجیستر کردن فایل، دستور زیر را وارد کنید.

regsvr32 “C:\path\to\your\activex_name.ocx”

3.اجرای دستور حذف (Unregister): برای حذف کنترل از رجیستری ویندوز، از سوییچ /u استفاده کنید.

regsvr32 /u “C:\path\to\your\activex_name.ocx”

نکته مهم: همیشه مسیر کامل فایل .ocx یا .dll را در دستور وارد کنید.

استفاده از ActiveX در کتابخانه کلاس (Class Library) با Wrapper

چالش اصلی اینجاست که ActiveX برای محیط‌های دارای رابط کاربری (GUI) طراحی شده است. این کنترل‌ها اغلب به یک ترد Single-Threaded Apartment (STA) نیاز دارند که به طور پیش‌فرض در برنامه‌های Windows Forms وجود دارد اما در یک Class Library یا Console App خیر. 😥

راه حل، ساخت یک کلاس پوششی (Wrapper) است. این کلاس وظیفه مدیریت چرخه حیات کنترل ActiveX را در یک ترد مناسب بر عهده می‌گیرد.

گام ۱: آماده‌سازی پروژه

ابتدا یک پروژه Windows Forms ایجاد کنید. اگر کنترل ActiveX شما ۳۲ بیتی است، حتماً پلتفرم پروژه را در تنظیمات Build روی x86 قرار دهید.

گام ۲: افزودن کنترل ActiveX به فرم

1. یک فرم جدید با نام SdkWrapperForm به پروژه اضافه کنید. این فرم میزبان کنترل ActiveX ما خواهد بود.
2. از منوی Tools به Toolbox بروید. راست‌کلیک کرده و Choose Items را انتخاب کنید.
3. به تب COM Components بروید و کنترل ActiveX مورد نظر خود را پیدا و فعال کنید.
4. کنترل جدید به Toolbox اضافه می‌شود. آن را کشیده و روی فرم SdkWrapperForm رها کنید. ویژوال استودیو به طور خودکار دو کتابخانه Interop و AxInterop به پروژه شما اضافه می‌کند.

گام ۳: ایجاد دسترسی به کنترل

کد فرم SdkWrapperForm.cs را باز کرده و یک پراپرتی برای دسترسی عمومی به نمونه ActiveX ایجاد کنید.

public partial class SdkWrapperForm : Form
{
public SdkWrapperForm()
{
InitializeComponent();
}

// این پراپرتی امکان دسترسی به کنترل را از خارج فرم می‌دهد
public AxYourActiveXLib.AxYourActiveXControl SDK
{
get
{
// axYourActiveXControl1 نام نمونه کنترل روی فرم است
return axYourActiveXControl1;
}
}
}

 گام ۴: ساخت کلاس Wrapper اصلی

حالا کلاس اصلی پوششی را با نام `SdkWrapper.cs` ایجاد می‌کنیم. این کلاس یک ترد جدید از نوع `STA` برای میزبانی فرم و کنترل ActiveX ایجاد می‌کند.

csharp
public class SdkWrapper : IDisposable
{
private Thread _uiThread;
private SdkWrapperForm _form;

public SdkWrapper()
{
ManualResetEvent initFinished = new ManualResetEvent(false);

_uiThread = new Thread(() =>
{
_form = new SdkWrapperForm();
// می‌توانید متدهای اولیه کنترل را اینجا فراخوانی کنید
// _form.SDK.SomeInitMethod();
initFinished.Set(); // به ترد اصلی اطلاع می‌دهد که راه‌اندازی تمام شد
Application.Run(); // حلقه پیام ترد را اجرا می‌کند
});

_uiThread.SetApartmentState(ApartmentState.STA); // مهم‌ترین بخش!
_uiThread.IsBackground = true;
_uiThread.Start();
initFinished.WaitOne(); // منتظر می‌مانیم تا ترد آماده شود
}

// متدها و رویدادهای کنترل را اینجا فراخوانی کنید…

public void Dispose()
{
// تمیزکاری منابع در هنگام خروج
if (_uiThread != null)
{
Application.Exit();
_uiThread.Join(); // منتظر می‌مانیم تا ترد کاملا بسته شود
_uiThread = null;
}
}
}
نکته: فراخوانی متد `Dispose` قبل از بستن برنامه اصلی برای آزادسازی منابع الزامی است.

گام ۵: فراخوانی متدها و رویدادها

از آنجایی که کنترل ActiveX در یک ترد دیگر اجرا می‌شود، تمام فراخوانی‌ها باید از طریق `_form.Invoke` انجام شوند تا از خطای Cross-thread جلوگیری شود.

csharp
public class SdkWrapper : IDisposable
{
// … بخش‌های قبلی کلاس …

public string GetVersion()
{
if (_form.InvokeRequired)
{
// فراخوانی متد از یک ترد دیگر
return (string)_form.Invoke(new Func<string>(GetVersion));
}
else
{
// اجرای مستقیم متد در ترد UI
return _form.SDK.GetVersion();
}
}

public void Connect(string address)
{
if (_form.InvokeRequired)
{
_form.Invoke(new Action(() => Connect(address)));
}
else
{
_form.SDK.Connect(address);
}
}

// … متد Dispose
}
اکنون می‌توانید یک نمونه از کلاس `SdkWrapper` را در برنامه کنسول یا کتابخانه خود بسازید و به راحتی از متدهای ActiveX استفاده کنید.

مشکلات رایج و راه‌حل‌ها

هنگام کار با ActiveX در برنامه‌های NET.، ممکن است با خطاهای خاصی مواجه شوید. ⚡️

خطای `System.AccessViolationException`: این خطا اغلب به دلیل مدیریت نادرست منابع مدیریت‌نشده (Unmanaged) رخ می‌دهد. معمولاً زمانی اتفاق می‌افتد که برنامه به طور مکرر اشیاء ActiveX را ایجاد و نابود می‌کند.

خطای `TargetInvocationException`: این خطا نیز می‌تواند ناشی از فراخوانی‌های بین تردی (Cross-thread) نادرست یا مشکلات در چرخه حیات کامپوننت COM باشد.

راه حل کلیدی: برای حل این مشکلات، به جای ایجاد و حذف مداوم اشیاء ActiveX، از الگوی Object Pooling استفاده کنید. یک “استخر” از اشیاء ActiveX ایجاد کنید. برنامه شما قبل از ساخت یک شیء جدید، ابتدا این استخر را بررسی می‌کند. اگر شیء آماده‌ای وجود داشت از آن استفاده می‌کند، در غیر این صورت یک شیء جدید می‌سازد. این کار بار روی سیستم را به شدت کاهش می‌دهد.

ثبت‌نام برای دریافت API و آموزش‌های بیشتر

برای دسترسی به مستندات کامل APIها، دریافت کلیدهای توسعه و مشاهده آموزش‌های ویدیویی پیشرفته، می‌توانید در پنل توسعه‌دهندگان ما ثبت‌نام کنید. فرآیند ثبت‌نام ساده و سریع است.

1. به وبسایت `p.api.ir` مراجعه کنید.
2. فرم ثبت‌نام را با اطلاعات خود تکمیل نمایید.
3. پس از تایید ایمیل، به پنل کاربری خود دسترسی خواهید داشت.

جمع‌بندی

استفاده از ActiveX در برنامه‌های NET.، به خصوص در پروژه‌های غیر گرافیکی، نیازمند دقت و رویکردی صحیح است. با دنبال کردن مراحل این راهنما، از جمله ثبت صحیح کنترل، ایجاد یک کلاس Wrapper برای مدیریت ترد `STA` و فراخوانی امن متدها، می‌توانید به راحتی این تکنولوژی را در پروژه‌های خود ادغام کنید. همچنین، استفاده از الگوی Object Pooling کلید پایداری برنامه شما در بلندمدت خواهد بود. 💡

امیدواریم این مقاله برای شما مفید بوده باشد. آیا تجربه کار با ActiveX در دات‌نت را داشته‌اید؟ چالش‌ها و راه‌حل‌های خود را در بخش نظرات با ما و دیگران به اشتراک بگذارید.

• برچسب ها:
• ActiveX در برنامه های net.
• api