العودة إلى المدونة

واجهة برمجة أسعار الصرف بلغة C# / .NET — دليل تكامل شامل (2026)

V
Vlado Grigirov
May 26, 2026
C# .NET Currency API Exchange Rates Tutorial Fintech ASP.NET Core

إذا كنت تبني خلفية مدفوعات أو محرّك فوترة لمنتج SaaS أو خدمة تسعير مؤسسية على منصة مايكروسوفت، فإن دمج واجهة برمجة أسعار الصرف في C# / .NET هو أحد أعلى المهام مردوداً التي يمكنك تسليمها هذا الأسبوع. تقدّم لك منصة .NET الحديثة كل ما تحتاج جاهزاً — HttpClient وIHttpClientFactory وSystem.Text.Json وIMemoryCache وحقن تبعيات من الدرجة الأولى — ومع ذلك لا تزال معظم الشروحات تعرض مقطعاً واحداً من WebClient.DownloadString لا يمكن أن يجتاز أي مراجعة كود إنتاج. هذا الدليل ينقلك من أول طلب وصولاً إلى عميل مكتوب بأنواع صارمة، مخزن مؤقتاً، ومرن، يمكن إسقاطه في ASP.NET Core أو تطبيق Blazor أو أداة سطح مكتب WPF أو Azure Function.

بنهاية هذا الدليل سيكون لديك عميل Finexly قابل لإعادة الاستخدام لـتوثيق واجهة Finexly، ومحوّل عملات صغير لسطر الأوامر، و ASP.NET Core Minimal API يقدّم أسعار الصرف اللحظية لبقية منصتك — كل ذلك مكتوب بأسلوب اصطلاحي في .NET 8 / .NET 9 وفق الأنماط التي توصي بها مايكروسوفت نفسها.

لماذا C# / .NET خيار قوي لتكاملات العملات

تحويل العملات في الإنتاج هو في الغالب مسألة إدخال/إخراج: جلب الأسعار، تخزينها مؤقتاً، ضرب بعض الأعداد العشرية، إعادة JSON. تم تحسين بيئة تشغيل .NET على وجه التحديد لهذا النوع من الأعباء طوال العقد الماضي:

  • IHttpClientFactory يحل مشكلة استنفاد المقابس. يقوم بتجميع نُسخ HttpMessageHandler كي تستطيع حقن HttpClient في كل مكان دون تسريب مقابس — وهو أكبر مصدر للأعطال المتقطعة في واجهات أسعار الصرف الذي نراه في الكود القديم بـ .NET.
  • System.Text.Json سريع وقليل التخصيص. يفك تسلسل استجابة نموذجية فيها 170 عملة في أقل بكثير من مليثانية، دون أي مكتبة طرف ثالث.
  • decimal مدمج في اللغة. لا تحتاج أبداً إلى BigDecimal خارجي للتعامل مع المال بشكل صحيح — وهذا مهم عندما تجمع آلاف بنود فاتورة محوّلة.
  • Polly هو مكتبة المرونة الفعلية. إعادة المحاولة، قاطع الدائرة، والمهل تحتاج إلى استدعاء واحد لـ AddPolicyHandler.
  • Minimal API و AOT. أصبح من الواقعي إطلاق خدمة مصغّرة لأسعار الصرف في 30 سطراً، مع بدء بارد بالميلي ثانية.

إذا كنت تقارن بين منصات تطوير، فلدينا أدلة موازية لـ Node.js وPython وGo وPHP. هذا المقال خاص بـ C# ويفترض ارتياحك مع async/await و Generic Hosting وحقن التبعيات.

المتطلبات وإعداد المشروع

تحتاج إلى .NET 8 أو .NET 9 مثبتاً. تحقق من إصدار SDK:

dotnet --version

أنشئ حلاً جديداً يضم مكتبة فئات للعميل وتطبيق سطر أوامر لتجربته:

