تبدیل JSON به API در سی شارپ

اگر قصد دارید داده‌های یک سرویس وب را در برنامه خود استفاده کنید، باید با تبدیل JSON به API در سی شارپ آشنا باشید. امروزه بیشتر APIها داده را در قالب JSON برمی‌گردانند. این فرمت سبک، سریع و خوانا است. به همین دلیل در پروژه‌های #C، وب‌اپلیکیشن‌ها و حتی برنامه‌های دسکتاپ، استفاده گسترده‌ای دارد. 🚀

در این مقاله، روش درست و به‌روز کار با JSON در سی شارپ را بررسی می‌کنیم. همچنین می‌بینید چگونه با استفاده از HttpClient و کتابخانه Newtonsoft.Json داده را از یک API دریافت و به آبجکت‌های قابل استفاده تبدیل کنید. هدف این آموزش، فقط نمایش کد نیست. هدف، ساخت یک مسیر عملی و قابل استفاده برای پروژه‌های واقعی است. ✅

در ادامه، یک سناریوی ساده را پیاده‌سازی می‌کنیم. کاربر نام یک شهر را وارد می‌کند و برنامه، مختصات جغرافیایی آن را از API دریافت می‌کند. این مثال، پایه‌ای عالی برای درک ارتباط بین JSON، API و مدل‌سازی داده در C# است.

JSON در سی شارپ چیست؟

JSON مخفف JavaScript Object Notation است. این فرمت برای تبادل داده بین سیستم‌ها استفاده می‌شود. JSON ساختاری سبک دارد و برای انسان و ماشین خوانا است.

در سی شارپ، JSON معمولاً در این مراحل استفاده می‌شود:

دریافت داده از API
تبدیل متن JSON به کلاس‌های C#
استخراج ویژگی‌ها و مقادیر
نمایش یا پردازش اطلاعات در برنامه

بیشتر APIهای مدرن به‌جای XML از JSON استفاده می‌کنند. دلیل آن هم ساده است: JSON سریع‌تر، سبک‌تر و پیاده‌سازی آن آسان‌تر است. 📌

چرا تبدیل JSON به API در سی شارپ مهم است؟

وقتی از API استفاده می‌کنید، داده‌ها معمولاً به‌صورت خام برمی‌گردند. این داده خام برای استفاده مستقیم مناسب نیست. شما باید آن را به کلاس‌ها و اشیای قابل فهم در C# تبدیل کنید.

مزیت‌ها

⚡ سرعت توسعه بیشتر: داده‌ها سریع‌تر در برنامه استفاده می‌شوند.
🔍 خوانایی بهتر کد: ساختار JSON به کلاس‌های واضح تبدیل می‌شود.
🛠️ نگهداری آسان‌تر: تغییرات API راحت‌تر مدیریت می‌شود.
📦 توسعه‌پذیری بالا: می‌توانید ویژگی‌های جدید را سریع اضافه کنید.
✅ کاهش خطا: استفاده از مدل‌های مشخص، احتمال خطای پردازش را کم می‌کند.

کاربردهای تبدیل JSON به API در C#

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

کاربردها

🌍 دریافت اطلاعات آب‌وهوا از سرویس‌های خارجی
📍 دریافت مختصات شهرها و مکان‌ها
🛒 اتصال به API فروشگاه و محصولات
👤 دریافت اطلاعات کاربران از سرویس‌های احراز هویت
💳 ارتباط با درگاه‌های پرداخت
📊 ساخت داشبوردهای تحلیلی با داده‌های زنده

اگر با وب‌سرویس‌ها کار می‌کنید، این مهارت برای شما ضروری است. 💡

پیش‌نیازهای پیاده‌سازی

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

نصب Visual Studio
ایجاد یک پروژه Windows Forms یا Console App
آشنایی اولیه با کلاس و شیء در سی شارپ
نصب پکیج Newtonsoft.Json
دسترسی به یک API که خروجی JSON داشته باشد

ساخت پروژه برای دریافت JSON

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

اجزای فرم

اگر از Windows Forms استفاده می‌کنید، این کنترل‌ها را بسازید:

یک TextBox با نام txbx_City
یک Button برای ارسال درخواست
دو Label با نام‌های lbl_latitude و lbl_longitude

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

نمونه JSON دریافتی از API

یک API مکان‌یابی ممکن است خروجی مشابه زیر برگرداند:

json

{
  "results": [
    {
      "formatted_address": "Lahore, Pakistan",
      "geometry": {
        "location": {
          "lat": 31.55460609999999,
          "lng": 74.35715810000001
        }
      }
    }
  ],
  "status": "OK"
}

این ساختار نشان می‌دهد که طول و عرض جغرافیایی در مسیر زیر قرار دارد:

results[0].geometry.location.lat
results[0].geometry.location.lng

تبدیل JSON به کلاس در سی شارپ

