PP مستندات فضای ابری پارس‌پک
.NET 8+ · AWS SDK for .NET v4

AmazonS3Client را برای پارس‌پک بسازید

نمونهٔ .NET تنظیم ServiceURL، path-style و Region امضا را در یک AmazonS3Config متمرکز می‌کند. عملیات شبکه async است، Response و Stream به‌درستی Dispose می‌شوند و لینک‌های موقت GET و PUT هم از همان Client ساخته می‌شوند.

.NET 8Async I/OPresigned GET و PUT
برنامه C# متصل به فضای ذخیره‌سازی
هفت فرمان با خروجی JSON

برنامه هر عملیات را از یک زیرفرمان اجرا می‌کند و نتیجه را JSON برمی‌گرداند. فایل آزمایشی در Prefix مجزای tutorial/ قرار می‌گیرد.

اجرای مراحل از ابتدا باعث می‌شود خطای اتصال، مجوز و نبودن Object را از هم تمیز بدهید.

۱

پیش‌نیاز و نصب SDK

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

فرمان را از ریشه همین مستندات بزنید. اگر نصب درست باشد، وابستگی‌ها داخل پوشه زبان می‌مانند و لازم نیست آن‌ها را جهانی نصب کنید.
terminal · نصب و بررسی
(cd examples/csharp && dotnet restore && dotnet build --no-restore)
ساختار فایل‌ها
examples/csharp/
├── .env               # پس از کپی‌کردن فایل نمونه ساخته می‌شود
├── ParspackS3.csproj  # وابستگی‌های .NET
└── Program.cs         # Client و هفت فرمان مدیریت فایل
۲

ساخت فایل .env

پنج مقدار را از پنل فضای ابری پارس‌پک کپی کنید. معنی هر متغیر و شکل معمول Endpoint در صفحه شروع آمده است.

بعد از کپی، فقط مقدارها را عوض کنید؛ نام متغیرها را کوتاه نکنید. اگر اسلش ته Endpoint بماند یا Region را بی‌دلیل عوض کنید، اولین upload با خطای امضا می‌خوابد.
terminal
cp examples/.env.example examples/csharp/.env
examples/csharp/.env
PARSPACK_S3_ENDPOINT=https://c123456.parspack.net
PARSPACK_S3_BUCKET=c123456
PARSPACK_S3_REGION=us-east-1
PARSPACK_S3_ACCESS_KEY=YOUR_ACCESS_KEY
PARSPACK_S3_SECRET_KEY=YOUR_SECRET_KEY
متغیرچه چیزی در آن می‌گذاریداگر اشتباه باشد
PARSPACK_S3_ENDPOINTآدرس HTTPS پنل، بدون / در انتها؛ شکل معمول https://c123456.parspack.netTimeout یا خطای امضا
PARSPACK_S3_BUCKETنام باکت؛ اغلب با شناسه داخل Endpoint یکی استNoSuchBucket
PARSPACK_S3_REGIONفقط برای امضای Signature V4 است. اگر پنل Region نداد، us-east-1 را ثابت نگه داریدSignatureDoesNotMatch
PARSPACK_S3_ACCESS_KEY / SECRET_KEYکلیدهای API از پنل؛ فقط روی سرورAccessDenied یا خطای امضا
!

فایل .env را Commit نکنید. Access Key و Secret Key فقط روی سرور می‌مانند؛ مرورگر فقط لینک کوتاه‌عمر می‌گیرد.

۳

اتصال برنامه به فضای پارس‌پک

Client را یک بار با مقدارهای .env بسازید. همین شیء برای هر هفت فرمان کافی است.

در SDK دات‌نت، آدرس پنل در ServiceURL می‌رود، نه فیلدی به نام Endpoint. AuthenticationRegion همان Region امضاست؛ اگر پنل چیزی نگفت us-east-1 را عوض نکنید. ForcePathStyle باید true باشد تا URL به شکل /bucket/key ساخته شود.
Head در این SDK اسمش GetObjectMetadataAsync است؛ مشخصات فایل را می‌دهد و خود فایل را نمی‌آورد. لینک موقت با GetPreSignedURLAsync ساخته می‌شود. Access Key و Secret Key فقط روی سرور می‌مانند. در ASP.NET Core همین Client را یک بار در DI ثبت کنید.
C# · اتصال
Dictionary<string, string> env = LoadDotEnv();
string endpoint = Required(env, "PARSPACK_S3_ENDPOINT").TrimEnd('/');
string bucket = Required(env, "PARSPACK_S3_BUCKET");