mkdir Finexly.Sample && cd Finexly.Sample
dotnet new sln -n Finexly.Sample
dotnet new classlib -n Finexly.Client
dotnet new console   -n Finexly.ConsoleApp
dotnet sln add Finexly.Client/Finexly.Client.csproj
dotnet sln add Finexly.ConsoleApp/Finexly.ConsoleApp.csproj
dotnet add Finexly.ConsoleApp/Finexly.ConsoleApp.csproj reference Finexly.Client/Finexly.Client.csproj

تحتاج أيضاً إلى مفتاح Finexly API. سجل مجاناً — دون بطاقة ائتمان، وتأتي الباقة المجانية بـ 1000 طلب شهرياً، وهي أكثر من كافية للتطوير و CI.

لا تضع المفتاح أبداً في الكود مباشرة. خزّنه كمتغير بيئة:

# macOS / Linux
export FINEXLY_API_KEY="your_api_key_here"
# Windows PowerShell
$env:FINEXLY_API_KEY = "your_api_key_here"

في الإنتاج، خزّنه في Azure Key Vault أو AWS Secrets Manager أو dotnet user-secrets للتطوير المحلي.

أول طلب مع HttpClient

لنبدأ بأبسط مثال يعمل. افتح Finexly.ConsoleApp/Program.cs:

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

var apiKey = Environment.GetEnvironmentVariable("FINEXLY_API_KEY")
    ?? throw new InvalidOperationException("FINEXLY_API_KEY not set");

using var http = new HttpClient
{
    BaseAddress = new Uri("https://api.finexly.com/v1/")
};

var url = $"latest?base=USD&apikey={apiKey}";
var payload = await http.GetFromJsonAsync<Dictionary<string, object>>(url);

Console.WriteLine(payload?["rates"]);

شغّله:

dotnet run --project Finexly.ConsoleApp

ستظهر لك قاموس برموز العملات وأسعارها مقابل USD. هذا يعمل، لكنه يحمل كل العيوب المتوقعة من مثال 10 أسطر: قيم object بلا أنواع، لا تخزين مؤقت، لا إعادة محاولة، إنشاء يدوي لـ HttpClient، ومفتاح API في الرابط. لنصلح كل ذلك.

تعريف نماذج استجابة بأنواع صارمة

System.Text.Json يفك التسلسل بشكل نظيف إلى أنواع record في C#. في مشروع Finexly.Client، أنشئ Models/LatestRatesResponse.cs:

using System.Text.Json.Serialization;

namespace Finexly.Client.Models;

public sealed record LatestRatesResponse(
    [property: JsonPropertyName("base")] string Base,
    [property: JsonPropertyName("date")] DateOnly Date,
    [property: JsonPropertyName("rates")] IReadOnlyDictionary<string, decimal> Rates
);

تفاصيل تستحق الانتباه:

  • decimal بدلاً من double. خطأ الفاصلة العائمة غير مقبول للنقود. decimal يمنحك 28–29 خانة دقيقة وحساباً عشرياً مضبوطاً.
  • IReadOnlyDictionary. الاستجابة للقراءة فقط — عبّر عن ذلك في النوع.
  • DateOnly. يقدّم .NET الحديث نوع تاريخ مناسب. استخدمه بدلاً من DateTime عندما لا يوجد مكوّن زمن.

الآن نستطيع فك التسلسل دون الحاجة إلى ألاعيب dynamic أو Dictionary<string, object>.

بناء HttpClient ذي نوع باستخدام IHttpClientFactory

النمط الموصى به في .NET هو عميل ذو نوع مسجّل عبر IHttpClientFactory. يمنحك تجميع الاتصالات، ومعالجات قابلة للضبط، وحقن تبعيات سهل. أنشئ FinexlyClient.cs في مشروع Finexly.Client:

using System.Net.Http.Json;
using Finexly.Client.Models;

namespace Finexly.Client;

public sealed class FinexlyClient
{
    private readonly HttpClient _http;
    private readonly string _apiKey;

    public FinexlyClient(HttpClient http, FinexlyOptions options)
    {
        _http = http;
        _apiKey = options.ApiKey;
        _http.BaseAddress = new Uri("https://api.finexly.com/v1/");
        _http.DefaultRequestHeaders.Add("X-Api-Key", _apiKey);
        _http.Timeout = TimeSpan.FromSeconds(5);
    }

