قصد داریم اطلاعات یک فرم React را به همراه دو فایل الصاقی به آن، به سمت یک سرور ASP.NET Core ارسال کنیم؛ بطوریکه درصد پیشرفت ارسال فایل‌ها، زمان سپری شده، زمان باقی مانده و سرعت آپلود نیز گزارش داده شوند:
پیشنیازها
«
بررسی روش آپلود فایل‌ها در ASP.NET Core»
«
ارسال فایل و تصویر به همراه داده‌های دیگر از طریق jQuery Ajax »
- در مطلب اول، روش دریافت فایل‌ها از کلاینت، در سمت سرور و ذخیره سازی آنها در یک برنامه‌ی ASP.NET Core بررسی شده‌است که کلیات آن در اینجا نیز صادق است.
- در مطلب دوم، روش کار با
FormData استاندارد بررسی شده‌است. هرچند در مطلب جاری از jQuery استفاده نمی‌شود، اما نکات نحوه‌ی کار با شیء FormData استاندارد، در اینجا نیز یکی است.
برپایی پروژه‌های مورد نیاز
ابتدا یک پوشه‌ی جدید مانند UploadFilesSample را ایجاد کرده و در داخل آن دستور زیر را اجرا میکنیم:
در مورد این قالب که امکان تجربه‌ی توسعه‌ی یکپارچه‌ی ASP.NET Core و React را میسر میکند، در مطلب «
روش یکی کردن پروژه‌های React و ASP.NET Core» بیشتر بحث کرده‌ایم.
سپس در این پوشه، پوشه‌ی ClientApp پیشفرض آن‌را حذف میکنیم؛ چون کمی قدیمی است. همچنین فایل‌های کنترلر و سرویس آب و هوای پیشفرض آن‌را به همراه پوشه‌ی صفحات Razor آن، حذف و پوشه‌ی خالی wwwroot را نیز به آن اضافه میکنیم.
همچنین بجای تنظیم پیش فرض زیر در فایل کلاس آغازین برنامه:
spa.UseReactDevelopmentServer(npmScript: "start");
از تنظیم زیر استفاده کرده‌ایم تا با هر بار تغییری در کدهای پروژه‌ی ASP.NET، یکبار دیگر از صفر npm start اجرا نشود:
spa.UseProxyToSpaDevelopmentServer("http://localhost:3000");
بدیهی است در این حالت باید از طریق خط فرمان به پوشه‌ی clientApp وارد شد و دستور npm start را یکبار به صورت دستی اجرا کرد، تا این وب سرور بر روی پورت 3000، راه اندازی شود. البته ما برنامه را به صورت یکپارچه بر روی پورت 5001 وب سرور ASP.NET Core، مرور میکنیم.
اکنون در ریشه‌ی پروژه‌ی ASP.NET Core ایجاد شده، دستور زیر را صادر میکنیم تا پروژه‌ی کلاینت React را با فرمت جدید آن ایجاد کند:
> create-react-app clientapp
سپس وارد این پوشه‌ی جدید شده و بسته‌های زیر را نصب میکنیم:
> cd clientapp
> npm install --save bootstrap axios react-toastify
توضیحات:
- برای استفاده از شیوه‌نامه‌های بوت استرپ، بسته‌ی bootstrap نیز در اینجا نصب میشود که برای افزودن فایل bootstrap.css آن به پروژه‌ی React خود، ابتدای فایل clientapp\src\index.js را به نحو زیر ویرایش خواهیم کرد:
import "bootstrap/dist/css/bootstrap.css";
این import به صورت خودکار توسط webpack ای که در پشت صحنه کار bundling & minification برنامه را انجام میدهد، مورد استفاده قرار می‌گیرد.
- برای نمایش پیام‌های برنامه از کامپوننت react-toastify استفاده میکنیم که پس از نصب آن، با مراجعه به فایل app.js نیاز است importهای لازم آن‌را اضافه کنیم:
import { ToastContainer } from "react-toastify";
import "react-toastify/dist/ReactToastify.css";
همچنین نیاز است ToastContainer را به ابتدای متد render آن نیز اضافه کرد:
render() {
return (
<React.Fragment>
<ToastContainer />
- برای ارسال فایل‌ها به سمت سرور از کتابخانه‌ی معروف axios استفاده خواهیم کرد.
ایجاد کامپوننت React فرم ارسال فایل‌ها به سمت سرور
پس از این مقدمات، فایل جدید clientapp\src\components\UploadFileSimple.jsx را ایجاد کرده و به صورت زیر تکمیل میکنیم:
import React, { useState } from "react";
import axios from "axios";
import { toast } from "react-toastify";
export default function UploadFileSimple() {
const [description, setDescription] = useState("");
const [selectedFile1, setSelectedFile1] = useState();
const [selectedFile2, setSelectedFile2] = useState();
return (
<form>
<fieldset className="form-group">
<legend>Support Form</legend>
<div className="form-group row">
<label className="form-control-label" htmlFor="description">
Description
</label>
<input
type="text"
className="form-control"
name="description"
onChange={event => setDescription(event.target.value)}
value={description}
/>
</div>
<div className="form-group row">
<label className="form-control-label" htmlFor="file1">
File 1
</label>
<input
type="file"
className="form-control"
name="file1"
onChange={event => setSelectedFile1(event.target.files[0])}
/>
</div>
<div className="form-group row">
<label className="form-control-label" htmlFor="file2">
File 2
</label>
<input
type="file"
className="form-control"
name="file2"
onChange={event => setSelectedFile2(event.target.files[0])}
/>
</div>
<div className="form-group row">
<button
className="btn btn-primary"
type="submit"
>
Submit
</button>
</div>
</fieldset>
</form>
);
}
کاری که تا این مرحله انجام شده، بازگشت UI فرم برنامه توسط یک functional component است.
- توسط آن یک textbox به همراه دو فیلد ارسال فایل، به فرم اضافه شده‌اند.
- مرحله‌ی بعد، دسترسی به فایل‌های انتخابی کاربر و همچنین مقدار توضیحات وارد شده‌است. به همین جهت با استفاده از useState Hook، روش دریافت و تنظیم این مقادیر را مشخص کرده‌ایم:
const [description, setDescription] = useState("");
const [selectedFile1, setSelectedFile1] = useState();
const [selectedFile2, setSelectedFile2] = useState();
با React Hooks، بجای تعریف یک state، به صورت خاصیت، آن‌را صرفا use میکنیم و یا همان useState، که یک تابع است و باید در ابتدای کامپوننت، مورد استفاده قرار گیرد. این متد برای شروع به کار، نیاز به یک state آغازین را دارد؛ مانند انتساب یک رشته‌ی خالی به description. سپس اولین خروجی متد useState که داخل یک آرایه مشخص شده‌است، همان متغیر description است که توسط state ردیابی خواهد شد. اینبار بجای متد this.setState قبلی که یک متد عمومی بود، متدی اختصاصی را صرفا جهت تغییر مقدار همین متغیر description به نام setDescription به عنوان دومین خروجی متد useState، تعریف میکنیم. بنابراین متد useState، یک initialState را دریافت میکند و سپس یک مقدار را به همراه یک متد، جهت تغییر state آن، بازگشت میدهد. همین کار را برای دو فیلد دیگر نیز تکرار کرده‌ایم. بنابراین selectedFile1، فایلی است که توسط متد setSelectedFile1 تنظیم خواهد شد و این تنظیم، سبب رندر مجدد UI نیز خواهد گردید.
- پس از طراحی state این فرم، مرحله‌ی بعدی، استفاده از متدهای set تمام useStateهای فوق است. برای مثال در مورد یک textbox معمولی، میتوان آن‌را به صورت inline تعریف کرد و با هر بار تغییری در محتوای آن، این رخ‌داد را به متد setDescription ارسال نمود تا مقدار وارد شده را به متغیر حالت description انتساب دهد:
<input
type="text"
className="form-control"
name="description"
onChange={event => setDescription(event.target.value)}
value={description}
/>
در مورد فیلدهای دریافت فایل‌ها، روش انجام اینکار به صورت زیر است:
<input
type="file"
className="form-control"
name="file1"
onChange={event => setSelectedFile1(event.target.files[0])}
/>
چون المان‌های دریافت فایل می‌توانند بیش از یک فایل را نیز دریافت کنند (اگر ویژگی multiple، به تعریف تگ آنها اضافه شود)، به همین جهت خاصیت files بر روی آنها قابل دسترسی شده‌است. اما چون در اینجا ویژگی multiple ذکر نشده‌است، بنابراین تنها یک فایل توسط آنها قابل دریافت است و به همین جهت دسترسی به اولین فایل و یا files[0] را در اینجا مشاهده میکنید. بنابراین با فراخوانی متد setSelectedFile1، اکنون متغیر حالت selectedFile1، مقدار دهی شده و قابل استفاده است.
تشکیل مدل ارسال داده‌ها به سمت سرور
در فرم‌های معمولی، عموما داده‌ها به صورت یک شیء JSON به سمت سرور ارسال می‌شوند؛ اما در اینجا وضع متفاوت است و به همراه توضیحات وارد شده، دو فایل باینری نیز وجود دارند.
در حالت ارسال متداول فرم‌هایی که به همراه المان‌های دریافت فایل هستند، ابتدا یک ویژگی enctype با مقدار multipart/form-data به المان فرم اضافه میشود و سپس این فرم به سادگی قابلیت post-back به سمت سرور را پیدا میکند:
<form enctype="multipart/form-data" action="/upload" method="post">
<input id="file-input" type="file" />
</form>
اما اگر قرار باشد همین فرم را توسط جاوا اسکریپت به سمت سرور ارسال کنیم، روش کار به صورت زیر است:
let file = document.getElementById("file-input").files[0];
let formData = new FormData();
formData.append("file", file);
fetch('/upload/image', {method: "POST", body: formData});
ابتدا به خاصیت files و اولین فایل آن دسترسی پیدا کرده و سپس شیء استاندارد FormData را بر اساس آن و تمام فیلدهای فرم تشکیل می‌دهیم. FormData ساختاری شبیه به یک دیکشنری را دارد و از کلیدهایی که متناظر با Id المان‌های فرم و مقادیری متناظر با مقادیر آن المان‌ها هستند، تشکیل میشود که توسط متد append آن، به این دیکشنری اضافه خواهند شد. در آخر هم شیء formData را به سمت سرور ارسال میکنیم.
در یک برنامه‌ی React نیز باید دقیقا چنین مراحلی طی شوند. تا اینجا کار دسترسی به مقدار files[0] و تشکیل متغیرهای حالت فرم را انجام داده‌ایم. در مرحله‌ی بعد، شیء FormData را تشکیل خواهیم داد:
// ...
export default function UploadFileSimple() {
// ...
const handleSubmit = async event => {
event.preventDefault();
const formData = new FormData();
formData.append("description", description);
formData.append("file1", selectedFile1);
formData.append("file2", selectedFile2);
toast.success("Form has been submitted successfully!");
setDescription("");
};
return (
<form onSubmit={handleSubmit}>
</form>
);
}
به همین جهت، ابتدا کار مدیریت رخ‌داد onSubmit فرم را انجام داده و توسط آن با استفاده از متد preventDefault، از post-back متداول فرم به سمت سرور جلوگیری میکنیم. سپس شیء FormData را بر اساس مقادیر حالت متناظر با المان‌های فرم، تشکیل می‌دهیم. کلیدهایی که در اینجا ذکر می‌شوند، نام خواص مدل متناظر سمت سرور را نیز تشکیل خواهند داد.
ارسال مدل داده‌های فرم React به سمت سرور
پس از تشکیل شیء FormData در متد مدیریت کننده‌ی handleSubmit، اکنون با استفاده از کتابخانه‌ی axios، کار ارسال این اطلاعات را به سمت سرور انجام خواهیم داد:
// ...
export default function UploadFileSimple() {
const apiUrl = "https://localhost:5001/api/SimpleUpload/SaveTicket";
// ...
const [isUploading, setIsUploading] = useState(false);
const handleSubmit = async event => {
event.preventDefault();
const formData = new FormData();
formData.append("description", description);
formData.append("file1", selectedFile1);
formData.append("file2", selectedFile2);
try {
setIsUploading(true);
const { data } = await axios.post(apiUrl, formData, {
headers: {
"Content-Type": "multipart/form-data"
}}
});
toast.success("Form has been submitted successfully!");
console.log("uploadResult", data);
setIsUploading(false);
setDescription("");
} catch (error) {
setIsUploading(false);
toast.error(error);
}
};
return (
// ...
);
}
در اینجا نحوه‌ی ارسال شیء FormData را توسط کتابخانه‌ی axios به سمت سرور مشاهده میکنید. با استفاده از متد post آن، به سمت مسیر api/SimpleUpload/SaveTicket که آن‌را در ادامه تکمیل خواهیم کرد، شیء formData متناظر با اطلاعات فرم، به صورت async، ارسال شده‌است. همچنین headers آن نیز به همان «"enctype="multipart/form-data» که پیشتر توضیح داده شد، تنظیم شده‌است.
در قطعه کد فوق، متغیر جدید حالت isLoading را نیز مشاهده میکنید. از آن میتوان برای فعال و غیرفعال کردن دکمه‌ی submit فرم در زمان ارسال اطلاعات به سمت سرور، استفاده کرد:
<button
disabled={ isUploading }
className="btn btn-primary"
type="submit"
>
Submit
</button>
به این ترتیب اگر فراخوانی await axios.post هنوز به پایان نرسیده باشد، مقدار isUploading مساوی true بوده و سبب غیرفعال شدن دکمه‌ی submit میشود.
اعتبارسنجی سمت کلاینت فایل‌های ارسالی به سمت سرور
در اینجا شاید نیاز باشد نوع و یا اندازه‌ی فایل‌های انتخابی توسط کاربر را تعیین اعتبار کرد. به همین جهت متدی را برای اینکار به صورت زیر تهیه میکنیم:
const isFileValid = selectedFile => {
if (!selectedFile) {
// toast.error("Please select a file.");
return false;
}
const allowedMimeTypes = [
"image/png",
"image/jpeg",
"image/gif",
"image/svg+xml"
];
if (!allowedMimeTypes.includes(selectedFile.type)) {
toast.error(`Invalid file type: ${selectedFile.type}`);
return false;
}
const maxFileSize = 1024 * 500;
const fileSize = selectedFile.size;
if (fileSize > maxFileSize) {
toast.error(
`File size ${(fileSize / 1024).toFixed(
2
)} KB must be less than ${maxFileSize / 1024} KB`
);
return false;
}
return true;
};
در اینجا ابتدا بررسی میشود که آیا فایلی انتخاب شده‌است یا خیر؟ سپس فایل انتخاب شده، باید دارای یکی از MimeTypeهای تعریف شده باشد. همچنین اندازه‌ی آن نیز نباید بیشتر از 500 کیلوبایت باشد. در هر کدام از این موارد، یک خطا توسط react-toastify به کاربر نمایش داده خواهد شد.
اکنون برای استفاده‌ی از این متد دو راه وجود دارد:
الف) استفاده از آن در متد مدیریت کننده‌ی submit اطلاعات:
const handleSubmit = async event => {
event.preventDefault();
if (!isFileValid(selectedFile1) || !isFileValid(selectedFile2)) {
return;
}
در ابتدای متد مدیریت کننده‌ی handleSubmit، متد isFileValid را بر روی دو متغیر حالتی که حاوی اطلاعات فایل‌های انتخابی توسط کاربر هستند، فراخوانی میکنیم.
ب) استفاده‌ی از آن جهت غیرفعال کردن دکمه‌ی submit:
<button
disabled={
isUploading ||
!isFileValid(selectedFile1) ||
!isFileValid(selectedFile2)
}
className="btn btn-primary"
type="submit"
>
Submit
</button>
میتوان دقیقا در همان زمانیکه کاربر فایلی را انتخاب میکند نیز به انتخاب او واکنش نشان داد. چون مقدار دهی‌های متغیرهای حالت، همواره سبب رندر مجدد فرم می‌شوند و در این حالت مقدار ویژگی disabled نیز محاسبه‌ی مجدد خواهد شد، بنابراین در همان زمانیکه کاربر فایلی را انتخاب میکند، متد isFileValid نیز بر روی آن فراخوانی شده و در صورت نیاز، خطایی به او نمایش داده میشود.
نمایش درصد پیشرفت آپلود فایل‌ها
کتابخانه‌ی axios، امکان دسترسی به میزان اطلاعات آپلود شده‌ی به سمت سرور را به صورت یک رخ‌داد فراهم کرده‌است که در ادامه از آن برای نمایش درصد پیشرفت آپلود فایل‌ها استفاده میکنیم:
const startTime = Date.now();
const { data } = await axios.post(apiUrl, formData, {
headers: {
"Content-Type": "multipart/form-data"
},
onUploadProgress: progressEvent => {
const { loaded, total } = progressEvent;
const timeElapsed = Date.now() - startTime;
const uploadSpeed = loaded / (timeElapsed / 1000);
setUploadProgress({
queueProgress: Math.round((loaded / total) * 100),
uploadTimeRemaining: Math.ceil((total - loaded) / uploadSpeed),
uploadTimeElapsed: Math.ceil(timeElapsed / 1000),
uploadSpeed: (uploadSpeed / 1024).toFixed(2)
});
}
});
هر بار که متد رویدادگردان onUploadProgress فراخوانی میشود، به همراه اطلاعات شیء progressEvent است که خواص loaded آن به معنای میزان اطلاعات آپلود شده و total هم جمع کل اندازه‌ی اطلاعات در حال ارسال است. بر این اساس و همچنین زمان شروع عملیات، میتوان اطلاعاتی مانند درصد پیشرفت عملیات، مدت زمان باقیمانده، مدت زمان سپری شده و سرعت آپلود اطلاعات را محاسبه کرد و سپس توسط آن، شیء state ویژه‌ای را به روز رسانی کرد که به صورت زیر تعریف میشود:
const [uploadProgress, setUploadProgress] = useState({
queueProgress: 0,
uploadTimeRemaining: 0,
uploadTimeElapsed: 0,
uploadSpeed: 0
});
هر بار به روز رسانی state، سبب رندر مجدد UI میشود. به همین جهت متدی را برای رندر جدولی که اطلاعات شیء state فوق را نمایش میدهد، به صورت زیر تهیه میکنیم:
const showUploadProgress = () => {
const {
queueProgress,
uploadTimeRemaining,
uploadTimeElapsed,
uploadSpeed
} = uploadProgress;
if (queueProgress <= 0) {
return <></>;
}
return (
<table className="table">
<thead>
<tr>
<th width="15%">Event</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<strong>Elapsed time</strong>
</td>
<td>{uploadTimeElapsed} second(s)</td>
</tr>
<tr>
<td>
<strong>Remaining time</strong>
</td>
<td>{uploadTimeRemaining} second(s)</td>
</tr>
<tr>
<td>
<strong>Upload speed</strong>
</td>
<td>{uploadSpeed} KB/s</td>
</tr>
<tr>
<td>
<strong>Queue progress</strong>
</td>
<td>
<div
className="progress-bar progress-bar-info progress-bar-striped"
role="progressbar"
aria-valuemin="0"
aria-valuemax="100"
aria-valuenow={queueProgress}
style={{ width: queueProgress + "%" }}
>
{queueProgress}%
</div>
</td>
</tr>
</tbody>
</table>
);
};
و این متد را به این شکل در ذیل المان fieldset فرم، اضافه میکنیم تا کار رندر نهایی را انجام دهد:
هربار که state به روز میشود، مقدار شیء uploadProgress دریافت شده و بر اساس آن، 4 سطر جدول نمایش پیشرفت آپلود، تکمیل می‌شوند.
در اینجا از کامپوننت progress-bar خود بوت استرپ برای نمایش درصد آپلود فایل‌ها استفاده شده‌است. اگر style آن‌را هر بار با مقدار جدید queueProgress به روز رسانی کنیم، سبب نمایش پویای این progress-bar خواهد شد.
یک نکته: اگر می‌خواهید درصد پیشرفت آپلود را در حالت آزمایش local بهتر مشاهده کنید، دربرگه‌ی network، سرعت را بر روی 3G تنظیم کنید (مانند تصویر ابتدای بحث)؛ در غیراینصورت همان ابتدای کار به علت بالا بودن سرعت ارسال فایل‌ها، 100 درصد را مشاهده خواهید کرد.
دریافت فرم React درخواست پشتیبانی، در سمت سرور و ذخیره‌ی فایل‌های آن
بر اساس نحوه‌ی تشکیل FormData سمت کلاینت:
const formData = new FormData();
formData.append("description", description);
formData.append("file1", selectedFile1);
formData.append("file2", selectedFile2);
مدل سمت سرور معادل با آن به صورت زیر خواهد بود:
using Microsoft.AspNetCore.Http;
namespace UploadFilesSample.Models
{
public class Ticket
{
public int Id { set; get; }
public string Description { set; get; }
public IFormFile File1 { set; get; }
public IFormFile File2 { set; get; }
}
}
که در اینجا هر selectedFile سمت کلاینت، به یک IFormFile سمت سرور نگاشت میشود. نام این خواص نیز باید با نام کلیدهای اضافه شده‌ی به دیکشنری FormData، یکی باشند.
پس از آن کنترلر ذخیره سازی اطلاعات Ticket را مشاهده میکنید:
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using UploadFilesSample.Models;
namespace UploadFilesSample.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class SimpleUploadController : Controller
{
private readonly IWebHostEnvironment _environment;
public SimpleUploadController(IWebHostEnvironment environment)
{
_environment = environment;
}
[HttpPost("[action]")]
public async Task<IActionResult> SaveTicket([FromForm]Ticket ticket)
{
var file1Path = await saveFileAsync(ticket.File1);
var file2Path = await saveFileAsync(ticket.File2);
//TODO: save the ticket ... get id
return Created("", new { id = 1001 });
}
private async Task<string> saveFileAsync(IFormFile file)
{
const string uploadsFolder = "uploads";
var uploadsRootFolder = Path.Combine(_environment.WebRootPath, "uploads");
if (!Directory.Exists(uploadsRootFolder))
{
Directory.CreateDirectory(uploadsRootFolder);
}
//TODO: Do security checks ...!
if (file == null || file.Length == 0)
{
return string.Empty;
}
var filePath = Path.Combine(uploadsRootFolder, file.FileName);
using (var fileStream = new FileStream(filePath, FileMode.Create))
{
await file.CopyToAsync(fileStream);
}
return $"/{uploadsFolder}/{file.Name}";
}
}
}
توضیحات تکمیلی:
- تزریق IWebHostEnvironment در سازنده‌ی کلاس کنترلر، سبب میشود تا از طریق خاصیت WebRootPath آن، به wwwroot دسترسی پیدا کنیم و فایل‌های نهایی را در آنجا ذخیره سازی کنیم.
- همانطور که ملاحظه میکنید، هنوز هم model binding کار کرده و میتوان شیء Ticket را به نحو متداولی دریافت کرد:
public async Task<IActionResult> SaveTicket([FromForm]Ticket ticket)
ویژگی FromForm نیز مرتبط است به هدر multipart/form-data ارسالی از سمت کلاینت:
const { data } = await axios.post(apiUrl, formData, {
headers: {
"Content-Type": "multipart/form-data"
}}
});
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: UploadFilesSample.zip
برای اجرای آن، پس از صدور فرمان dotnet restore که سبب بازیابی وابستگی‌های سمت کلاینت نیز میشود، ابتدا به پوشه‌ی clientapp مراجعه کرده و فایل run.cmd را اجرا کنید. با اینکار react development server بر روی پورت 3000 شروع به کار میکند. سپس به پوشه‌ی اصلی برنامه‌ی ASP.NET Core بازگشت شده و فایل dotnet_run.bat را اجرا کنید. این اجرا سبب راه اندازی وب سرور برنامه و همچنین ارائه‌ی برنامه‌ی React بر روی پورت 5001 میشود.