var config = new AmazonS3Config
{
  ServiceURL = endpoint,
  AuthenticationRegion = Required(env, "PARSPACK_S3_REGION"),
  ForcePathStyle = true,
  MaxErrorRetry = 3,
};

var credentials = new BasicAWSCredentials(
  Required(env, "PARSPACK_S3_ACCESS_KEY"),
  Required(env, "PARSPACK_S3_SECRET_KEY")
);
using var s3 = new AmazonS3Client(credentials, config);
۴

آپلود فایل با PutObjectAsync

اولین فرمان سناریو: فایل محلی را با یک نام مشخص در باکت بگذارید.

فایل روی سیستم شما ./hello.txt است؛ داخل باکت با نام tutorial/hello.txt ذخیره می‌شود. اسلش پوشه واقعی نمی‌سازد، فقط بخشی از نام است. ETag اثر انگشت محتواست. اگر همین نام از قبل در باکت باشد، محتوای قبلی عوض می‌شود.
C# · آپلود فایل به باکت
PutObjectResponse response = await s3.PutObjectAsync(new PutObjectRequest
{
  BucketName = bucket,
  Key = "tutorial/hello.txt",
  FilePath = "./hello.txt",
  ContentType = "text/plain",
});

Console.WriteLine(response.ETag);
پارامترمثالکاربرد
Bucketاز .envمحل ذخیره Object
Keytutorial/hello.txtنام کامل Object در S3
FilePath./hello.txtفایل موجود روی سیستم
ContentTypetext/plainنوع محتوای فایل
terminal
(cd examples/csharp && dotnet run -- upload ./hello.txt tutorial/hello.txt)
خروجی نمونه
{ "ok": true, "operation": "upload", "key": "tutorial/hello.txt", "etag": "..." }
!

اگر tutorial/hello.txt از قبل وجود داشته باشد، Upload جدید همان Key را جایگزین می‌کند.

۵

فهرست فایل‌ها و مشخصات یک فایل

بعد از آپلود، اول ببینید فایل در فهرست هست؛ بعد حجم و نوع را بدون دانلود بخوانید.

list tutorial/ خود فایل را نمی‌آورد؛ فقط نام، حجم و زمان تغییر فایل‌هایی را برمی‌گرداند که با این Prefix شروع می‌شوند. اگر آرایه خالی بود، یا آپلود انجام نشده یا Prefix را اشتباه نوشته‌اید.
head وقتی لازم است که فقط بخواهید بدانید فایل هست یا نه، یا حجم و نوعش چیست. اگر Key نباشد معمولاً 404 می‌گیرید. این فرمان را با دانلود عوض نکنید؛ بدنه فایل را منتقل نمی‌کند.
C# · فهرست فایل‌ها
string? continuationToken = null;
do
{
  ListObjectsV2Response response = await s3.ListObjectsV2Async(new ListObjectsV2Request
  {
      BucketName = bucket,
      Prefix = "tutorial/",
      ContinuationToken = continuationToken,
  });
  foreach (S3Object item in response.S3Objects)
  {
      Console.WriteLine($"${item.Key} — ${item.Size}");
  }
  continuationToken = response.IsTruncated == true ? response.NextContinuationToken : null;
} while (continuationToken is not null);
terminal
(cd examples/csharp && dotnet run -- list tutorial/)
خروجی نمونه
{ "ok": true, "prefix": "tutorial/", "objects": [ { "key": "tutorial/hello.txt", "bytes": 14, "last_modified": "2026-08-18T10:00:00+00:00" } ] }
C# · مشخصات یک فایل
GetObjectMetadataResponse info = await s3.GetObjectMetadataAsync(new GetObjectMetadataRequest
{
  BucketName = bucket,
  Key = "tutorial/hello.txt",
});

Console.WriteLine(info.ContentLength);
Console.WriteLine(info.Headers.ContentType);
terminal
(cd examples/csharp && dotnet run -- head tutorial/hello.txt)
خروجی نمونه
{ "ok": true, "key": "tutorial/hello.txt", "bytes": 14, "content_type": "text/plain", "etag": "...", "last_modified": "2026-08-18T10:00:00+00:00" }
Prefixاگر tutorial/ بگذارید، فقط فایل‌هایی که نامشان با این مقدار شروع می‌شود دیده می‌شوند.
ContinuationTokenتا زمانی که IsTruncated درست است، صفحه بعدی را دریافت کنید.
HeadGetObjectMetadataAsync حجم، نوع، ETag و زمان تغییر را می‌گوید؛ خود فایل را دانلود نمی‌کند.
Key ناموجودبرای Key ناموجود خطای 404 دریافت می‌کنید.
۶

دانلود روی سرور