    public async Task<LatestRatesResponse> GetLatestRatesAsync(
        string baseCurrency = "USD",
        IEnumerable<string>? symbols = null,
        CancellationToken cancellationToken = default)
    {
        var query = $"latest?base={baseCurrency}";
        if (symbols is not null)
        {
            query += $"&symbols={string.Join(",", symbols)}";
        }

        var response = await _http.GetFromJsonAsync<LatestRatesResponse>(
            query, cancellationToken);

        return response
            ?? throw new InvalidOperationException("Empty response from Finexly");
    }

    public async Task<decimal> ConvertAsync(
        string from, string to, decimal amount,
        CancellationToken cancellationToken = default)
    {
        var rates = await GetLatestRatesAsync(from, new[] { to }, cancellationToken);
        if (!rates.Rates.TryGetValue(to, out var rate))
        {
            throw new ArgumentException($"Unknown currency: {to}");
        }
        return amount * rate;
    }
}

public sealed class FinexlyOptions
{
    public required string ApiKey { get; init; }
}

نقاط تستحق الإشارة:

  • يذهب المفتاح في هيدر وليس في الرابط — أكثر أماناً للسجلات والوكلاء والتتبع.
  • مهلة Timeout مدتها 5 ثوان تمنع واجهة عملات معلّقة من إبطاء صفحة الدفع.
  • يقبل العميل CancellationToken في كل دالة — هذا غير قابل للتفاوض في ASP.NET الحديث.
  • يستخدم GetFromJsonAsync<T> الذي يجمع GET والتحقق من الحالة وفك التسلسل في استدعاء واحد قليل التخصيصات.

تسجيل العميل في حقن التبعيات

في Program.cs (Console أو ASP.NET Core أو Worker — نفس واجهة الاستخدام في كل مكان):

using Finexly.Client;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton(new FinexlyOptions
{
    ApiKey = Environment.GetEnvironmentVariable("FINEXLY_API_KEY")!
});

builder.Services.AddHttpClient<FinexlyClient>();

using var host = builder.Build();

var finexly = host.Services.GetRequiredService<FinexlyClient>();
var eur = await finexly.ConvertAsync("USD", "EUR", 100m);
Console.WriteLine($"100 USD = {eur:0.00} EUR");

AddHttpClient<FinexlyClient>() يسجّل FinexlyClient كخدمة عابرة (transient) ويزوّده بـ HttpClient مجمّع من المصنع. تستطيع الآن حقن FinexlyClient في أي كنترولر أو Minimal API أو خدمة خلفية.

إضافة إعادة المحاولة وقاطع الدائرة عبر Polly

أحياناً تفقد الواجهات الخارجية طلباً أو تتحكم بالمعدّل أو تختنق على مستوى الشبكة. Polly هي المكتبة المعيارية للمرونة في .NET وتتكامل مع IHttpClientFactory في سطرين.

ثبّت الحزمة:

dotnet add Finexly.ConsoleApp package Microsoft.Extensions.Http.Polly

اضبط إعادة محاولة بتراجع أسي وقاطع دائرة:

using Polly;
using Polly.Extensions.Http;

builder.Services.AddHttpClient<FinexlyClient>()
    .AddPolicyHandler(HttpPolicyExtensions
        .HandleTransientHttpError()
        .OrResult(r => (int)r.StatusCode == 429)
        .WaitAndRetryAsync(
            retryCount: 3,
            sleepDurationProvider: attempt =>
                TimeSpan.FromMilliseconds(200 * Math.Pow(2, attempt))))
    .AddPolicyHandler(HttpPolicyExtensions
        .HandleTransientHttpError()
        .CircuitBreakerAsync(
            handledEventsAllowedBeforeBreaking: 5,
            durationOfBreak: TimeSpan.FromSeconds(30)));

هذا التسجيل الواحد يعيد المحاولة على 5xx و 408 و 429 بتراجع أسي (200 و 400 و 800 مللي ثانية)، ويفعّل قاطع الدائرة إذا توقفت الواجهة كلياً — فتدهور صفحة الدفع بأسلوب لائق بدل احتجاز اتصالات لدقائق.

