در آموزش ساخت پروژهٔ Windows Forms با C#، ظاهر برنامهٔ «فهرست نام‌ها» رو آماده کردیم. حالا می‌خوایم با کلیک روی دکمه، نام واردشده به فهرست اضافه بشه.

بعد از تکمیل برنامه، اجرای بدون دیباگر و اجرای همراه دیباگر رو امتحان می‌کنیم و با یک Breakpoint، رفتار کد رو قدم‌به‌قدم می‌بینیم.

قبل از شروع، پروژه رو آماده کنید

این آموزش ادامهٔ همان پروژهٔ Names با Visual Studio 2026 و .NET 10 LTS است.

پروژه رو باز کنید و مطمئن بشید این سه کنترل روی فرم قرار دارن:

• کادر ورود نام با ویژگی (Name) برابر txtName
• دکمهٔ افزودن نام با ویژگی (Name) برابر btnAdd
• فهرست نام‌ها با ویژگی (Name) برابر lstNames

این نام‌ها با نوشته‌ای که کاربر روی فرم می‌بینه فرق دارن. برای مثال، نام دکمه در کد btnAdd است، ولی متن روی اون می‌تونه «افزودن نام» باشه.

مرحلهٔ اول: رویداد کلیک دکمه رو بسازید

در محیط Designer، روی دکمهٔ «افزودن نام» کلیک کنید.

پنجرهٔ Properties رو باز کنید و روی علامت رعدوبرق، یعنی Events، بزنید.

رویداد Click رو پیدا کنید و داخل خانهٔ روبه‌روی اون دابل‌کلیک کنید.

Visual Studio معمولاً متدی با نام btnAdd_Click در فایل Form1.cs می‌سازه و اتصال دکمه به این متد رو هم انجام می‌ده.

نتیجهٔ موردانتظار: ویرایشگر کد باز می‌شه و داخل متدی قرار می‌گیرید که هنگام کلیک روی دکمه اجرا خواهد شد.

اگر از قبل برای Click متدی ساخته‌اید، همان متد باز می‌شه؛ متد جدید و تکراری نسازید.

مرحلهٔ دوم: کد افزودن نام رو بنویسید

کد متد رو به شکل زیر تکمیل کنید:

private void btnAdd_Click(object? sender, EventArgs e)
{
    string name = txtName.Text.Trim();

    if (string.IsNullOrWhiteSpace(name))
    {
        MessageBox.Show("لطفاً یک نام وارد کنید.");
        txtName.Focus();
        return;
    }

    if (lstNames.Items.Contains(name))
    {
        MessageBox.Show("این نام قبلاً اضافه شده.");
        txtName.Focus();
        return;
    }

    lstNames.Items.Add(name);
    txtName.Clear();
    txtName.Focus();
}

اگر Visual Studio متد رو از قبل ساخته، فقط دستورهای داخل آکولادها رو در همان متد قرار بدید. کل متد رو داخل متد موجود نچسبونید.

این کد باید در Form1.cs قرار بگیره. برای این تمرین، فایل Form1.Designer.cs رو دستی تغییر ندید.

این کد چه کاری انجام می‌ده؟

دستور string name = txtName.Text.Trim(); متن کادر ورودی رو می‌خونه و فاصله‌های ابتدا و انتهای اون رو حذف می‌کنه.

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

دستور return اجرای همین متد رو در همان نقطه تمام می‌کنه؛ بنابراین نام خالی به فهرست اضافه نمی‌شه.

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

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

اگر هر دو بررسی موفق باشن، دستور lstNames.Items.Add(name); نام رو اضافه می‌کنه.

در پایان، Clear کادر ورودی رو خالی می‌کنه و Focus مکان‌نما رو به اون برمی‌گردونه تا نام بعدی رو بنویسید.

مرحلهٔ سوم: برنامه رو بدون دیباگر اجرا کنید

از منوی File > Save All پروژه رو ذخیره کنید.

بعد از منوی Debug > Start Without Debugging استفاده کنید یا کلیدهای Ctrl+F5 رو بزنید.

Visual Studio پروژه رو Build می‌کنه و اگر خطای ساخت وجود نداشته باشه، پنجرهٔ برنامه باز می‌شه.

نتیجهٔ موردانتظار: فرم «فهرست نام‌ها» رو می‌بینید و می‌تونید با کادر ورودی و دکمه کار کنید.

این پنجره، برنامهٔ در حال اجراست. Designer محیط چیدن اجزای فرم بود.

رفتار برنامه رو امتحان کنید

ابتدا «علی» رو وارد کنید و روی «افزودن نام» بزنید.

باید «علی» داخل فهرست دیده بشه، کادر ورودی خالی بشه و مکان‌نما به کادر برگرده.

دوباره «علی» رو وارد کنید. باید پیام تکراری‌بودن نمایش داده بشه و مورد جدیدی به فهرست اضافه نشه.

حالا کادر رو خالی کنید یا فقط چند فاصله وارد کنید. باید پیام درخواست نام نمایش داده بشه.

برای ادامهٔ آموزش، پنجرهٔ برنامه رو ببندید.

تفاوت F5 و Ctrl+F5 چیه؟

Ctrl+F5 برنامه رو بدون اتصال دیباگر اجرا می‌کنه. برای امتحان‌کردن رفتار عادی برنامه مناسبه.

F5 برنامه رو همراه دیباگر اجرا می‌کنه. در این حالت می‌تونیم اجرای کد رو در نقطه‌ای مشخص متوقف کنیم و مقدار متغیرها رو ببینیم.

صرف اجرای برنامه، به معنی انجام اشکال‌زدایی نیست. دیباگر ابزاریه که برای بررسی رفتار برنامه ازش استفاده می‌کنیم.

