زمانیکه قرار است با فایل‌های باینری واقع در سمت سرور کار کنیم، اگر اکشن متدهای ارائه دهنده‌ی آن‌ها محافظت شده نباشند، برای نمایش و یا دریافت آن‌ها تنها کافی است از آدرس مستقیم این منابع استفاده کرد و در این حالت نیازی به رعایت هیچ نکته‌ی خاصی نیست. اما اگر اکشن متدی در سمت سرور توسط فیلتر Authorize محافظت شده باشد و روش محافظت نیز مبتنی بر کوکی‌ها نباشد، یعنی این کوکی‌ها در طی درخواست‌های مختلف، به صورت خودکار توسط مرورگر به سمت سرور ارسال نشوند، آنگاه نیاز است با استفاده از HttpClient برنامه‌های Blazor WASM، درخواست دسترسی به منبعی را به همراه برای مثال JSON Web Tokens کاربر به سمت سرور ارسال کرد و سپس فایل باینری نهایی را به صورت آرایه‌ای از بایت‌ها دریافت نمود. در این حالت با توجه به ماهیت Ajax ای این این عملیات، برای نمایش و یا دریافت این فایل‌های محافظت شده در مرورگر، نیاز به دانستن نکات ویژه‌ای است که در این مطلب به آن‌ها خواهیم پرداخت.
کدهای سمت سرور دریافت فایل PDF
در اینجا کدهای سمت سرور برنامه، نکته‌ی خاصی را به همراه نداشته و صرفا یک فایل PDF ساده (محتوای باینری) را بازگشت می‌دهد:
using Microsoft.AspNetCore.Mvc;
namespace BlazorWasmShowBinaryFiles.Server.Controllers
{
[ApiController]
[Route("api/[controller]")]
public class ReportsController : ControllerBase
{
[HttpGet("[action]")]
public IActionResult GetPdfReport()
{
//TODO: create the `sample.pdf` report file on the server
return File(virtualPath: "~/app_data/sample.pdf",
contentType: "application/pdf",
fileDownloadName: "sample.pdf");
}
}
}
که در نهایت با آدرس api/Reports/GetPdfReport در سمت کلاینت قابل دسترسی خواهد بود.
یک نکته: استفاده مستقیم از کتابخانه‌های تولید PDF در برنامه‌های سمت کاربر Blazor منطقی نیست؛ چون به ازای هر کاربر، گاهی از اوقات مجبور به ارسال بیش از 8 مگابایت اضافی مختص به فایل‌های dll. آن کتابخانه‌ی تولید PDF خواهیم شد. بنابراین بهتر است تولید PDF را در سمت سرور و در اکشن متدهای Web API انجام داد و سپس فایل نهایی تولیدی را در برنامه‌ی سمت کلاینت، دریافت و یا نمایش داد. به همین جهت در این مثال خروجی نهایی یک چنین عملیات فرضی را توسط یک اکشن متد Web API ارائه داده‌ایم که در بسیاری از موارد حتی می‌تواند توسط فیلتر Authorize نیز محافظت شده باشد.
ساخت URL برای دسترسی به اطلاعات باینری
تمام مرورگرهای جدید از ایجاد URL برای اشیاء Blob دریافتی از سمت سرور، توسط متد توکار
URL.createObjectURL پشتیبانی می‌کنند. این متد، شیء URL را از شیء window جاری دریافت می‌کند و سپس اطلاعات باینری را دریافت کرده و آدرسی را جهت دسترسی موقت به آن تولید می‌کند. حاصل آن، یک URL ویژه‌است مانند
blob:https://localhost:5001/03edcadf-89fd-48b9-8a4a-e9acf09afd67 که گشودن آن در مرورگر، یا سبب نمایش آن تصویر و یا دریافت مستقیم فایل خواهد شد.
در برنامه‌های Blazor نیاز است اینکار را توسط JS Interop آن انجام داد؛ از این جهت که API تولید یک Blob URL، صرفا توسط کدهای جاوا اسکریپتی قابل دسترسی است. به همین جهت فایل جدید Client\wwwroot\site.js را با محتوای زیر ایجاد کرده و همچنین مدخل آن‌را در به انتهای فایل Client\wwwroot\index.html، پیش از بسته شدن تگ body، اضافه می‌کنیم:
window.JsBinaryFilesUtils = {
createBlobUrl: function (byteArray, contentType) {
// The byte array in .NET is encoded to base64 string when it passes to JavaScript.
const numArray = atob(byteArray)
.split("")
.map((c) => c.charCodeAt(0));
const uint8Array = new Uint8Array(numArray);
const blob = new Blob([uint8Array], { type: contentType });
return URL.createObjectURL(blob);
},
downloadFromUrl: function (fileName, url) {
const anchor = document.createElement("a");
anchor.style.display = "none";
anchor.href = url;
anchor.download = fileName;
document.body.appendChild(anchor);
anchor.click();
document.body.removeChild(anchor);
},
downloadBlazorByteArray: function (fileName, byteArray, contentType) {
const blobUrl = this.createBlobUrl(byteArray, contentType);
this.downloadFromUrl(fileName, blobUrl);
URL.revokeObjectURL(blobUrl);
},
printFromUrl: function (url) {
const iframe = document.createElement("iframe");
iframe.style.display = "none";
iframe.src = url;
document.body.appendChild(iframe);
if (iframe.contentWindow) {
iframe.contentWindow.print();
}
},
printBlazorByteArray: function (byteArray, contentType) {
const blobUrl = this.createBlobUrl(byteArray, contentType);
this.printFromUrl(blobUrl);
URL.revokeObjectURL(blobUrl);
},
showUrlInNewTab: function (url) {
window.open(url);
},
showBlazorByteArrayInNewTab: function (byteArray, contentType) {
const blobUrl = this.createBlobUrl(byteArray, contentType);
this.showUrlInNewTab(blobUrl);
URL.revokeObjectURL(blobUrl);
},
}; توضیحات:
- زمانیکه در برنامه‌های Blazor با استفاده از متد ()HttpClient.GetByteArrayAsync آرایه‌ای از بایت‌های یک فایل باینری را دریافت می‌کنیم، ارسال آن به کدهای جاوااسکریپتی به صورت یک رشته‌ی base64 شده صورت می‌گیرد (JS Interop اینکار را به صورت خودکار انجام می‌دهد). به همین جهت در متد createBlobUrl روش تبدیل این رشته‌ی base64 دریافتی را به آرایه‌ای از بایت‌ها، سپس به یک Blob و در آخر به یک Blob URL، مشاهده می‌کنید. این Blob Url اکنون آدرس موقتی دسترسی به آرایه‌ای از بایت‌های دریافتی توسط مرورگر است. به همین جهت می‌توان از آن به عنوان src بسیاری از اشیاء HTML استفاده کرد.
- متد downloadFromUrl، کار دریافت یک Url و سپس دانلود خودکار آن‌را انجام می‌دهد. اگر به یک anchor استاندارد HTML، ویژگی download را نیز اضافه کنیم، با کلیک بر روی آن، بجای گشوده شدن این Url، مرورگر آن‌را دریافت خواهد کرد. متد downloadFromUrl کار ساخت لینک و تنظیم ویژگی‌های آن و سپس کلیک بر روی آن‌را به صورت خودکار انجام می‌دهد. از متد downloadFromUrl زمانی استفاده کنید که منبع مدنظر، محافظت شده نباشد و Url آن به سادگی در مرورگر قابل گشودن باشد.
- متد downloadBlazorByteArray همان کار متد downloadFromUrl را انجام می‌دهد؛ با این تفاوت که Url مورد نیاز توسط متد downloadFromUrl را از طریق یک Blob Url تامین می‌کند.
- متد printFromUrl که جهت دسترسی به منابع محافظت نشده طراحی شده‌است، Url یک منبع را دریافت کرده، آن‌را به یک iframe اضافه می‌کند و سپس متد print را بر روی این iframe به صورت خودکار فراخوانی خواهد کرد تا سبب ظاهر شدن صفحه‌ی پیش‌نمایش چاپ شود.
- printBlazorByteArray همان کار متد printFromUrl را انجام می‌دهد؛ با این تفاوت که Url مورد نیاز توسط متد printFromUrl را از طریق یک Blob Url تامین می‌کند.
تهیه‌ی متدهایی الحاقی جهت کار ساده‌تر با JsBinaryFilesUtils
پس از تهیه‌ی JsBinaryFilesUtils فوق، می‌توان با استفاده از کلاس زیر که به همراه متدهایی الحاقی جهت دسترسی به امکانات آن است، کار با متدهای دریافت، نمایش و چاپ فایل‌های باینری را ساده‌تر کرد و از تکرار کدها جلوگیری نمود:
using System.Threading.Tasks;
using Microsoft.JSInterop;
namespace BlazorWasmShowBinaryFiles.Client.Utils
{
public static class JsBinaryFilesUtils
{
public static ValueTask<string> CreateBlobUrlAsync(
this IJSRuntime JSRuntime,
byte[] byteArray, string contentType)
{
return JSRuntime.InvokeAsync<string>("JsBinaryFilesUtils.createBlobUrl", byteArray, contentType);
}
public static ValueTask DownloadFromUrlAsync(this IJSRuntime JSRuntime, string fileName, string url)
{
return JSRuntime.InvokeVoidAsync("JsBinaryFilesUtils.downloadFromUrl", fileName, url);
}
public static ValueTask DownloadBlazorByteArrayAsync(
this IJSRuntime JSRuntime,
string fileName, byte[] byteArray, string contentType)
{
return JSRuntime.InvokeVoidAsync("JsBinaryFilesUtils.downloadBlazorByteArray",
fileName, byteArray, contentType);
}
public static ValueTask PrintFromUrlAsync(this IJSRuntime JSRuntime, string url)
{
return JSRuntime.InvokeVoidAsync("JsBinaryFilesUtils.printFromUrl", url);
}
public static ValueTask PrintBlazorByteArrayAsync(
this IJSRuntime JSRuntime,
byte[] byteArray, string contentType)
{
return JSRuntime.InvokeVoidAsync("JsBinaryFilesUtils.printBlazorByteArray", byteArray, contentType);
}
public static ValueTask ShowUrlInNewTabAsync(this IJSRuntime JSRuntime, string url)
{
return JSRuntime.InvokeVoidAsync("JsBinaryFilesUtils.showUrlInNewTab", url);
}
public static ValueTask ShowBlazorByteArrayInNewTabAsync(
this IJSRuntime JSRuntime,
byte[] byteArray, string contentType)
{
return JSRuntime.InvokeVoidAsync("JsBinaryFilesUtils.showBlazorByteArrayInNewTab", byteArray, contentType);
}
}
} اصلاح Content Security Policy سمت سرور جهت ارائه‌ی محتوای blob
پس از دریافت فایل PDF به صورت یک blob، با استفاده از متد URL.createObjectURL می‌توان آدرس موقت محلی را برای دسترسی به آن تولید کرد و یک چنین آدرس‌هایی به صورت blob:http تولید می‌شوند. در این حالت در
Content Security Policy سمت سرور، نیاز است امکان دسترسی به تصاویر و همچنین اشیاء از نوع blob را نیز آزاد معرفی کنید:
img-src 'self' data: blob:
default-src 'self' blob:
object-src 'self' blob:
در غیراینصورت مرورگر، نمایش یک چنین تصاویر و یا اشیایی را سد خواهد کرد.
نمایش فایل PDF دریافتی از سرور، به همراه دکمه‌های دریافت، چاپ و نمایش آن در صفحه‌ی جاری
در ادامه کدهای کامل مرتبط با تصویری را که در ابتدای بحث مشاهده کردید، ملاحظه می‌کنید:
@page "/"
@using BlazorWasmShowBinaryFiles.Client.Utils
@inject IJSRuntime JSRuntime
@inject HttpClient HttpClient
<h1>Display PDF Files</h1>
<button class="btn btn-info" @onclick="handlePrintPdf">Print PDF</button>
<button class="btn btn-primary ml-2" @onclick="handleShowPdf">Show PDF</button>
<button class="btn btn-success ml-2" @onclick="handleDownloadPdf">Download PDF</button>
@if(!string.IsNullOrWhiteSpace(PdfBlobUrl))
{
<section class="card mb-5 mt-3">
<div class="card-header">
<h4>using iframe</h4>
</div>
<div class="card-body">
<iframe title="PDF Report" width="100%" height="600" src="@PdfBlobUrl" type="@PdfContentType"></iframe>
</div>
</section>
<section class="card mb-5">
<div class="card-header">
<h4>using object</h4>
</div>
<div class="card-body">
<object data="@PdfBlobUrl" aria-label="PDF Report" type="@PdfContentType" width="100%" height="100%"></object>
</div>
</section>
<section class="card mb-5">
<div class="card-header">
<h4>using embed</h4>
</div>
<div class="card-body">
<embed aria-label="PDF Report" src="@PdfBlobUrl" type="@PdfContentType" width="100%" height="100%">
</div>
</section>
}
@code
{
private const string ReportUrl = "/api/Reports/GetPdfReport";
private const string PdfContentType = "application/pdf";
private string PdfBlobUrl;
private async Task handlePrintPdf()
{
// Note: Using the `HttpClient` is useful for accessing the protected API's by JWT's (non cookie-based authorization).
// Otherwise just use the `PrintFromUrlAsync` method.
var byteArray = await HttpClient.GetByteArrayAsync(ReportUrl);
await JSRuntime.PrintBlazorByteArrayAsync(byteArray, PdfContentType);
}
private async Task handleDownloadPdf()
{
// Note: Using the `HttpClient` is useful for accessing the protected API's by JWT's (non cookie-based authorization).
// Otherwise just use the `DownloadFromUrlAsync` method.
var byteArray = await HttpClient.GetByteArrayAsync(ReportUrl);
await JSRuntime.DownloadBlazorByteArrayAsync("report.pdf", byteArray, PdfContentType);
}
private async Task handleShowPdf()
{
// Note: Using the `HttpClient` is useful for accessing the protected API's by JWT's (non cookie-based authorization).
// Otherwise just use the `ReportUrl` as the `src` of the `iframe` directly.
var byteArray = await HttpClient.GetByteArrayAsync(ReportUrl);
PdfBlobUrl = await JSRuntime.CreateBlobUrlAsync(byteArray, PdfContentType);
}
// Tips:
// 1- How do I enable/disable the built-in pdf viewer of FireFox
// https://support.mozilla.org/en-US/kb/disable-built-pdf-viewer-and-use-another-viewer
// 2- How to configure browsers to use the Adobe PDF plug-in to open PDF files
// https://helpx.adobe.com/acrobat/kb/pdf-browser-plugin-configuration.html
// https://helpx.adobe.com/acrobat/using/display-pdf-in-browser.html
// 3- Microsoft Edge is gaining new PDF reader features within the Windows 10 Fall Creator’s Update (version 1709).
} توضیحات:
- پس از تهیه‌ی JsBinaryFilesUtils و متدهای الحاقی متناظر با آن، اکنون تنها کافی است با استفاده از متد ()HttpClient.GetByteArrayAsync، فایل PDF ارائه شده‌ی توسط یک اکشن متد را به صورت آرایه‌ای از بایت‌ها دریافت و سپس به متدهای چاپ (PrintBlazorByteArrayAsync) و دریافت (DownloadBlazorByteArrayAsync) آن ارسال کنیم.
- در مورد نمایش آرایه‌ای از بایت‌های دریافتی، وضعیت کمی متفاوت است. ابتدا باید توسط متد CreateBlobUrlAsync، آدرس موقتی این آرایه را در مرورگر تولید کرد و سپس این آدرس را برای مثال به src یک iframe انتساب دهیم تا PDF را با استفاده از امکانات توکار مرورگر، نمایش دهد.
کدهای کامل این مطلب را از اینجا می‌توانید دریافت کنید: BlazorWasmShowBinaryFiles.zip 