تخزين الاستجابات مؤقتاً بـ IMemoryCache

نادراً ما تتغيّر أسعار الصرف اللحظية أكثر من مرة في الدقيقة، لذا غالباً ما يقلّص تخزين مؤقت داخلي صغير الاتصالات الصاعدة بنسبة 95% أو أكثر. يأتي IMemoryCache ضمن .NET افتراضياً.

dotnet add Finexly.Client package Microsoft.Extensions.Caching.Memory

أنشئ CachedFinexlyClient.cs:

using Finexly.Client.Models;
using Microsoft.Extensions.Caching.Memory;

namespace Finexly.Client;

public sealed class CachedFinexlyClient
{
    private readonly FinexlyClient _inner;
    private readonly IMemoryCache _cache;
    private static readonly TimeSpan DefaultTtl = TimeSpan.FromSeconds(60);

    public CachedFinexlyClient(FinexlyClient inner, IMemoryCache cache)
    {
        _inner = inner;
        _cache = cache;
    }

    public Task<LatestRatesResponse> GetLatestRatesAsync(
        string baseCurrency,
        CancellationToken cancellationToken = default)
    {
        var key = $"finexly:latest:{baseCurrency}";

        return _cache.GetOrCreateAsync(key, entry =>
        {
            entry.AbsoluteExpirationRelativeToNow = DefaultTtl;
            return _inner.GetLatestRatesAsync(baseCurrency,
                cancellationToken: cancellationToken);
        })!;
    }
}

سجّله مع IMemoryCache:

builder.Services.AddMemoryCache();
builder.Services.AddSingleton<CachedFinexlyClient>();

TTL بمقدار 60 ثانية افتراضي ممتاز لأسعار الدفع ومعاينات الفوترة ولوحات الإدارة. للبيانات التاريخية، ارفع TTL إلى ساعات أو أيام — الأسعار التاريخية لا تتغيّر.

محوّل عملات لسطر الأوامر يعمل فعلاً

بدمج كل شيء، يصبح لدينا أداة CLI صغيرة تعمل مثل currencyconverter --amount 100 --from USD --to JPY:

using Finexly.Client;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddMemoryCache();
builder.Services.AddSingleton(new FinexlyOptions
{
    ApiKey = Environment.GetEnvironmentVariable("FINEXLY_API_KEY")!
});
builder.Services.AddHttpClient<FinexlyClient>();
builder.Services.AddSingleton<CachedFinexlyClient>();

using var host = builder.Build();

decimal amount = 1m;
string from = "USD", to = "EUR";

for (int i = 0; i < args.Length - 1; i++)
{
    switch (args[i])
    {
        case "--amount": amount = decimal.Parse(args[i + 1]); break;
        case "--from":   from   = args[i + 1].ToUpperInvariant(); break;
        case "--to":     to     = args[i + 1].ToUpperInvariant(); break;
    }
}

var finexly = host.Services.GetRequiredService<CachedFinexlyClient>();
var rates   = await finexly.GetLatestRatesAsync(from);

if (!rates.Rates.TryGetValue(to, out var rate))
{
    Console.Error.WriteLine($"Unknown currency: {to}");
    return 1;
}

Console.WriteLine($"{amount:0.00} {from} = {amount * rate:0.00} {to}");
return 0;

ابنِ ثنائياً بملف واحد يصلح لأي خادم:

dotnet publish Finexly.ConsoleApp -c Release -r linux-x64 \
  --self-contained -p:PublishSingleFile=true

كشف الأسعار عبر ASP.NET Core Minimal API

بالنسبة لمعظم الفرق، البنية الصحيحة هي خدمة مصغّرة داخلية للأسعار تغلّف الواجهة المنبع، وتضيف التخزين المؤقت، وتمنح كل الخدمات الأخرى نقطة وصول سريعة ومجانية داخل VPC. مع Minimal API في ASP.NET Core يصبح ذلك ملفاً من 30 سطراً:

