اشتراکها
اشتراکها
پروژه River Trail
اشتراکها
مستندات EF Core
This documentation is for EF Core. For EF6.x and earlier release see http://msdn.com/data/ef
اگر با Elasticsearch کار کرده باشید میدانید که تولید Elasticsearch DSL Query کمی پیچیده است و عموما باید به صورت manual این Query هارو تولید کنید.
با استفاده از این پکیج برای تولید این Queryها میتوانید از syntax پشتیبانی شده در Gridify استفاده کنید که کار ساخت Query برای Elasticsearch را ساده میکند.
مثال:
await client.SearchAsync<User>(s => s .Index("users") .ApplyFiltering("emailAddress = John"));
query زیر را تولید میکند:
GET users/_search { "query": { "term": { "emailAddress.keyword": { "value": "test@test.com" } } } }
نظرات مطالب
Asp.Net Identity #1
نکتهای رو خیلیها به اون دقت نمیکنند و اون پایان توسعهی نگارش 2x این کتابخانه هست. الان تمام همت و تلاش مایکروسافت بر روی نگارش 3 آن در GitHub هست به صورت سورس باز البته (قسمت commits و قسمت issues آنرا بررسی کنید). یعنی اگر قصد شروع پروژهای را دارید، شروع کردن با فناوری که دیگر پشتیبانی ندارد، اشتباه و اتلاف وقت هست.
Identity 2.0 is no longer under primary development. No new features will be added, only bugs will be considered
در مطلب «فعال سازی عملیات CRUD در Kendo UI Grid» با نحوهی تعریف مقدماتی اعتبارسنجی فیلدهای تعریف شده، آشنا شدید:
در ادامه نگاهی خواهیم داشت به جزئیات تکمیلی امکانات اعتبارسنجی ورودیهای کاربر در Kendo UI.
Kendo UI Validation و HTML 5
در HTML 5 امکان تعریف نوعهای خاص کنترلهای ورودی کاربر مانند email، url، number، range، date، search و color وجود دارد. برای مثال در اینجا اگر کاربر تاریخ غیرمعتبری را وارد کند، مرورگر پیام اعتبارسنجی متناظری را به او نمایش خواهد داد. همچنین در HTML 5 امکان افزودن ویژگی required نیز به کنترلهای ورودی پیش بینی شدهاست. اما باید درنظر داشت که مرورگرهای قدیمی از این امکانات پشتیبانی نمیکنند. در این حالت Kendo UI با تشویق استفاده از روش معرفی شده در HTML 5، با آن یکپارچه شده و همچنین این قابلیتهای اعتبارسنجی HTML 5 را در مرورگرهای قدیمی نیز میسر میکند. Kendo UI Validation جزو نسخهی سورس باز Kendo UI با مجوز Apache نیز میباشد.
نمونهای از امکانات اعتبارسنجی توکار HTML 5 را در اینجا مشاهده میکنید:
یکپارچه سازی اعتبارسنجی Kendo UI با اعتبارسنجی HTML 5
در اینجا یک فرم تشکیل شده با ساختار HTML 5 را ملاحظه میکنید. هر دو فیلد ورودی، با ویژگی استاندارد required مزین شدهاند. همچنین توسط ویژگی type، ورودی دوم جهت دریافت آدرس ایمیل معرفی شدهاست.
چون فیلد دوم دارای دو اعتبارسنجی تعریف شده است، دارای دو ویژگی *-data برای تعریف پیامهای اعتبارسنجی متناظر نیز میباشد. الگوی تعریف آنها data-[rule]-msg است.
تنها کاری که جهت یکپارچه سازی امکانات اعتبارسنجی Kendo UI با اعتبارسنجی استاندارد HTML 5 باید انجام داد، فراخوانی متد kendoValidator بر روی ناحیهی مشخص شده است.
تعیین محل نمایش پیامهای اعتبارسنجی
پیامهای اعتبارسنجی Kendo UI به صورت خودکار در کنار فیلد متناظر با آن نمایش داده میشوند. اما اگر نیاز به تعیین مکان دستی آنها وجود داشت (جهت خوانایی بهتر) باید به نحو ذیل عمل کرد:
در اینجا span با کلاس k-invalid-msg و ویژگی data-for که به name کنترل ورودی اشاره میکند، محل نمایش پیام اعتبارسنجی متناظر با فیلد name خواهد بود.
تعریف سراسری پیامهای اعتبارسنجی
در مثال فوق، به ازای تک تک فیلدهای ورودی، پیام اعتبارسنجی متناظر با required وارد شد. میتوان این پیامها را حذف کرد و در قسمت messages متد kendoValidator قرار داد:
- به این صورت پیامهای اعتبارسنجی required و email، به صورت یکسانی به تمام المانهای دارای این ویژگیها اعمال خواهند شد.
- در این پیامها {0} با مقدار ویژگی name فیلد ورودی متناظر جایگزین میشود.
- اگر هم در markup و هم در تعاریف kendoValidator، پیامهای اعتبارسنجی تعریف شوند، حق تقدم با تعاریف markup خواهد بود.
اعتبارسنجی سفارشی سمت کاربر
علاوه بر امکانات استاندارد HTML 5، امکان تعریف دستورهای اعتبارسنجی سفارشی نیز وجود دارد:
- همانطور که ملاحظه میکنید، برای تعریف منطق اعتبارسنجی سفارشی، باید از خاصیت rules ورودی متد kendoValidator شروع کرد. در اینجا نام یک متد callback دلخواهی را وارد کرده و سپس بر اساس منطق اعتبارسنجی مورد نظر، باید true/false را بازگشت داد. برای نمونه در این مثال اگر کاربر در فیلد نام، عدد وارد کند، ورودی او مورد قبول واقع نخواهد شد.
- باید دقت داشت که اگر بررسی input.is صورت نگیرد، منطق تعریف شده به تمام کنترلهای صفحه اعمال میشود.
- پیام متناظر با این دستور سفارشی جدید، در قسمت messages، دقیقا بر اساس نام callback method تعریف شده در قسمت rules باید تعریف شود.
فراخوانی دستی اعتبارسنجی یک فرم
در حالت پیش فرض، با کلیک بر روی دکمهی ارسال، اعتبارسنجی کلیه عناصر فرم به صورت خودکار انجام میشود. اگر بخواهیم در این بین یک پیام سفارشی را نیز نمایش دهیم میتوان به صورت زیر عمل کرد:
در اینجا رخداد submit فرم بازنویسی شده و متد validate آن بر اساس kendoValidator تعریف شده، به صورت دستی فراخوانی میشود.
اعتبارسنجی سفارشی در DataSource
در تعریف فیلدهای مدل DataSource، امکان تعریف اعتبارسنجیهای پیش فرضی مانند rquired، min، max و امثال آن وجود دارد که نمونهای از آنرا در بحث فعال سازی CRUD در Kendo UI Grid مشاهده کردید:
برای تعریف اعتبارسنجی سفارشی در اینجا، همانند متد kendoValidator نیاز است یک یا چند callback متد سفارشی را طراحی کرد:
نام این متد که نهایتا true/false بر میگرداند، اختیاری است. نام کنترل جاری همان نام فیلد متناظر است (جهت محدود کردن بازهی اعمال منطق اعتبارسنجی). برای مقدار دهی پیام اعتبارسنجی از متد input.attr و الگوی data-[validationRuleName]-msg استفاده میشود. ضمنا به هر تعداد لازم میتوان در اینجا custom rule تعریف کرد.
متد ()input.val مقدار کنترل جاری را بر میگرداند. برای دسترسی به مقدار سایر کنترلها میتوان از روش ()fieldName").val#")$ استفاده کرد.
fields: { "Price": { type: "number", validation: { required: true, min: 1 } } }
Kendo UI Validation و HTML 5
در HTML 5 امکان تعریف نوعهای خاص کنترلهای ورودی کاربر مانند email، url، number، range، date، search و color وجود دارد. برای مثال در اینجا اگر کاربر تاریخ غیرمعتبری را وارد کند، مرورگر پیام اعتبارسنجی متناظری را به او نمایش خواهد داد. همچنین در HTML 5 امکان افزودن ویژگی required نیز به کنترلهای ورودی پیش بینی شدهاست. اما باید درنظر داشت که مرورگرهای قدیمی از این امکانات پشتیبانی نمیکنند. در این حالت Kendo UI با تشویق استفاده از روش معرفی شده در HTML 5، با آن یکپارچه شده و همچنین این قابلیتهای اعتبارسنجی HTML 5 را در مرورگرهای قدیمی نیز میسر میکند. Kendo UI Validation جزو نسخهی سورس باز Kendo UI با مجوز Apache نیز میباشد.
نمونهای از امکانات اعتبارسنجی توکار HTML 5 را در اینجا مشاهده میکنید:
<input type="text" name="firstName" required /> <input type="text" name="twitter" pattern="https?://(?:www\.)?twitter\.com/.+i" /> <input type="number" name="age" min="1" max="42" /> <input type="number" name="age" min="1" max="100" step="2" /> <input type="url" name="url" /> <input type="email" name="email" />
یکپارچه سازی اعتبارسنجی Kendo UI با اعتبارسنجی HTML 5
در اینجا یک فرم تشکیل شده با ساختار HTML 5 را ملاحظه میکنید. هر دو فیلد ورودی، با ویژگی استاندارد required مزین شدهاند. همچنین توسط ویژگی type، ورودی دوم جهت دریافت آدرس ایمیل معرفی شدهاست.
چون فیلد دوم دارای دو اعتبارسنجی تعریف شده است، دارای دو ویژگی *-data برای تعریف پیامهای اعتبارسنجی متناظر نیز میباشد. الگوی تعریف آنها data-[rule]-msg است.
<div class="k-rtl"> <form id="testView"> <label for="firstName">نام</label> <input id="firstName" name="firstName" type="text" class="k-textbox" required validationmessage="لطفا نامی را وارد کنید"> <br> <label for="emailId">آدرس پست الکترونیک</label> <input id="emailId" name="emailId" type="email" dir="ltr" required class="k-textbox" data-required-msg="لطفا ایمیلی را وارد کنید." data-email-msg="ایمیل وارد شده معتبر نیست."> <br> <input type="submit" class="k-button" value="ارسال"> </form> </div> <script type="text/javascript"> $(function () { $("form#testView").kendoValidator(); }); </script>
تعیین محل نمایش پیامهای اعتبارسنجی
پیامهای اعتبارسنجی Kendo UI به صورت خودکار در کنار فیلد متناظر با آن نمایش داده میشوند. اما اگر نیاز به تعیین مکان دستی آنها وجود داشت (جهت خوانایی بهتر) باید به نحو ذیل عمل کرد:
<input type="text" id="name" name="name" required> <span class="k-invalid-msg" data-for="name"></span>
تعریف سراسری پیامهای اعتبارسنجی
در مثال فوق، به ازای تک تک فیلدهای ورودی، پیام اعتبارسنجی متناظر با required وارد شد. میتوان این پیامها را حذف کرد و در قسمت messages متد kendoValidator قرار داد:
<script type="text/javascript"> $(function () { $("form#testView").kendoValidator({ messages: { // {0} would be replaced with the input element's name required: '{0} را تکمیل کنید.', email: 'ایمیل وارد شده معتبر نیست.' } }); }); </script>
- در این پیامها {0} با مقدار ویژگی name فیلد ورودی متناظر جایگزین میشود.
- اگر هم در markup و هم در تعاریف kendoValidator، پیامهای اعتبارسنجی تعریف شوند، حق تقدم با تعاریف markup خواهد بود.
اعتبارسنجی سفارشی سمت کاربر
علاوه بر امکانات استاندارد HTML 5، امکان تعریف دستورهای اعتبارسنجی سفارشی نیز وجود دارد:
<script type="text/javascript"> $(function () { $("form#testView").kendoValidator({ rules: { customRule1: function (input) { if (!input.is("[id=firstName]")) return true; var re = /^[A-Za-z]+$/; return re.test(input.val()); } //, customRule1: …. }, messages: { // {0} would be replaced with the input element's name required: '{0} را تکمیل کنید.', email: 'ایمیل وارد شده معتبر نیست.', customRule1: 'اعداد مجاز نیستند.' } }); }); </script>
- همانطور که ملاحظه میکنید، برای تعریف منطق اعتبارسنجی سفارشی، باید از خاصیت rules ورودی متد kendoValidator شروع کرد. در اینجا نام یک متد callback دلخواهی را وارد کرده و سپس بر اساس منطق اعتبارسنجی مورد نظر، باید true/false را بازگشت داد. برای نمونه در این مثال اگر کاربر در فیلد نام، عدد وارد کند، ورودی او مورد قبول واقع نخواهد شد.
- باید دقت داشت که اگر بررسی input.is صورت نگیرد، منطق تعریف شده به تمام کنترلهای صفحه اعمال میشود.
- پیام متناظر با این دستور سفارشی جدید، در قسمت messages، دقیقا بر اساس نام callback method تعریف شده در قسمت rules باید تعریف شود.
فراخوانی دستی اعتبارسنجی یک فرم
در حالت پیش فرض، با کلیک بر روی دکمهی ارسال، اعتبارسنجی کلیه عناصر فرم به صورت خودکار انجام میشود. اگر بخواهیم در این بین یک پیام سفارشی را نیز نمایش دهیم میتوان به صورت زیر عمل کرد:
<script type="text/javascript"> $(function () { $("form#testView").submit(function (event) { event.preventDefault(); var validator = $("form#testView").data("kendoValidator"); if (validator.validate()) { alert("validated!"); } else { alert("There is invalid data in the form."); } }); $("form#testView").kendoValidator(); }); </script>
اعتبارسنجی سفارشی در DataSource
در تعریف فیلدهای مدل DataSource، امکان تعریف اعتبارسنجیهای پیش فرضی مانند rquired، min، max و امثال آن وجود دارد که نمونهای از آنرا در بحث فعال سازی CRUD در Kendo UI Grid مشاهده کردید:
fields: { "serviceName": { type: "string", defaultValue: "Inspection", editable: true, nullable: false, validation: { /*...*/ } }, // ... }
schema: { model: { id: "ProductID", fields: { ProductID: { editable: false, nullable: true }, ProductName: { validation: { required: true, custom1: function (input) { if (input.is("[name='ProductName']") && input.val() != "") { input.attr("data-custom1-msg", "نام محصول باید با حرف بزرگ انگلیسی شروع شود"); return /^[A-Z]/.test(input.val()); } return true; } // ,custom2: ... } }, UnitPrice: { type: "number", validation: { required: true, min: 1} }, Discontinued: { type: "boolean" }, UnitsInStock: { type: "number", validation: { min: 0, required: true} } } } }
متد ()input.val مقدار کنترل جاری را بر میگرداند. برای دسترسی به مقدار سایر کنترلها میتوان از روش ()fieldName").val#")$ استفاده کرد.
پاسخ به بازخوردهای پروژهها
نحوه دریافت تعداد صفحات گزارش در هدر یا فوتر بصورت عدد
- مراجعه کنید به مثال CustomHeaderFooter ، فایل CustomFooter.cs، روال ClosingDocument آن. در اینجا عدد writer.PageNumber - 1 مساوی تعداد کل صفحات است.
- یا مراجعه کنید به مثال InlineProviders . در اینجا data.TotalPagesCountImage یک تصویر است که به صورت خودکار توسط برنامه در آخر کار مقدار دهی میشود. عددی که در آن درج میشود معادل تعداد کل صفحات است.
- و یا در مثال HtmlHeader ، تگ سفارشی به نام TotalPagesNumber به صورت خودکار در پایان کار تهیه گزارش توسط برنامه با تعداد کل صفحات مقدار دهی خواهد شد.
- یا مراجعه کنید به مثال InlineProviders . در اینجا data.TotalPagesCountImage یک تصویر است که به صورت خودکار توسط برنامه در آخر کار مقدار دهی میشود. عددی که در آن درج میشود معادل تعداد کل صفحات است.
- و یا در مثال HtmlHeader ، تگ سفارشی به نام TotalPagesNumber به صورت خودکار در پایان کار تهیه گزارش توسط برنامه با تعداد کل صفحات مقدار دهی خواهد شد.
زمانیکه قرار است با فایلهای باینری واقع در سمت سرور کار کنیم، اگر اکشن متدهای ارائه دهندهی آنها محافظت شده نباشند، برای نمایش و یا دریافت آنها تنها کافی است از آدرس مستقیم این منابع استفاده کرد و در این حالت نیازی به رعایت هیچ نکتهی خاصی نیست. اما اگر اکشن متدی در سمت سرور توسط فیلتر Authorize محافظت شده باشد و روش محافظت نیز مبتنی بر کوکیها نباشد، یعنی این کوکیها در طی درخواستهای مختلف، به صورت خودکار توسط مرورگر به سمت سرور ارسال نشوند، آنگاه نیاز است با استفاده از HttpClient برنامههای Blazor WASM، درخواست دسترسی به منبعی را به همراه برای مثال JSON Web Tokens کاربر به سمت سرور ارسال کرد و سپس فایل باینری نهایی را به صورت آرایهای از بایتها دریافت نمود. در این حالت با توجه به ماهیت Ajax ای این این عملیات، برای نمایش و یا دریافت این فایلهای محافظت شده در مرورگر، نیاز به دانستن نکات ویژهای است که در این مطلب به آنها خواهیم پرداخت.
کدهای سمت سرور دریافت فایل PDF
که در نهایت با آدرس api/Reports/GetPdfReport در سمت کلاینت قابل دسترسی خواهد بود.
ساخت 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، اضافه میکنیم:
توضیحات:
- زمانیکه در برنامههای 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 فوق، میتوان با استفاده از کلاس زیر که به همراه متدهایی الحاقی جهت دسترسی به امکانات آن است، کار با متدهای دریافت، نمایش و چاپ فایلهای باینری را سادهتر کرد و از تکرار کدها جلوگیری نمود:
اصلاح Content Security Policy سمت سرور جهت ارائهی محتوای blob
پس از دریافت فایل PDF به صورت یک blob، با استفاده از متد URL.createObjectURL میتوان آدرس موقت محلی را برای دسترسی به آن تولید کرد و یک چنین آدرسهایی به صورت blob:http تولید میشوند. در این حالت در Content Security Policy سمت سرور، نیاز است امکان دسترسی به تصاویر و همچنین اشیاء از نوع blob را نیز آزاد معرفی کنید:
در غیراینصورت مرورگر، نمایش یک چنین تصاویر و یا اشیایی را سد خواهد کرد.
نمایش فایل PDF دریافتی از سرور، به همراه دکمههای دریافت، چاپ و نمایش آن در صفحهی جاری
در ادامه کدهای کامل مرتبط با تصویری را که در ابتدای بحث مشاهده کردید، ملاحظه میکنید:
توضیحات:
- پس از تهیهی JsBinaryFilesUtils و متدهای الحاقی متناظر با آن، اکنون تنها کافی است با استفاده از متد ()HttpClient.GetByteArrayAsync، فایل PDF ارائه شدهی توسط یک اکشن متد را به صورت آرایهای از بایتها دریافت و سپس به متدهای چاپ (PrintBlazorByteArrayAsync) و دریافت (DownloadBlazorByteArrayAsync) آن ارسال کنیم.
- در مورد نمایش آرایهای از بایتهای دریافتی، وضعیت کمی متفاوت است. ابتدا باید توسط متد CreateBlobUrlAsync، آدرس موقتی این آرایه را در مرورگر تولید کرد و سپس این آدرس را برای مثال به src یک iframe انتساب دهیم تا PDF را با استفاده از امکانات توکار مرورگر، نمایش دهد.
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید: BlazorWasmShowBinaryFiles.zip
کدهای سمت سرور دریافت فایل 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"); } } }
یک نکته: استفاده مستقیم از کتابخانههای تولید 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