استفاده از SDKهای C# تولیدشده در Postman

این راهنما روش استفاده از SDKهای C# تولیدشده با Postman SDK Generator را توضیح می‌دهد. این SDKها برای پروژه‌های .NET آماده‌اند و شامل client، serviceها، modelها، authentication، validation، retry و error handling هستند.

ساختار SDK C# #

• src/: کد اصلی SDK.
• Services/: service classها برای endpoint groupها.
• Models/: modelهای request/response و exceptionهای typed.
• Http/: HTTP client، pipeline، retry و transport.
• *.csproj: تنظیمات package، dependencyها و target framework.

اجرای نمونه SDK #

هر SDK پوشه examples/ دارد. نمونه را اجرا کنید تا الگوی initialization و API call را ببینید.

cd examples
dotnet restore
dotnet run

using YourSdk;

var sdk = new YourSdkClient(new YourSdkConfig
{
    ApiKey = "your-api-key",
    BaseUrl = "https://api.example.com"
});

try
{
    var user = await sdk.Users.GetUserAsync("123");
    Console.WriteLine(user);
}
catch (Exception ex)
{
    Console.WriteLine(ex.Message);
}

نصب SDK C# #

نصب با NuGet #

اگر SDK را در NuGet منتشر کرده‌اید، آن را مثل هر package دیگری نصب کنید.

dotnet add package YourSdk

نصب از مسیر local #

برای کار محلی، می‌توانید project reference بدهید یا package محلی بسازید.

dotnet add reference ../path/to/your-sdk/YourSdk.csproj

dotnet pack -c Release
dotnet add package YourSdk --source ../path/to/your-sdk/bin/Release

انتشار در NuGet #

برای انتشار، به حساب NuGet، API key، نام package یکتا و metadata کامل در فایل project نیاز دارید.

<PropertyGroup>
  <PackageId>YourSdk</PackageId>
  <Version>1.0.0</Version>
  <Authors>Your Organization</Authors>
  <Description>SDK for Your API</Description>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

dotnet restore
dotnet build -c Release
dotnet test
dotnet pack -c Release
dotnet nuget push bin/Release/*.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json

برای نسخه جدید، version را افزایش دهید و دوباره pack/push کنید.

بهترین کارها برای NuGet #

• README و نمونه کد همراه package قرار دهید.
• از semantic versioning استفاده کنید.
• قبل از push، testها را اجرا کنید.
• Symbol package و source link را برای debugging بهتر در نظر بگیرید.
• انتشار را در CI/CD خودکار کنید.

Authentication #

var sdk = new YourSdkClient(new YourSdkConfig
{
    ApiKey = "your-api-key"
});

var sdk = new YourSdkClient(new YourSdkConfig
{
    AccessToken = "your-bearer-token"
});

var sdk = new YourSdkClient(new YourSdkConfig
{
    Username = "your-username",
    Password = "your-password"
});

Asynchronous calls و cancellation #

در C# بیشتر فراخوانی‌ها async هستند و از Task استفاده می‌کنند. برای لغو request می‌توانید CancellationToken پاس بدهید.

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
var user = await sdk.Users.GetUserAsync("123", cancellationToken: cts.Token);

Environment management #

var sdk = new YourSdkClient(new YourSdkConfig
{
    Environment = Environment.Production,
    ApiKey = "your-api-key"
});

var customSdk = new YourSdkClient(new YourSdkConfig
{
    BaseUrl = "https://custom.api.example.com",
    ApiKey = "your-api-key"
});

Hierarchical configuration #

تنظیمات می‌توانند در سطح SDK، service، method و request اعمال شوند. تنظیم request خاص‌ترین سطح است.

var requestConfig = new RequestConfig
{
    Timeout = TimeSpan.FromSeconds(30),
    BaseUrl = "https://legacy-api.example.com"
};

var user = await sdk.Users.GetUserAsync("123", requestConfig);

Error handling #

SDK برای API errorها exceptionهای اختصاصی دارد. این exceptionها معمولا status code و response را نگه می‌دارند.

try
{
    var user = await sdk.Users.GetUserAsync("123");
}
catch (ValidationException ex)
{
    Console.WriteLine($"Validation failed: {ex.Message}");
}
catch (ApiException ex)
{
    Console.WriteLine($"API error: {ex.Message}");
    Console.WriteLine($"Status code: {ex.StatusCode}");
    Console.WriteLine($"Response: {ex.Response}");
}
catch (Exception ex)
{
    Console.WriteLine($"Unexpected error: {ex.Message}");
}

catch (ApiException ex) when (ex.StatusCode == 404)
{
    Console.WriteLine("User not found");
}

Timeout و retry #

var sdk = new YourSdkClient(new YourSdkConfig
{
    ApiKey = "your-api-key",
    Timeout = TimeSpan.FromSeconds(10),
    Retry = new RetryConfig
    {
        Attempts = 3,
        Delay = TimeSpan.FromSeconds(1),
        MaxDelay = TimeSpan.FromSeconds(30),
        BackoffFactor = 2
    }
});

Validation #

SDK constraintهای OpenAPI را قبل از ارسال request بررسی می‌کند. اگر validation شکست بخورد، exception شامل فهرست violationها دریافت می‌کنید.

Optional و nullable fieldها #

در C# تفاوت بین property تنظیم‌نشده، مقدار null و مقدار واقعی برای APIهای update مهم است. SDK این تفاوت را در modelها و serialization تا حد ممکن حفظ می‌کند.

Resource cleanup #

اگر SDK یا HTTP client شما disposable است، آن را با using یا lifecycle مناسب DI container مدیریت کنید.

using var sdk = new YourSdkClient(config);

منابع داخل SDK #

• پوشه documentation/ برای serviceها و modelها.
• پوشه examples/ برای نمونه اجرایی.
• فایل‌های .csproj برای تنظیم package و target framework.
• وابستگی‌های HTTP و JSON serialization بسته به خروجی generator.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.