using Finexly.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMemoryCache();
builder.Services.AddSingleton(new FinexlyOptions
{
    ApiKey = builder.Configuration["Finexly:ApiKey"]!
});
builder.Services.AddHttpClient<FinexlyClient>();
builder.Services.AddSingleton<CachedFinexlyClient>();

var app = builder.Build();

app.MapGet("/rates", async (
    string? @base,
    CachedFinexlyClient finexly,
    CancellationToken ct) =>
{
    var rates = await finexly.GetLatestRatesAsync(@base ?? "USD", ct);
    return Results.Ok(rates);
});

app.MapGet("/convert", async (
    string from, string to, decimal amount,
    CachedFinexlyClient finexly,
    CancellationToken ct) =>
{
    var rates = await finexly.GetLatestRatesAsync(from, ct);
    return rates.Rates.TryGetValue(to, out var rate)
        ? Results.Ok(new { from, to, amount, converted = amount * rate })
        : Results.NotFound(new { error = $"Unknown currency {to}" });
});

app.Run();

انشر هذا خلف بوابة API المعتادة، وستستطيع أي خدمة لديك استدعاء GET /convert?from=USD&to=EUR&amount=99.95 بزمن استجابة أقل من 10 مللي ثانية عند نجاح التخزين المؤقت. للتجربة على المتصفح، البيانات نفسها متوفرة في محوّل العملات المستضاف لدينا.

التعامل مع المال في C# بطريقة صحيحة

أنماط دفاعية تسدّد كلفتها من أول مراجعة لدفتر المدفوعات:

  • استخدم decimal دائماً، ولا تستخدم double أو float أبداً. من المعروف أن 0.1 + 0.2 لا تساوي 0.3 في الفاصلة العائمة — وهذا الخطأ الواحد في التقريب قد يكلّفك نزاع رد مبالغ.
  • قرّب عند العرض لا عند الحساب. احتفظ بالدقة الكاملة عبر كل ضرب، ولا تستخدم Math.Round(value, 2, MidpointRounding.ToEven) إلا عند العرض أو الحفظ.
  • حدّد وضع التقريب. التقريب المصرفي (ToEven) هو الافتراضي في الصناعة المالية ضمن IEEE 754 و ISO 80000-1.
  • تعامل مع العملات كرموز مبهمة. استخدم سلاسل ISO 4217 — لا تفترض أبداً أن لكل عملة منزلتين عشريتين. JPY لها صفر، و BHD لها ثلاث. يغطي دليل ISO 4217 لدينا الحالات الحدية.

أفضل الممارسات للإنتاج

أنماط إضافية تفرّق بين دمج هواية ونظام يمكنك تشغيله لسنوات:

  • اضبط مهل HTTP ضيقة. المهلة الافتراضية البالغة 100 ثانية في HttpClient.Timeout ستحجز خيوط الـ thread pool تحت الحمل. خمس ثوان أكثر من كافية لواجهة عملات.
  • غلّف كل اتصال خارجي بـ CancellationToken. يمرّره ASP.NET Core مجاناً، فاحترمه كي لا تستمر الطلبات المسقطة في التحدث مع المنبع.
  • سجّل رموز الحالة لا أجسام الاستجابة. ردود واجهة العملات أكبر من أن تُسجّل بفائدة وقد تحوي بيانات أسعار لا تريدها في Splunk.
  • راقب حصتك. قارن خطط الأسعار واضبط تنبيهات في CloudWatch / Application Insights عند 80% من السقف الشهري.
  • ثبّت العملات التي تستخدمها فعلاً. إرسال symbols=EUR,GBP,JPY يقلّص الاستجابة من ~10 كيلوبايت إلى أقل من 200 بايت.
  • خزّن مؤقتاً بقوة. عمليات الدفع الحساسة للزمن تكتفي بتخزين 30 ثانية، ولوحات الإدارة بـ 5 دقائق.

إذا كنت تقيّم مزوّدين، يستعرض مقارنتنا بين واجهات العملات المجانية والمدفوعة الدقة ومدة التشغيل والأسعار بين الخيارات الكبرى.

أسئلة شائعة