در نوار ابزار هم حالت Debug رو نگه دارید. انتخاب پیکربندی Debug با متصل‌بودن دیباگر دو موضوع جداست؛ حتی با پیکربندی Debug می‌تونید از Ctrl+F5 استفاده کنید.

مرحلهٔ چهارم: یک Breakpoint قرار بدید

در Form1.cs، خط string name = txtName.Text.Trim(); رو پیدا کنید.

روی حاشیهٔ سمت چپ همان خط کلیک کنید تا یک دایرهٔ قرمز ظاهر بشه. این علامت، Breakpoint یا نقطهٔ توقف است.

حالا F5 رو بزنید.

بعد از بازشدن برنامه، یک نام وارد کنید و روی دکمه بزنید.

نتیجهٔ موردانتظار: Visual Studio اجرای برنامه رو در خط مشخص‌شده متوقف می‌کنه.

خطی که به‌عنوان محل فعلی اجرا مشخص شده، هنوز اجرا نشده. بنابراین در این لحظه، مقداردهی متغیر name هنوز انجام نشده است.

مرحلهٔ پنجم: کد رو قدم‌به‌قدم بررسی کنید

در همان حالت توقف، F10 رو بزنید تا دستور مقداردهی اجرا بشه.

حالا نشانگر ماوس رو روی متغیر name نگه دارید. باید مقدار نام واردشده رو ببینید.

با زدن دوبارهٔ F10، بررسی شرط‌ها رو دنبال کنید.

اگر نام معتبر و غیرتکراری باشه، مسیر اجرا به خط lstNames.Items.Add(name); می‌رسه.

با F10، این دستور هم اجرا می‌شه. برای برگشتن به ادامهٔ عادی برنامه، F5 رو بزنید.

وقتی برنامه در Breakpoint متوقفه، فرم ممکنه به کلیک‌ها پاسخ نده؛ در این مثال، اجرای کد رابط کاربری متوقف شده است.

برای حذف Breakpoint، دوباره روی دایرهٔ قرمز کلیک کنید.

چطور اجرای برنامه رو متوقف کنیم؟

در اجرای بدون دیباگر، پنجرهٔ اصلی برنامه رو با دکمهٔ ضربدر ببندید.

در اجرای همراه دیباگر، می‌تونید از Debug > Stop Debugging یا میان‌بر Shift+F5 استفاده کنید.

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

خطاهای رایج این مرحله

روی دکمه کلیک می‌کنم، اما اتفاقی نمی‌افته

در Designer، دکمه رو انتخاب کنید و در Properties > Events بررسی کنید که روبه‌روی Click، نام btnAdd_Click قرار گرفته باشه.

صرف نوشتن یک متد با این نام، اتصال اون به رویداد دکمه رو ایجاد نمی‌کنه.

زیر txtName یا lstNames خط قرمز دیده می‌شه

ویژگی (Name) کنترل‌ها رو بررسی کنید. نام داخل کد باید دقیقاً با نام کنترل برابر باشه.

مطمئن بشید کد رو داخل کلاس فرم در فایل Form1.cs نوشته‌اید.

برنامه Build نمی‌شه

از مسیر View > Error List خطاها رو ببینید.

اگر پیشنهاد اجرای آخرین نسخهٔ موفق برنامه نمایش داده شد، برای بررسی تغییر جدید، اول خطای Build رو برطرف کنید؛ نسخهٔ قبلی ممکنه کد جدید شما رو نداشته باشه.

Breakpoint فعال نمی‌شه

مطمئن بشید برنامه رو با F5 اجرا کرده‌اید و بعد روی دکمه کلیک کرده‌اید.

اگر دایرهٔ Breakpoint توخالیه یا علامت هشدار داره، نشانگر رو روی اون نگه دارید و پیام Visual Studio رو بخونید.

پروژهٔ اشتباهی اجرا می‌شه

اگر Solution چند پروژه داره، روی پروژهٔ Names راست‌کلیک کنید و Set as Startup Project رو انتخاب کنید.

اگر پروژهٔ قدیمی .NET Framework داریم چی؟

مسیر اصلی این آموزش، .NET 10 است. در پروژه‌های قدیمی Windows Forms، مفهوم رویداد Click و دستورهای اصلی این نمونه مشابه‌اند، اما ساختار پروژه و کدهای تولیدشده ممکنه فرق داشته باشن.

برای اضافه‌کردن این رفتار، امضای متدی که Designer پروژهٔ خودتون ساخته رو حفظ کنید و فقط دستورهای داخل متد رو منتقل کنید. در پروژه‌های قدیمی ممکنه پارامتر اول object sender باشه و علامت ? نداشته باشه.

فایل Program.cs یا تنظیمات پروژهٔ قدیمی رو با نمونهٔ پروژهٔ جدید جایگزین نکنید.

تمرین کوتاه

این سه آزمایش رو انجام بدید:

1. نام «سارا» رو یک بار با چند فاصله در ابتدا و انتها و یک بار بدون فاصله وارد کنید. آیا مورد تکراری اضافه می‌شه؟
2. روی خط lstNames.Items.Add(name) یک Breakpoint بذارید. یک نام خالی وارد کنید. آیا اجرا به این خط می‌رسه؟
3. پیام مربوط به نام تکراری رو تغییر بدید، برنامه رو دوباره اجرا کنید و نتیجه رو ببینید.

بعد از تمرین، Breakpointها رو بردارید و یک بار برنامه رو با Ctrl+F5 اجرا کنید.

ادامهٔ یادگیری C#

حالا یک فرم دارید که ورودی رو می‌خونه، بررسی می‌کنه و نتیجه رو نشان می‌ده. همچنین می‌تونید مسیر اجرای کد رو با دیباگر دنبال کنید.