استفاده از 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، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.