أي واجهة عملات تعمل أفضل مع C# و .NET؟ أي REST API بصيغة JSON نظيفة ومدة تشغيل مستقرة ستندمج جيداً عبر IHttpClientFactory. صُمّمت Finexly لتكون محايدة بالنسبة للغة — نفس النقاط يستهلكها عملاء Node و Python و Go و Java و .NET دون قيد SDK. راجع نظرة عامة على واجهة العملات المجانية.

هل أستخدم Newtonsoft.Json أم System.Text.Json؟ للكود الجديد على .NET 6+ استخدم System.Text.Json. أسرع بـ 2–3 مرات، وأقل تخصيصاً، وجزء من المكتبة الأساسية، فلا توجد حزمة إضافية لتحديثها. Newtonsoft.Json لا يزال ممتازاً ويستحق البقاء في الكود القديم، لكن الدمج الجديد لواجهات العملات في C# يجب أن يكون افتراضه System.Text.Json.

هل أحتاج إلى NuGet SDK أم يكفي HttpClient؟ عميل مكتوب يدوياً بأنواع صارمة (نحو 50 سطر C#) هو الإجابة الصحيحة دائماً تقريباً. يمنحك تحكماً كاملاً في التخزين المؤقت وإعادة المحاولة والتلميتري والتسلسل، ويتجنب مخاطر اختلاف الإصدارات المرتبطة بأي SDK خارجي. المثال في هذا الدليل جاهز للإنتاج.

كم مرة يجب تحديث الأسعار في تطبيق .NET؟ في معظم الحالات — دفع المتاجر، فوترة SaaS، إصدار الفواتير — تخزين مؤقت من 30 إلى 60 ثانية آمن. تحتاج أنظمة التداول إلى بيانات لحظية، لكن لكل ما عدا ذلك يكون التحديث بدقائق غير مرئي للمستخدم ويقلّل تكلفة الواجهة بشكل كبير.

هل يمكنني تشغيل ذلك في Azure Functions أو AWS Lambda؟ نعم. يعمل IHttpClientFactory بالطريقة نفسها في Azure Functions ذات العملية المعزولة وفي معالجات Lambda مع Microsoft.Extensions.Hosting. لأعباء حساسة للبدء البارد، انشر بـ AOT (PublishAot=true) لتبدأ دالتك في أقل من 100 مللي ثانية.

هل decimal بطيء مقارنة بـ double؟ decimal أبطأ نحو 10–20 مرة من double في كل عملية حسابية، لكن تحويل العملات يجري بضع ضربات على الأكثر. لن تقيس الفارق في عبء حقيقي أبداً — ومكسب الصحة في النقود غير قابل للتفاوض.

خاتمة

أصبح بحوزتك مخطط شامل وجاهز للإنتاج لدمج واجهة برمجة أسعار الصرف في C# / .NET: نماذج بأنواع صارمة، وعميل مدعوم بـ IHttpClientFactory، وإعادة محاولة وقاطع دائرة عبر Polly، وتخزين مؤقت داخلي، ومحوّل لسطر الأوامر، و ASP.NET Core Minimal API. كل نمط هنا مأخوذ مباشرة من توجيهات مايكروسوفت الرسمية ومجرّب في كود إنتاج فينتك حقيقي.

جاهز لإيصال أسعار صرف لحظية إلى تطبيق .NET الخاص بك؟ احصل على مفتاح Finexly API المجاني — دون بطاقة ائتمان. ابدأ بـ 1000 طلب مجاني شهرياً، وقم بالترقية مع نمو منتجك. إذا أردت أولاً معرفة كيف تقارن Finexly بمزوّدين آخرين، اقرأ مقارنة واجهات العملات.

Explore More

API Documentation

Full endpoint reference & examples
Currency Converter

Try live rates instantly
Pricing Plans

Free tier & production plans
VG

Vlado Grigirov

Senior Currency Markets Analyst & Financial Strategist

Vlado Grigirov is a senior currency markets analyst and financial strategist with over 14 years of experience in foreign exchange markets, cross-border finance, and currency risk management. He has wo...

View full profile →

شارك هذه المقالة

تويتر لينكدإن البريد الإلكتروني