برای استفاده راحت‌تر، باید JSON را به کلاس تبدیل کنید. در گذشته معمولاً از ابزارهای آنلاین مثل Json2CSharp استفاده می‌شد. هنوز هم این ابزارها مفید هستند. اما بهتر است ساختار کلاس‌ها را بشناسید و درک کنید.

نمونه کلاس‌ها

csharp

public class Location
{
    public double lat { get; set; }
    public double lng { get; set; }
}

public class Geometry
{
    public Location location { get; set; }
}

public class Result
{
    public string formatted_address { get; set; }
    public Geometry geometry { get; set; }
}

public class Root
{
    public List<Result> results { get; set; }
    public string status { get; set; }
}

این مدل‌ها به شما کمک می‌کنند داده را مستقیم به شیء تبدیل کنید. این روش بسیار تمیزتر از پردازش دستی متن JSON است. 🧩

نصب Newtonsoft.Json

برای Deserialize کردن JSON، یکی از محبوب‌ترین گزینه‌ها Newtonsoft.Json است.

مراحل نصب

وارد Solution Explorer شوید.
روی پروژه کلیک راست کنید.
گزینه Manage NuGet Packages را بزنید.
عبارت Newtonsoft.Json را جستجو کنید.
پکیج را نصب کنید.

بعد از نصب، این namespace را اضافه کنید:

csharp

using Newtonsoft.Json;

دریافت داده از API با HttpClient

اکنون به بخش اصلی می‌رسیم. برای ارسال درخواست به API از HttpClient استفاده می‌کنیم.

نمونه کد

csharp

using Newtonsoft.Json;
using System.Net.Http;

private async void button1_Click(object sender, EventArgs e)
{
    string cityName = txbx_City.Text.Trim();

    if (string.IsNullOrEmpty(cityName))
    {
        MessageBox.Show("لطفاً نام شهر را وارد کنید.");
        return;
    }

    string url = $"https://example.com/api/geocode?city={cityName}";

    using (HttpClient client = new HttpClient())
    {
        HttpResponseMessage response = await client.GetAsync(url);

        if (response.IsSuccessStatusCode)
        {
            string jsonResult = await response.Content.ReadAsStringAsync();
            Root data = JsonConvert.DeserializeObject<Root>(jsonResult);

            if (data != null && data.results != null && data.results.Count > 0)
            {
                lbl_latitude.Text = data.results[0].geometry.location.lat.ToString();
                lbl_longitude.Text = data.results[0].geometry.location.lng.ToString();
            }
            else
            {
                MessageBox.Show("داده‌ای یافت نشد.");
            }
        }
        else
        {
            MessageBox.Show("خطا در دریافت اطلاعات از API.");
        }
    }
}

این کد، ساختار پایه برای کار با API در سی شارپ است. شما می‌توانید آن را برای صدها سناریوی دیگر توسعه دهید. 🔧

نکات مهم در پیاده‌سازی

برای اینکه کد شما حرفه‌ای‌تر شود، این نکات را رعایت کنید:

مدیریت خطا

از try-catch استفاده کنید.
خطاهای شبکه را جداگانه مدیریت کنید.
اگر API نیاز به احراز هویت دارد، توکن را امن نگه دارید.

اعتبارسنجی ورودی

ورودی کاربر را بررسی کنید.
از ارسال داده خالی یا نامعتبر جلوگیری کنید.

بهینه‌سازی ساختار کلاس‌ها

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

بخش ثبت‌نام و شروع استفاده

اگر می‌خواهید سریع‌تر وارد فرایند استفاده از API شوید، بهتر است ابتدا ثبت‌نام خود را انجام دهید. روند ثبت‌نام معمولاً ساده است و در چند مرحله انجام می‌شود. ✍️

مراحل ثبت‌نام

📝 ورود به صفحه ثبت‌نام از طریق لینک: p.api.ir
📧 وارد کردن اطلاعات اولیه و ایمیل
🔐 تعیین رمز عبور امن
✅ تأیید حساب کاربری
🚀 دریافت دسترسی و شروع استفاده از APIها

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

تبدیل JSON به API در سی شارپ یکی از مهم‌ترین مهارت‌ها برای توسعه‌دهندگان C# است. با کمک HttpClient و Newtonsoft.Json می‌توانید داده را از هر API دریافت کرده و به‌سادگی در برنامه خود استفاده کنید. اگر ساختار JSON را درست مدل‌سازی کنید، توسعه پروژه سریع‌تر، تمیزتر و قابل نگهداری‌تر می‌شود.

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

نظر شما چیست؟

اگر دوست دارید، می‌توانم در مرحله بعد همین مقاله را با کد کامل و اجرایی Windows Forms یا ASP.NET Core هم برایتان آماده کنم. همچنین می‌توانید مقاله‌های مرتبط را بخوانید یا تجربه خود را در بخش نظرات بنویسید.