فایل را از باکت بگیرید و روی دیسک همین برنامه بنویسید. این کار لینک برای کاربر نمی‌سازد.

این فرمان فایل را از باکت می‌گیرد و روی دیسک همین برنامه می‌نویسد. کاربر سایت آن را نمی‌بیند مگر خودتان بعداً برایش بفرستید. وقتی به آن نیاز دارید که سرور باید فایل را پردازش کند، در ایمیل ضمیمه کند، یا جای دیگری نگه دارد. پوشه مقصد اگر نباشد، نمونه آن را می‌سازد.
C# · ذخیره فایل روی سرور
using GetObjectResponse response = await s3.GetObjectAsync(new GetObjectRequest
{
  BucketName = bucket,
  Key = "tutorial/hello.txt",
});

await response.WriteResponseStreamToFileAsync(
  "./downloads/hello.txt", false, CancellationToken.None);
terminal
(cd examples/csharp && dotnet run -- download tutorial/hello.txt ./downloads/hello.txt)
خروجی نمونه
{ "ok": true, "operation": "download", "key": "tutorial/hello.txt", "local_file": "./downloads/hello.txt", "bytes": 14 }
۷

لینک موقت دانلود برای کاربر

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

باکت خصوصی است و کلید API را نباید به کاربر بدهید. این کد فایل را ذخیره نمی‌کند؛ فقط یک URL چند دقیقه‌ای می‌سازد. مثال: کاربر بعد از ورود روی «دانلود فاکتور» می‌زند، سرور مجوز را چک می‌کند، لینک را برمی‌گرداند، مرورگر همان آدرس را باز می‌کند. فایل از سرور شما رد نمی‌شود.
همان URL را در مرورگر باز کنید، در <a href> بگذارید، یا با curl --output file.pdf "$URL" بگیرید. Header اضافه لازم نیست. 900 یعنی پانزده دقیقه؛ بعد از آن آدرس کار نمی‌کند.
C# · ساخت لینک موقت دانلود
string downloadUrl = await s3.GetPreSignedURLAsync(new GetPreSignedUrlRequest
{
  BucketName = bucket,
  Key = objectKey,
  Verb = HttpVerb.GET,
  Expires = DateTime.UtcNow.AddMinutes(15),
});
terminal
(cd examples/csharp && dotnet run -- presign-get tutorial/hello.txt 900)
خروجی نمونه
{ "ok": true, "operation": "presign-get", "key": "tutorial/hello.txt", "method": "GET", "expires_in": 900, "url": "https://c123456.parspack.net/c123456/tutorial/hello.txt?X-Amz-..." }
curl · گرفتن فایل با لینک موقت دانلود
curl --output invoice.pdf "$SIGNED_DOWNLOAD_URL"
!

لینک را کوتاه نگه دارید؛ بین ۱ ثانیه تا ۷ روز (۶۰۴۸۰۰ ثانیه). فقط همان Key را می‌خواند. لینک را فقط بعد از ورود کاربر و چک مجوز بسازید.

۸

لینک موقت آپلود مستقیم

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

وقتی کاربر باید فایل را از مرورگر بفرستد، ولی نباید کلید را ببیند و نباید کل فایل از سرور شما عبور کند، سرور نام و نوع را خودش قفل می‌کند و URL می‌سازد. مثال: آپلود عکس پروفایل. کاربر فقط حق دارد همان یک نام را با روش PUT بنویسد.
بدنه فایل را با PUT به همان URL بفرستید و Content-Type را دقیقاً همان مقدار زمان ساخت لینک بگذارید؛ وگرنه معمولاً خطای امضا می‌گیرید. از مرورگر فقط وقتی کار می‌کند که CORS باکت سایت شما را مجاز کرده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.
C# · ساخت لینک موقت آپلود
string contentType = "text/plain";

string uploadUrl = await s3.GetPreSignedURLAsync(new GetPreSignedUrlRequest
{
  BucketName = bucket,
  Key = objectKey,
  Verb = HttpVerb.PUT,
  ContentType = contentType,
  Expires = DateTime.UtcNow.AddMinutes(15),
});
terminal
(cd examples/csharp && dotnet run -- presign-put tutorial/upload.txt text/plain 900)
خروجی نمونه
{ "ok": true, "operation": "presign-put", "key": "tutorial/upload.txt", "method": "PUT", "headers": { "Content-Type": "text/plain" }, "expires_in": 900, "url": "https://c123456.parspack.net/c123456/tutorial/upload.txt?X-Amz-..." }
curl · فرستادن فایل با لینک موقت آپلود
curl --request PUT \
--header 'Content-Type: text/plain' \
--upload-file ./hello.txt \
"$SIGNED_UPLOAD_URL"
مرورگر · fetch آپلود
await fetch(signed.url, {
method: "PUT",
headers: { "Content-Type": signed.headers["Content-Type"] },
body: file,
});
Presigned GETPresigned PUT
MethodGETPUT
ورودی امضاBucket، Key، انقضاBucket، Key، Content-Type، انقضا
جایگزین کدام فرمان سرور استجایگزین download برای کاربر نهاییجایگزین upload وقتی فایل نباید از سرور شما عبور کند
!

اگر موقع ساخت لینک text/plain گذاشته‌اید، هنگام ارسال هم باید همان را بفرستید. از مرورگر این کار فقط وقتی درست است که CORS باکت سایت شما را مجاز کرده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.

۹

حذف فایل با DeleteObjectAsync

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

اگر آن نام در باکت نباشد، معمولاً باز هم پاسخ موفق می‌آید. پس خود برنامه باید بداند کدام Key را حذف کرده است، نه اینکه فقط به موفق بودن پاسخ اعتماد کند.
C# · حذف از باکت
await s3.DeleteObjectAsync(new DeleteObjectRequest
{
  BucketName = bucket,
  Key = "tutorial/hello.txt",
});
terminal
(cd examples/csharp && dotnet run -- delete tutorial/hello.txt)
خروجی نمونه
{ "ok": true, "operation": "delete", "key": "tutorial/hello.txt" }
۱۰

StatusCode و ErrorCode را ثبت کنید

AmazonS3Exception جزئیات پاسخ سرویس را در اختیار شما می‌گذارد. نمونه آن‌ها را روی stderr چاپ می‌کند تا خطای مجوز، امضا یا باکت با مشکل ارتباطی اشتباه نشود.

C# · catch
catch (AmazonS3Exception error)
{
  Console.Error.WriteLine($"${error.ErrorCode}: ${error.Message}");
  return 1;
}
catch (Exception error)
{
  Console.Error.WriteLine($"${error.GetType().Name}: ${error.Message}");
  return 1;
}
خطاعلت معمولبررسی
Local file not foundمسیر فایل محلی اشتباه استمسیر را نسبت به پوشه examples/csharp بررسی کنید
AccessDeniedکلید یا دسترسی Bucket کافی نیستمقدارهای پنل و نوع دسترسی کاربر فضای ابری
SignatureDoesNotMatchامضای درخواست با تنظیمات یکی نیستSlash انتهای Endpoint، Region، کلیدها و Content-Type در PUT
NoSuchBucketنام Bucket با مقدار پنل یکی نیستPARSPACK_S3_BUCKET
Timeout / connectionEndpoint در دسترس نیست یا HTTPS قطع استآدرس پنل را بدون تغییر و بدون / انتها وارد کنید
۱۱

اجرای کامل همین سناریو

فایل همراه مستندات، Loader فایل .env، اعتبارسنجی ورودی، تشخیص Content-Type و خروجی JSON را یک‌جا دارد و Client را با using می‌بندد. اگر خروجی هر فرمان شبیه نمونه‌های بالا بود، می‌توانید Key و مسیر را با نام فایل‌های برنامه خودتان عوض کنید.

terminal · از ابتدا تا انتها
(cd examples/csharp && dotnet restore && dotnet build --no-restore)
cp examples/.env.example examples/csharp/.env

# مقدارهای .env را کامل کنید
printf 'hello ParsPack\n' > hello.txt
(cd examples/csharp && dotnet run -- upload ./hello.txt tutorial/hello.txt)
(cd examples/csharp && dotnet run -- list tutorial/)
(cd examples/csharp && dotnet run -- head tutorial/hello.txt)
(cd examples/csharp && dotnet run -- download tutorial/hello.txt ./downloads/hello.txt)
(cd examples/csharp && dotnet run -- presign-get tutorial/hello.txt 900)
(cd examples/csharp && dotnet run -- presign-put tutorial/upload.txt text/plain 900)
(cd examples/csharp && dotnet run -- delete tutorial/hello.txt)
ASP.NET CoreIAmazonS3 را به‌صورت Singleton در DI ثبت کنید و در Storage service استفاده کنید.
Key کنترل‌شدهKey را در Backend بسازید و نتیجه Upload را کنار رکورد مربوط در Database نگه دارید.
Streamبرای فایل بزرگ به‌جای FilePath از InputStream استفاده کنید.
خطای APIAmazonS3Exception را به Status مناسب برنامه خود تبدیل کنید.
پروژهٔ C# آماده است.کد کامل به‌همراه ParspackS3.csproj در این zip است؛ کافی است باز کنید و dotnet run بزنید.
دریافت csharp.zip