در یک نگاه کلی، ASP.NET Web API OData بر روی ASP.NET Web API سوار شده است و مزیتهای پایه آن را به صورت کامل دارد، شامل Routing، داشتن Action Filterها، احراز هویت و ... همچنین استاندارد OData بر روی استاندارد Rest سوار شده است و مزیتهای پایه ای آن را دارا میباشد. اما در کنار اینها OData ویژگی هایی دارد، مانند batch request که در پستهای بعدی توضیح خواهم داد. و همچنین با داشتن Metadata و استفاده از یک OData Client که در JavaScript | C# | Objective-C و ... کتاب خانههای مختلفی برای آنها وجود دارد، شما میتوانید به سادگی Proxy سمت کلاینت رو Generate کرده و متدها را فراخوانی کنید. همچنین سازگاری استاندارد دیتا گرید ها، کمبو باکسها و کنترلهای گوناگون از فریم ورکهای مختلف از دیگر ویژگیهای OData است. بخاطر مبتنی بر Rest بودن Web API OData امکان فراخوانی آن با jQuery نیز وجود دارد؛ اما استفاده از OData Clientها میتواند سادگی کار را به شدت بالا ببرد. سازگاری با Owin و امکان اجرای آن بر روی ASP.NET Core نیز از دیگر موارد مهمی است که باید به آن اشاره کنم. در ضمن این استاندارد محدود به مایکروسافت نبوده و در سایر زبانها و پلتفرمها نیز شناخته شده میباشد. برای مثال امکان نوشتن یک OData Server در جاوا یا جاوا اسکریپت نیز وجود دارد.
در دو مقاله پیشین ^ ، ^ به بررسی نوشتن افزونه در مرورگر کروم پرداختیم و اینبار قصد داریم همان پروژه را برای فایرفاکس پیاده کنیم. پس در مورد کدهای تکراری توضیحی داده نخواهد شد و برای فهم آن میتوانید به دو مقاله قبلی رجوع کنید. همهی ما فایرفاکس را به خوبی میشناسیم. اولین باری که این مرورگر آمد سرو صدای زیادی به پا کرد و بازار وسیعی از مرورگرها را که در چنگ IE بود، به دست آورد . این سر و صدا بیشتر به خاطر امنیت و کارآیی بالای این مرورگر، استفاده از آخرین فناوریهای تحت وب و دوست داشتنی برای طراحان وب بود. همچنین یکی دیگر از مهمترین ویژگیهای آن، امکان سفارشی سازی آن با افزونهها extensions یا addon بود که این ویژگی در طول این سالها تغییرات زیادی به خود دیده است. در مورد افزونه نویسی برای فایرفاکس در سطح نت مطالب زیادی وجود دارند که همین پیشرفتهای اخیر در مورد افزونهها باعث شده خیلی از این مطالب به روز نباشند. اگر در مقاله پیشین فکر میکنید که کروم چقدر در نوشتن افزونه جذابیت دارد و امکانات خوبی را در اختیار شما میگذارد، الان دیگر وقت آن است که نظر خودتان را عوض کنید و فایرفاکس را نه تنها یک سرو گردن بلکه بیشتر از این حرفها بالاتر بدانید.
شرکت موزیالا برای قدرتمندی و راحتی کار طراحان یک sdk طراحی کرده است است و شما با استفاده از کدهای موجود در این sdk قادرید کارهای زیادی را انجام دهید. برای نصب این sdk باید پیش نیازهایی بر روی سیستم شما نصب باشد:
- نصب پایتون 2.5 یا 2.6 یا 2.7 که فعلا در سایت آن، نسخهی 2.7 در دسترس هست. توجه داشته باشید که هنوز برای نسخهی 3 پایتون پشتیبانی صورت نگرفته است.
- آخرین نسخهی sdk را هم میتوانید از این آدرس به صورت zip و یا از این آدرس به صورت tar دانلود کنید و در صورتیکه دوست دارید به سورس آن دسترسی داشته باشید یا اینکه از سورسهای مشارکت شده یا غیر رسمی استفاده کنید، از این صفحه آن را دریافت کنید.
بعد از دانلود sdk به شاخهی bin رفته و فایل activate.bat را اجرا کنید. موقعی که فایل activate اجرا شود، باید چنین چیزی دیده شود:
(C:\Users\aym\Downloads\addon-sdk-1.17) C:\Users\aym\Downloads\addon-sdk-1.17\bin>
برای سیستمهای عامل Linux,FreeBSD,OS X دستورات زیر را وارد کنید:
اگر یک کاربر پوستهی bash هستید کلمه زیر را در کنسول برای اجرای activate بزنید:
source bin/activate
bash bin/activate
(addon-sdk)~/mozilla/addon-sdk >
آغاز به کار
برای شروع، فایلهای زیادی باید ساخته شوند، ولی نگران نباشید cfx این کار را برای شما خواهد کرد. دستورات زیر را جهت ساخت یک پروژه خالی اجرا کنید:
mkdir fxaddon cd fxaddon cfx init
* lib directory created * data directory created * test directory created * doc directory created * README.md written * package.json written * test/test-main.js written * lib/main.js written * doc/main.md written Your sample add-on is now ready for testing: try "cfx test" and then "cfx run". Have fun!"
در این پوشه یک فایل به اسم package.json هم وجود دارد که اطلاعات زیر داخلش هست:
{ "name": "fxaddon", "title": "fxaddon", "id": "jid1-QfyqpNby9lTlcQ", "description": "a basic add-on", "author": "", "license": "MPL 2.0", "version": "0.1" }
{ "name": "dotnettips", "title": ".net Tips Updater", "id": "jid1-QfyqpNby9lTlcQ", "description": "This extension keeps you updated on current activities on dotnettips.info", "author": "yeganehaym@gmail.com", "license": "MPL 2.0", "version": "0.1" }
رابطهای کاربری
Action Button و Toggle Button
فایل main.js را در دایرکتوری lib باز کنید:موقعی که در کروم افزونه مینوشتیم امکانی به اسم browser action داشتیم که در اینجا با نام action button شناخته میشود. در اینجا باید کدها را require کرد، همان کاری در خیلی از زبانها مثلا مثل سی برای صدا زدن سرآیندها میکنید. مثلا برای action button اینگونه است:
var button= require('sdk/ui/button/action');
buttons.ActionButton({...});
کد زیر یک toggle button را برای فایرفاکس میسازد که با کلیک بر روی آن، صفحهی popup.htm به عنوان یک پنل روی آن رندر میشود:
var tgbutton = require('sdk/ui/button/toggle'); var panels = require("sdk/panel"); var self = require("sdk/self"); var button = tgbutton.ToggleButton({ id: "updaterui", label: ".Net Updater", icon: { "16": "./icon-16.png", "32": "./icon-32.png", "64": "./icon-64.png" }, onChange: handleChange }); var panel = panels.Panel({ contentURL: self.data.url("./popup.html"), onHide: handleHide }); function handleChange(state) { if (state.checked) { panel.show({ position: button }); } } function handleHide() { button.state('window', {checked: false}); }
tgbutton.ToggleButton
require('sdk/ui/button/toggle').ToggleButton
در خط بعدی به تعریف یک شیء از نوع toggle button به اسم button میپردازیم و خصوصیاتی که به این دکمه داده ایم، مانند یک کد شناسایی، یک برچسب که به عنوان tooltip نمایش داده خواهد شد و آیکنهایی در اندازههای مختلف که در هرجایی کاربر آن دکمه را قرار داد، در اندازهی مناسب باشد و نهایتا به تعریف یک رویداد میپردازیم. تابع handlechange زمانی صدا زده میشود که در وضعیت دکمهی ایجاد شده تغییری حاصل شود. در خط بعدی شیء panel را به صورت global میسازیم. شیء self دسترسی ما را به اجزا یا فایلهای افزونه خودمان فراهم میکند که در اینجا دسترسی ما به فایل html در شاخهی data میسر شده است و مقدار مورد نظر را در contentURL قرار میدهد. نهایتا هم برای رویداد onhide تابعی را در نظر میگیریم تا موقعی که پنجره بسته شد بتوانیم وضعیت toggle button را به حالت قبلی بازگردانیم و حالت فشرده نباشد. چرا که این دکمه تنها با کلیک ماوس به حالت فشرده و حالت معمولی سوییچ میکند. پس اگر کاربر با کلیک بر روی صفحهی مرورگر پنجره را ببندد، دکمه در همان وضعیت فشرده باقی میماند.
همانطور که گفتیم تابع handlechnage موقعی رخ میدهد که در وضعیت دکمه، تغییری رخ دهد و نمیدانیم که این وضعیت فشرده شدن دکمه هست یا از حالت فشرده خارج شده است. پس با استفاده از ویژگی checked بررسی میکنم که آیا دکمهای فشرده شده یا خیر؛ اگر برابر true بود یعنی کاربر روی دکمه، کلیک کرده و دکمه به حالت فشرده رفته، پس ما هم پنل را به آن نشان میدهیم و خصوصیات دلخواهی را برای مشخص کردن وضعیت پنل نمایشی به آن پاس میکنیم. خصوصیت یا پارامترهای زیادی را میتوان در حین ساخت پنل برای آن ارسال کرد. با استفاده از خصوصیت position محل نمایش پنجره را مشخص میکنیم. در صورتی که ذکر نشود پنجره در وسط مرورگر ظاهر خواهد شد.
تابع onhide زمانی رخ میدهد که به هر دلیلی پنجره بسته شده باشد که در بالا یک نمونهی آن را عرض کردیم. ولی اتفاقی که میافتد، وضعیت تابع را با متد state تغییر میدهیم و خصوصیت checked آن را false میکنیم. بجای پارامتر اولی، دو گزینه را میتوان نوشت؛ یکی window و دیگری tab است. اگر شما گزینه tab را جایگزین کنید، اگر در یک تب دکمه به حالت فشرده برود و به تب دیگر بروید و باعث بسته شدن پنجره بشوید، دکمه تنها در تبی که فعال است به حالت قبلی باز میگردد و تب اولی همچنان حالت خود را حفظ خواهد کرد پس مینویسیم window تا این عمل در کل پنجره اعمال شود.
Context Menus
برای ساخت منوی کانتکست از کد زیر استفاده میکنیم:
var contextMenu = require("sdk/context-menu"); var home = contextMenu.Item({ label: "صفحه اصلی", data: "https://www.dntips.ir/" }); var postsarchive = contextMenu.Item({ label: "مطالب سایت", data: "https://www.dntips.ir/postsarchive" }); var menuItem = contextMenu.Menu({ label: "Open .Net Tips", context: contextMenu.PageContext(), items: [home, postsarchive], image: self.data.url("icon-16.png"), contentScript: 'self.on("click", function (node, data) {' + ' window.location.href = data;' + '});' });
SelectorContext("img")
SelectorContext("img,a[href]")
آن منوهایی که با متد item ایجاد شدهاند منوهایی هستند که با کلیک کاربر اجرا میشوند؛ ولی والدی که با متد menu ایجاد شده است، برای منویی است که زیر منو دارد و خودش لزومی به اجرای کد ندارد. پس اگر منویی میسازید که زیرمنو ندارد و خودش قرار است کاری را انجام دهد، به صورت همان item بنویسید که پایینتر نمونهی آن را خواهید دید.
الان مشکلی که ایجاد میشود این است که موقعی که سایت را باز میکند، در همان تبی رخ میدهد که فعال است و اگر کاربر بر روی صفحهی خاصی باشد، آن صفحه به سمت سایت مقصد رفته و سایت فعلی از دست میرود. روش صحیحتر اینست که تبی جدید بار شود و آدرس مقصد در آن نمایش یابد. پس باید از روشی استفاده کنیم که رویداد کلیک توسط کد خود افزونه مدیریت شود، تا با استفاده از شیء tab، یک تب جدید با آدرسی جدید ایجاد کنیم. پس کد را با کمی تغییر مینویسیم:
var tabs = require("sdk/tabs"); var menuItem = contextMenu.Menu({ label: "Open .Net Tips", context: contextMenu.PageContext(), items: [home, postsarchive], image: self.data.url("icon-16.png"), contentScript: 'self.on("click", function (node, data) {' + ' self.postMessage(data);' + '});', onMessage: function (data) { tabs.open(data); } });
بگذارید کد زیر را هم جهت سرچ مطالب بر روی سایت پیاده کنیم:
var Url="https://www.dntips.ir/search?term="; var searchMenu = contextMenu.Item({ label: "search for", context: [contextMenu.PredicateContext(checkText),contextMenu.SelectionContext()], image: self.data.url("icon-16.png"), contentScript: 'self.on("click", function () {' + ' var text = window.getSelection().toString();' + ' if (text.length > 20)' + ' text = text.substr(0, 20);' + ' self.postMessage(text);'+ '})', onMessage: function (data) { tabs.open(Url+data); } }); function checkText(data) { if(data.selectionText === null) return false; console.log('selectionText: ' + data.selectionText); //handle showing or hiding of menu items based on the text content. menuItemToggle(data.selectionText); return true; }; function menuItemToggle(text){ var searchText="جست و جو برای "; searchMenu.label=searchText+text; };
در کل موقع ایجاد منو تابع checkText اجرا شده و متن انتخابی را خوانده به عنوان یک آرگومان برای تابع menuItemToggle ارسال میکند و به رشته "جست و جو برای" میچسباند. در خود پارامترهای آیتم اصلی، گزینه content scrip، با استفاده از جاوااسکریپت، متن انتخاب شده را دریافت کرده و با استفاده از متد postmessage برای تابع onMessage ارسال کرده و با ساخت یک تب و چسباندن عبارت به آدرس جست و جو سایت، کاربر را به صفحه مورد نظر هدایت کرده و عمل جست و جو در سایت انجام میگیرد.
در قسمت آینده موارد بیشتری را در مورد افزونه نویسی در فایرفاکس بررسی خواهیم کرد و افزونه را تکمیل خواهیم کرد
حتما مقاله ای را برای این در ادامه تهیه خواهم کرد تا به طور کامل این مباحث رو پوشش دهد. فعلا شاید این
بتواند کمک کند.در ضمن سرعت این برنامههای نوشته شده با Cordova نسبت به برنامههای بومی اندکی کم است (مزایا و معایب خود را دارد) و برای اینکه سورس در دسترس نباشد روش هایی برای آن در نظر گرفته شده.
با رشد دنیای تکنولوژی، وسائل هوشمند همراه نیز به سرعت پیشرفتهتر شدند. در این میان با گسترش زیرساخت اینترنت، رشد شبکههای اجتماعی نیز چشمگیر بوده است. یکی از بهترین اینها، شبکههای تلگرام میباشد که با بهره گیری از سرورهای ابری، امنیت و سرعت را برای کاربران به ارمغان آورده است.
چندی پیش موسسان تلگرام با معرفی APIهای کاربردی، به توسعه کنندگان اجازه دادند که با بهره گیری از بستر این شبکه، اقدام به تولید اینترفیسی به اسم بات کنند که با دریافت دستورات سفارشی، عملیات خاصی را انجام دهد.
در واقع تلگرام و متدهای ارائه شده، یک راه ارتباطی بین کاربران و برنامههای تولید شده را ایجاد کردند که با قدری ذوق و سلیقه، شاهد باتهای جالب و کاربردی هستیم.
در این مقاله سعی شده طرز تهیه یک بات با زبان #C توضیح داده شود.
در ابتدا شما باید توسط یکی از باتهای اصلی تلگرام اقدام به ثبت نام کاربری و تنظیمات بات مورد نظر خودتان نمایید. بات مورد نظر @BotFather میباشد که با شروع مکالمه میتوان با فرستادن دستورات مختلف تنظیمات مختلفی را انجام داد. با شروع مکالمه با بات مورد نظر با دستور /start دستورات زیر قابل انجام میباشد:
با انجام دستور /newbot در ابتدا نام بات و یوزنیم (دقت کنید یوزرنیم میبایست حتما به کلمهی bot ختم شود) را تنظیم کنید.
بعد از تایید نام و یوزر نیم، به شما یک توکن اختصاص داده میشود که توسط آن شما شناسایی میشوید.
در اینجا شما میتوانید تنظیمات اضافهتری مانند عکس برای پروفایل و غیره را نیز تنظیم کنید.
در مرحلهی بعد میتوانید در همین قسمت دستورات مورد نظر را جهت بات خود تنظیم کنید. برای این کار باید دستور /setcommands را وارد کنید و دستور مورد نظر خود را به فرمت command1 – Description وارد کنید.
مرحلهی بعد، تنظیمات برنامهی شما جهت دریافت دستورات وارد شده و انجام عملیات مورد نظر و تولید و ارسال خروجی مورد نظر است.
دریافت دستورات به دو طریق انجام میشود:
1. توسط دستور getUpdates میتوان تمامی کامندهای دریافتی را از سرور تلگرام دریافت کرد و با انجام پروسسهای لازم، خروجی را به کاربر مورد نظر ارسال کرد.
2. توسط تابع webhook از تلگرام درخواست کرد در صورت دریافت دستور جدید به بات، این دستور را به یک آدرس خاص ارسال کرد.
قابل توجه است که میتوان فقط از یکی از دو روش فوق استفاده کرد. همچنین در روش دوم حتما سرور مورد نظر باید گواهی ssl تایید شده داشته باشد.
کد زیر دریافت کامندهای یک بات به روش اول میباشد :
و توسط تابع زیر میتوان به کاربری که به بات کامند ارسال کرد، پاسخ داد:
لازم به ذکر است خروجی توابع باتهای تلگرام با فرمت JSON میباشد که با نصب پکیج NewTonsoft میتوان آن را به لیست تبدیل کرد.
rs.message.chat.id، آی دی فردی است که به بات تلگرامی ما مسیج ارسال کرده است.
rs.message.chat.first_name نام فردی است که به بات تلگرام مسیج ارسال کرده است.
همچنین میتوان در جواب کامند بات، علاوه بر متن، صدا و تصویر را نیز ارسال نمود .
در این لینک و این لینک میتوان توضیحات بیشتری را در این زمینه مطالعه کرد.
در انتها خوشحال میشوم ذوقها و ایدههای شما را در ساخت باتها با آیدی @iekhtiari مشاهده کنم.
چندی پیش موسسان تلگرام با معرفی APIهای کاربردی، به توسعه کنندگان اجازه دادند که با بهره گیری از بستر این شبکه، اقدام به تولید اینترفیسی به اسم بات کنند که با دریافت دستورات سفارشی، عملیات خاصی را انجام دهد.
در واقع تلگرام و متدهای ارائه شده، یک راه ارتباطی بین کاربران و برنامههای تولید شده را ایجاد کردند که با قدری ذوق و سلیقه، شاهد باتهای جالب و کاربردی هستیم.
در این مقاله سعی شده طرز تهیه یک بات با زبان #C توضیح داده شود.
در ابتدا شما باید توسط یکی از باتهای اصلی تلگرام اقدام به ثبت نام کاربری و تنظیمات بات مورد نظر خودتان نمایید. بات مورد نظر @BotFather میباشد که با شروع مکالمه میتوان با فرستادن دستورات مختلف تنظیمات مختلفی را انجام داد. با شروع مکالمه با بات مورد نظر با دستور /start دستورات زیر قابل انجام میباشد:
You can control me by sending these commands : / newbot - create a new bot / token - generate authorization token / revoke - revoke bot access token / setname - change a bot's name / setdescription - change bot description / setabouttext - change bot about info / setuserpic - change bot profile photo / setcommands - change bot commands list / setjoingroups - can your bot be added to groups ? / setprivacy - what messages does your bot see in groups ? / deletebot - delete a bot / cancel - cancel the current operation
بعد از تایید نام و یوزر نیم، به شما یک توکن اختصاص داده میشود که توسط آن شما شناسایی میشوید.
در اینجا شما میتوانید تنظیمات اضافهتری مانند عکس برای پروفایل و غیره را نیز تنظیم کنید.
در مرحلهی بعد میتوانید در همین قسمت دستورات مورد نظر را جهت بات خود تنظیم کنید. برای این کار باید دستور /setcommands را وارد کنید و دستور مورد نظر خود را به فرمت command1 – Description وارد کنید.
مرحلهی بعد، تنظیمات برنامهی شما جهت دریافت دستورات وارد شده و انجام عملیات مورد نظر و تولید و ارسال خروجی مورد نظر است.
دریافت دستورات به دو طریق انجام میشود:
1. توسط دستور getUpdates میتوان تمامی کامندهای دریافتی را از سرور تلگرام دریافت کرد و با انجام پروسسهای لازم، خروجی را به کاربر مورد نظر ارسال کرد.
2. توسط تابع webhook از تلگرام درخواست کرد در صورت دریافت دستور جدید به بات، این دستور را به یک آدرس خاص ارسال کرد.
قابل توجه است که میتوان فقط از یکی از دو روش فوق استفاده کرد. همچنین در روش دوم حتما سرور مورد نظر باید گواهی ssl تایید شده داشته باشد.
کد زیر دریافت کامندهای یک بات به روش اول میباشد :
public class mydata { public result[] result; } public class result { public int update_id { get; set; } public message message { get; set; } } public class message { public int message_id { get; set; } public message_from from { get; set; } public message_chat chat { get; set; } public int date { get; set; } public string text { get; set; } } public class message_from { public int ind { get; set; } public string first_name { get; set; } public string username { get; set; } } public class message_chat { public int id { get; set; } public string first_name { get; set; } public string username { get; set; } } public Void GetUpdates() { WebRequest req = WebRequest.Create("https://api.telegram.org/bot" + yourToken + "/getUpdates"); req.UseDefaultCredentials = true; WebResponse resp = req.GetResponse(); Stream stream = resp.GetResponseStream(); StreamReader sr = new StreamReader(stream); string s = sr.ReadToEnd(); sr.Close(); var jobject = Newtonsoft.Json.Linq.JObject.Parse(s); mydata gg = JsonConvert.DeserializeObject<mydata>(jobject.ToString()); List<result> results = new List<result>(); foreach (result rs in gg.result) { results.Add(rs); SendMessage(rs.message.chat.id.ToString(), "hello"+" "+"Dear"+rs.message.chat.first_name); } }
public static void SendMessage(string chat_id, string message) { WebRequest req = WebRequest.Create("https://api.telegram.org/bot" + youToken + "/sendMessage?chat_id=" + chat_id + "&text=" + message); req.UseDefaultCredentials = true; var result = req.GetResponse(); req.Abort(); }
لازم به ذکر است خروجی توابع باتهای تلگرام با فرمت JSON میباشد که با نصب پکیج NewTonsoft میتوان آن را به لیست تبدیل کرد.
rs.message.chat.id، آی دی فردی است که به بات تلگرامی ما مسیج ارسال کرده است.
rs.message.chat.first_name نام فردی است که به بات تلگرام مسیج ارسال کرده است.
همچنین میتوان در جواب کامند بات، علاوه بر متن، صدا و تصویر را نیز ارسال نمود .
در این لینک و این لینک میتوان توضیحات بیشتری را در این زمینه مطالعه کرد.
در انتها خوشحال میشوم ذوقها و ایدههای شما را در ساخت باتها با آیدی @iekhtiari مشاهده کنم.
مطالب
امن سازی برنامههای ASP.NET Core توسط IdentityServer 4x - قسمت سوم - بررسی مفاهیم OpenID Connect
پیش از نصب و راه اندازی IdentityServer، نیاز است با یک سری از مفاهیم اساسی پروتکل OpenID Connect، مانند Identity token ،Client types ،Flow و Endpoints، آشنا شویم تا بتوانیم از امکانات این IDP ویژه استفاده و آنها را تنظیم کنیم. بدون آشنایی با این مفاهیم، اتصال برنامهای که در قسمت قبل تدارک دیدیم به IdentityServer میسر نیست.
پروتکل OpenID Connect چگونه کار میکند؟
در انتهای قسمت اول این سری، پروتکل OpenID Connect معرفی شد. در ادامه جزئیات بیشتری از این پروتکل را بررسی میکنیم.
هر برنامهی کلاینت متصل به WebAPI مثال قسمت قبل، نیاز به دانستن هویت کاربر وارد شدهی به آنرا دارد. در اینجا به این برنامهی کلاینت، اصطلاحا relying party هم گفته میشود؛ از این جهت که این برنامهی کلاینت، به برنامهی Identity provider و یا به اختصار IDP، جهت دریافت نتیجهی اعتبارسنجی کاربر، وابستهاست. برنامهی کلاینت یک درخواست Authentication را به سمت IDP ارسال میکند. به این ترتیب کاربر به صورت موقت از برنامهی جاری خارج شده و به برنامهی IDP منتقل میشود. در برنامهی IDP است که کاربر مشخص میکند کیست؛ برای مثال با ارائهی نام کاربری و کلمهی عبور. پس از این مرحله، در صورت تائید هویت کاربر، برنامهی IDP یک Identity Token را تولید و امضاء میکند. سپس برنامهی IDP کاربر را مجددا به برنامهی کلاینت اصلی هدایت میکند و Identity Token را در اختیار آن کلاینت قرار میدهد. در اینجا برنامهی کلاینت، این توکن هویت را دریافت و اعتبارسنجی میکند. اگر این اعتبارسنجی با موفقیت انجام شود، اکنون کاربر تعیین اعتبار شده و هویت او جهت استفادهی از قسمتهای مختلف برنامه مشخص میشود. در برنامههای ASP.NET Core، این توکن هویت، پردازش و بر اساس آن یکسری Claims تولید میشوند که در اغلب موارد به صورت یک کوکی رمزنگاری شده در سمت کلاینت ذخیره میشوند.
به این ترتیب مرورگر با هر درخواستی از سمت کاربر، این کوکی را به صورت خودکار به سمت برنامهی کلاینت ارسال میکند و از طریق آن، هویت کاربر بدون نیاز به مراجعهی مجدد به IDP، استخراج و استفاده میشود.
مراحل انتقال کاربر به IDP، صدور توکن هویت، بازگشت مجدد به برنامهی کلاینت، اعتبارسنجی، استخراج Claims و ذخیرهی آن به صورت یک کوکی رمزنگاری شده را در تصویر فوق ملاحظه میکنید. بنابراین در حین کار با یک IDP، مرحلهی لاگین به سیستم، دیگر در برنامه یا برنامههای کلاینت قرار ندارد. در اینجا دو فلش به سمت IDP و سپس به سمت کلاینت را بخاطر بسپارید. در ادامه از آنها برای توضیح Flow و Endpoints استفاده خواهیم کرد.
البته OpenID Connect برای کار همزمان با انواع و اقسام برنامههای کلاینت طراحی شدهاست؛ مانند برنامهی سمت سرور MVC، برنامههای سمت کلاینت جاوا اسکریپتی مانند Angular و برنامههای موبایل. برای این منظور باید در IDP نوع کلاینت و یکسری از تنظیمات مرتبط با آنرا مشخص کرد.
کلاینتهای عمومی و محرمانه
زمانیکه قرار است با یک IDP کار کنیم، این IDP باید بتواند بین یک برنامهی حسابداری و یک برنامهی پرسنلی که از آن برای احراز هویت استفاده میکنند، تفاوت قائل شود و آنها را شناسایی کند.
- کلاینت محرمانه (Confidential Client)
هر کلاینت با یک client-id و یک client-secret شناخته میشود. کلاینتی که بتواند محرمانگی این اطلاعات را حفظ کند، کلاینت محرمانه نامیده میشود.
در اینجا هر کاربر، اطلاعات هویت خود را در IDP وارد میکند. اما اطلاعات تعیین هویت کلاینتها در سمت کلاینتها ذخیره میشوند. برای مثال برنامههای وب ASP.NET Core میتوانند هویت کلاینت خود را به نحو امنی در سمت سرور ذخیره کنند و این اطلاعات، قابل دسترسی توسط کاربران آن برنامه نیستند.
- کلاینت عمومی (Public Client)
این نوع کلاینتها نمیتوانند محرمانگی هویت خود را حفظ و تضمین کنند؛ مانند برنامههای جاوا اسکریپتی Angular و یا برنامههای موبایل که بر روی وسایل الکترونیکی کاربران اجرا میشوند. در این حالت هرچقدر هم سعی کنیم، چون کاربران به اصل این برنامهها دسترسی دارند، نمیتوان محرمانگی اطلاعات ذخیره شدهی در آنها را تضمین کرد.
مفهوم OpenID Connect Endpoints
در تصویر ابتدای بحث، دو فلش را مشاهده میکنید؛ برای مثال چگونه میتوان به Identity token دسترسی یافت (Authentication) و همچنین زمانیکه صحبت از Authorization میشود، چگونه میتوان Access tokens را دریافت کرد. اینکه این مراحله چگونه کار میکنند، توسط Flow مشخص میشود. Flow مشخص میکند که چگونه باید توکنها از سمت IDP به سمت کلاینت بازگشت داده شوند. بسته به نوع کلاینتها که در مورد آنها بحث شد و نیازمندیهای برنامه، باید از Flow مناسبی استفاده کرد.
هر Flow با Endpoint متفاوتی ارتباط برقرار میکند. این Endpointها در حقیقت جایگزین راهحلهای خانگی تولید برنامههای IDP هستند.
- در ابتدا یک Authorization Endpoint وجود دارد که در سطح IDP عمل میکند. این مورد همان انتهای فلش اول ارسال درخواست به سمت IDP است؛ در تصویر ابتدای بحث. کار این Endpoint، بازگشت Identity token جهت انجام عملیات Authentication و بازگشت Access token برای تکمیل عملیات Authorization است. این عملیات نیز توسط Redirection کلاینت انجام میشود (هدایت کاربر به سمت برنامهی IDP، دریافت توکنها و سپس هدایت مجدد به سمت برنامهی کلاینت اصلی).
نکتهی مهم: استفادهی از TLS و یا همان پروتکل HTTPS برای کار با OpenID Connect Endpoints اجباری است و بدون آن نمیتوانید با این سیستم کار کنید. به عبارتی در اینجا ترافیک بین کلاینت و IDP، همواره باید رمزنگاری شده باشد.
البته مزیت کار با ASP.NET Core 2.1، یکپارچگی بهتر و پیشفرض آن با پروتکل HTTPS است؛ تا حدی که مثال پیشفرض local آن به همراه یک مجوز موقتی SSL نصب شدهی توسط SDK آن کار میکند.
- پس از Authorization Endpoint که در مورد آن توضیح داده شد، یک Redirection Endpoint وجود دارد. در ابتدای کار، کلاینت با یک Redirect به سمت IDP هدایت میشود و پس از احراز هویت، مجددا کاربر به سمت کلاینت Redirect خواهد شد. به آدرسی که IDP کاربر را به سمت کلاینت Redirect میکند، Redirection Endpoint میگویند و در سطح کلاینت تعریف میشود. برنامهی IDP، اطلاعات تولیدی خود را مانند انواع توکنها، به سمت این Endpoint که در سمت کلاینت قرار دارد، ارسال میکند.
- پس از آن یک Token Endpoint نیز وجود دارد که در سطح IDP تعریف میشود. این Endpoint، آدرسی است در سمت IDP، که برنامهی کلاینت میتواند با برنامه نویسی، توکنهایی را از آن درخواست کند. این درخواست عموما از نوع HTTP Post بدون Redirection است.
مفهوم OpenID Connect Flow
- اولین Flow موجود، Authorization Code Flow است. کار آن بازگشت کدهای Authorization از Authorization Endpoint و همچنین توکنها از طریق Token Endpoint میباشد. در ایجا منظور از «کدهای Authorization»، اطلاعات دسترسی با طول عمر کوتاه است. هدف Authorization Code این است که مشخص کند، کاربری که به IDP لاگین کردهاست، همانی است که Flow را از طریق برنامهی وب کلاینت، شروع کردهاست. انتخاب این نوع Flow، برای کلاینتهای محرمانه مناسب است. در این حالت میتوان مباحث Refresh token و داشتن توکنهایی با طول عمر بالا را نیز پیاده سازی کرد.
- Implicit Flow، تنها توکنهای تولیدی را توسط Authorization Endpoint بازگشت میدهد و در اینجا خبری از بازگشت «کدهای Authorization» نیست. بنابراین از Token Endpoint استفاده نمیکند. این نوع Flow، برای کلاینتهای عمومی مناسب است. در اینجا کار client authentication انجام نمیشود؛ از این جهت که کلاینتهای عمومی، مناسب ذخیره سازی client-secret نیستند. به همین جهت در اینجا امکان دسترسی به Refresh token و توکنهایی با طول عمر بالا میسر نیست. این نوع از Flow، ممکن است توسط کلاینتهای محرمانه نیز استفاده شود.
- Hybrid Flow، تعدادی از توکنها را توسط Authorization Endpoint و تعدادی دیگر را توسط Token Endpoint بازگشت میدهد؛ بنابراین ترکیبی از دو Flow قبلی است. انتخاب این نوع Flow، برای کلاینتهای محرمانه مناسب است. در این حالت میتوان مباحث Refresh token و داشتن توکنهایی با طول عمر بالا را نیز پیاده سازی کرد. از این نوع Flow ممکن است برای native mobile apps نیز استفاده شود.
آگاهی از انواع Flowها، انتخاب نوع صحیح آنها را میسر میکند که در نتیجه منتهی به مشکلات امنیتی نخواهند شد. برای مثال Hybrid Flow توسط پشتیبانی از Refresh token امکان تمدید توکن جاری و بالا بردن طول عمر آنرا دارد و این طول عمر بالا بهتر است به کلاینتهای اعتبارسنجی شده ارائه شود. برای اعتبارسنجی یک کلاینت، نیاز به client-secret داریم و برای مثال برنامههای جاوا اسکریپتی نمیتوانند محل مناسبی برای ذخیره سازی client-secret باشند؛ چون از نوع کلاینتهای عمومی محسوب میشوند. بنابراین نباید از Hybrid Flow برای برنامههای Angular استفاده کرد. هرچند انتخاب این مساله صرفا به شما بر میگردد و چیزی نمیتواند مانع آن شود. برای مثال میتوان Hybrid Flow را با برنامههای Angular هم بکار برد؛ هرچند ایدهی خوبی نیست.
انتخاب OpenID Connect Flow مناسب برای یک برنامهی کلاینت از نوع ASP.NET Core
برنامههای ASP.NET Core، از نوع کلاینتهای محرمانه بهشمار میروند. بنابراین در اینجا میتوان تمام Flowهای یاد شده را انتخاب کرد. در برنامههای سمت سرور وب، به ویژگی به روز رسانی توکن نیاز است. بنابراین باید دسترسی به Refresh token را نیز داشت که توسط Implicit Flow پشتیبانی نمیشود. به همین جهت از Implicit Flow در اینجا استفاده نمیکنیم. پیش از ارائهی OpenID Connect، تنها Flow مورد استفادهی در برنامههای سمت سرور وب، همان Authorization Code Flow بود. در این Flow تمام توکنها توسط Token Endpoint بازگشت داده میشوند. اما Hybrid Flow نسبت به آن این مزیتها را دارد:
- ابتدا اجازه میدهد تا Identity token را از IDP دریافت کنیم. سپس میتوان آنرا بدون دریافت توکن دسترسی، تعیین اعتبار کرد.
- در ادامه OpenID Connect این Identity token را به یک توکن دسترسی، متصل میکند.
به همین جهت OpenID Connect نسبت به OAuth 2 ارجحیت بیشتری پیدا میکند.
پس از آشنایی با این مقدمات، در قسمت بعدی، کار نصب و راه اندازی IdentityServer را انجام خواهیم داد.
پروتکل OpenID Connect چگونه کار میکند؟
در انتهای قسمت اول این سری، پروتکل OpenID Connect معرفی شد. در ادامه جزئیات بیشتری از این پروتکل را بررسی میکنیم.
هر برنامهی کلاینت متصل به WebAPI مثال قسمت قبل، نیاز به دانستن هویت کاربر وارد شدهی به آنرا دارد. در اینجا به این برنامهی کلاینت، اصطلاحا relying party هم گفته میشود؛ از این جهت که این برنامهی کلاینت، به برنامهی Identity provider و یا به اختصار IDP، جهت دریافت نتیجهی اعتبارسنجی کاربر، وابستهاست. برنامهی کلاینت یک درخواست Authentication را به سمت IDP ارسال میکند. به این ترتیب کاربر به صورت موقت از برنامهی جاری خارج شده و به برنامهی IDP منتقل میشود. در برنامهی IDP است که کاربر مشخص میکند کیست؛ برای مثال با ارائهی نام کاربری و کلمهی عبور. پس از این مرحله، در صورت تائید هویت کاربر، برنامهی IDP یک Identity Token را تولید و امضاء میکند. سپس برنامهی IDP کاربر را مجددا به برنامهی کلاینت اصلی هدایت میکند و Identity Token را در اختیار آن کلاینت قرار میدهد. در اینجا برنامهی کلاینت، این توکن هویت را دریافت و اعتبارسنجی میکند. اگر این اعتبارسنجی با موفقیت انجام شود، اکنون کاربر تعیین اعتبار شده و هویت او جهت استفادهی از قسمتهای مختلف برنامه مشخص میشود. در برنامههای ASP.NET Core، این توکن هویت، پردازش و بر اساس آن یکسری Claims تولید میشوند که در اغلب موارد به صورت یک کوکی رمزنگاری شده در سمت کلاینت ذخیره میشوند.
به این ترتیب مرورگر با هر درخواستی از سمت کاربر، این کوکی را به صورت خودکار به سمت برنامهی کلاینت ارسال میکند و از طریق آن، هویت کاربر بدون نیاز به مراجعهی مجدد به IDP، استخراج و استفاده میشود.
مراحل انتقال کاربر به IDP، صدور توکن هویت، بازگشت مجدد به برنامهی کلاینت، اعتبارسنجی، استخراج Claims و ذخیرهی آن به صورت یک کوکی رمزنگاری شده را در تصویر فوق ملاحظه میکنید. بنابراین در حین کار با یک IDP، مرحلهی لاگین به سیستم، دیگر در برنامه یا برنامههای کلاینت قرار ندارد. در اینجا دو فلش به سمت IDP و سپس به سمت کلاینت را بخاطر بسپارید. در ادامه از آنها برای توضیح Flow و Endpoints استفاده خواهیم کرد.
البته OpenID Connect برای کار همزمان با انواع و اقسام برنامههای کلاینت طراحی شدهاست؛ مانند برنامهی سمت سرور MVC، برنامههای سمت کلاینت جاوا اسکریپتی مانند Angular و برنامههای موبایل. برای این منظور باید در IDP نوع کلاینت و یکسری از تنظیمات مرتبط با آنرا مشخص کرد.
کلاینتهای عمومی و محرمانه
زمانیکه قرار است با یک IDP کار کنیم، این IDP باید بتواند بین یک برنامهی حسابداری و یک برنامهی پرسنلی که از آن برای احراز هویت استفاده میکنند، تفاوت قائل شود و آنها را شناسایی کند.
- کلاینت محرمانه (Confidential Client)
هر کلاینت با یک client-id و یک client-secret شناخته میشود. کلاینتی که بتواند محرمانگی این اطلاعات را حفظ کند، کلاینت محرمانه نامیده میشود.
در اینجا هر کاربر، اطلاعات هویت خود را در IDP وارد میکند. اما اطلاعات تعیین هویت کلاینتها در سمت کلاینتها ذخیره میشوند. برای مثال برنامههای وب ASP.NET Core میتوانند هویت کلاینت خود را به نحو امنی در سمت سرور ذخیره کنند و این اطلاعات، قابل دسترسی توسط کاربران آن برنامه نیستند.
- کلاینت عمومی (Public Client)
این نوع کلاینتها نمیتوانند محرمانگی هویت خود را حفظ و تضمین کنند؛ مانند برنامههای جاوا اسکریپتی Angular و یا برنامههای موبایل که بر روی وسایل الکترونیکی کاربران اجرا میشوند. در این حالت هرچقدر هم سعی کنیم، چون کاربران به اصل این برنامهها دسترسی دارند، نمیتوان محرمانگی اطلاعات ذخیره شدهی در آنها را تضمین کرد.
مفهوم OpenID Connect Endpoints
در تصویر ابتدای بحث، دو فلش را مشاهده میکنید؛ برای مثال چگونه میتوان به Identity token دسترسی یافت (Authentication) و همچنین زمانیکه صحبت از Authorization میشود، چگونه میتوان Access tokens را دریافت کرد. اینکه این مراحله چگونه کار میکنند، توسط Flow مشخص میشود. Flow مشخص میکند که چگونه باید توکنها از سمت IDP به سمت کلاینت بازگشت داده شوند. بسته به نوع کلاینتها که در مورد آنها بحث شد و نیازمندیهای برنامه، باید از Flow مناسبی استفاده کرد.
هر Flow با Endpoint متفاوتی ارتباط برقرار میکند. این Endpointها در حقیقت جایگزین راهحلهای خانگی تولید برنامههای IDP هستند.
- در ابتدا یک Authorization Endpoint وجود دارد که در سطح IDP عمل میکند. این مورد همان انتهای فلش اول ارسال درخواست به سمت IDP است؛ در تصویر ابتدای بحث. کار این Endpoint، بازگشت Identity token جهت انجام عملیات Authentication و بازگشت Access token برای تکمیل عملیات Authorization است. این عملیات نیز توسط Redirection کلاینت انجام میشود (هدایت کاربر به سمت برنامهی IDP، دریافت توکنها و سپس هدایت مجدد به سمت برنامهی کلاینت اصلی).
نکتهی مهم: استفادهی از TLS و یا همان پروتکل HTTPS برای کار با OpenID Connect Endpoints اجباری است و بدون آن نمیتوانید با این سیستم کار کنید. به عبارتی در اینجا ترافیک بین کلاینت و IDP، همواره باید رمزنگاری شده باشد.
البته مزیت کار با ASP.NET Core 2.1، یکپارچگی بهتر و پیشفرض آن با پروتکل HTTPS است؛ تا حدی که مثال پیشفرض local آن به همراه یک مجوز موقتی SSL نصب شدهی توسط SDK آن کار میکند.
- پس از Authorization Endpoint که در مورد آن توضیح داده شد، یک Redirection Endpoint وجود دارد. در ابتدای کار، کلاینت با یک Redirect به سمت IDP هدایت میشود و پس از احراز هویت، مجددا کاربر به سمت کلاینت Redirect خواهد شد. به آدرسی که IDP کاربر را به سمت کلاینت Redirect میکند، Redirection Endpoint میگویند و در سطح کلاینت تعریف میشود. برنامهی IDP، اطلاعات تولیدی خود را مانند انواع توکنها، به سمت این Endpoint که در سمت کلاینت قرار دارد، ارسال میکند.
- پس از آن یک Token Endpoint نیز وجود دارد که در سطح IDP تعریف میشود. این Endpoint، آدرسی است در سمت IDP، که برنامهی کلاینت میتواند با برنامه نویسی، توکنهایی را از آن درخواست کند. این درخواست عموما از نوع HTTP Post بدون Redirection است.
مفهوم OpenID Connect Flow
- اولین Flow موجود، Authorization Code Flow است. کار آن بازگشت کدهای Authorization از Authorization Endpoint و همچنین توکنها از طریق Token Endpoint میباشد. در ایجا منظور از «کدهای Authorization»، اطلاعات دسترسی با طول عمر کوتاه است. هدف Authorization Code این است که مشخص کند، کاربری که به IDP لاگین کردهاست، همانی است که Flow را از طریق برنامهی وب کلاینت، شروع کردهاست. انتخاب این نوع Flow، برای کلاینتهای محرمانه مناسب است. در این حالت میتوان مباحث Refresh token و داشتن توکنهایی با طول عمر بالا را نیز پیاده سازی کرد.
- Implicit Flow، تنها توکنهای تولیدی را توسط Authorization Endpoint بازگشت میدهد و در اینجا خبری از بازگشت «کدهای Authorization» نیست. بنابراین از Token Endpoint استفاده نمیکند. این نوع Flow، برای کلاینتهای عمومی مناسب است. در اینجا کار client authentication انجام نمیشود؛ از این جهت که کلاینتهای عمومی، مناسب ذخیره سازی client-secret نیستند. به همین جهت در اینجا امکان دسترسی به Refresh token و توکنهایی با طول عمر بالا میسر نیست. این نوع از Flow، ممکن است توسط کلاینتهای محرمانه نیز استفاده شود.
- Hybrid Flow، تعدادی از توکنها را توسط Authorization Endpoint و تعدادی دیگر را توسط Token Endpoint بازگشت میدهد؛ بنابراین ترکیبی از دو Flow قبلی است. انتخاب این نوع Flow، برای کلاینتهای محرمانه مناسب است. در این حالت میتوان مباحث Refresh token و داشتن توکنهایی با طول عمر بالا را نیز پیاده سازی کرد. از این نوع Flow ممکن است برای native mobile apps نیز استفاده شود.
آگاهی از انواع Flowها، انتخاب نوع صحیح آنها را میسر میکند که در نتیجه منتهی به مشکلات امنیتی نخواهند شد. برای مثال Hybrid Flow توسط پشتیبانی از Refresh token امکان تمدید توکن جاری و بالا بردن طول عمر آنرا دارد و این طول عمر بالا بهتر است به کلاینتهای اعتبارسنجی شده ارائه شود. برای اعتبارسنجی یک کلاینت، نیاز به client-secret داریم و برای مثال برنامههای جاوا اسکریپتی نمیتوانند محل مناسبی برای ذخیره سازی client-secret باشند؛ چون از نوع کلاینتهای عمومی محسوب میشوند. بنابراین نباید از Hybrid Flow برای برنامههای Angular استفاده کرد. هرچند انتخاب این مساله صرفا به شما بر میگردد و چیزی نمیتواند مانع آن شود. برای مثال میتوان Hybrid Flow را با برنامههای Angular هم بکار برد؛ هرچند ایدهی خوبی نیست.
انتخاب OpenID Connect Flow مناسب برای یک برنامهی کلاینت از نوع ASP.NET Core
برنامههای ASP.NET Core، از نوع کلاینتهای محرمانه بهشمار میروند. بنابراین در اینجا میتوان تمام Flowهای یاد شده را انتخاب کرد. در برنامههای سمت سرور وب، به ویژگی به روز رسانی توکن نیاز است. بنابراین باید دسترسی به Refresh token را نیز داشت که توسط Implicit Flow پشتیبانی نمیشود. به همین جهت از Implicit Flow در اینجا استفاده نمیکنیم. پیش از ارائهی OpenID Connect، تنها Flow مورد استفادهی در برنامههای سمت سرور وب، همان Authorization Code Flow بود. در این Flow تمام توکنها توسط Token Endpoint بازگشت داده میشوند. اما Hybrid Flow نسبت به آن این مزیتها را دارد:
- ابتدا اجازه میدهد تا Identity token را از IDP دریافت کنیم. سپس میتوان آنرا بدون دریافت توکن دسترسی، تعیین اعتبار کرد.
- در ادامه OpenID Connect این Identity token را به یک توکن دسترسی، متصل میکند.
به همین جهت OpenID Connect نسبت به OAuth 2 ارجحیت بیشتری پیدا میکند.
پس از آشنایی با این مقدمات، در قسمت بعدی، کار نصب و راه اندازی IdentityServer را انجام خواهیم داد.
هر زمانیکه در سمت کلاینت، استثناء یا خطایی رخ میدهد، کاربر با نوار زرد رنگی در پایین صفحه، از آن مطلع میشود؛ اما برنامه نویس چطور؟! به همین جهت در این مطلب قصد داریم تمام خطاهای رخ دادهی در برنامهی سمت کلاینت را لاگ کرده و به سرور تلگرام ارسال کنیم. مزیت کار کردن با تلگرام، دسترسی به سروری است که تقریبا همواره در دسترس است و برخلاف بانک اطلاعاتی برنامه که ممکن است در لحظهی بروز خطا، خودش سبب ساز اصلی باشد و قادر به ثبت اطلاعات خطاهای رسیدهی از سمت کلاینت نباشد، چنین مشکلی را با تلگرام نداریم (مانند همان جملهی معروف: «بکآپ سروری که روی همان سرور گرفته میشود، بک آپ نام ندارد!»). همچنین بررسی و حذف گزارشهای رسیدهی به آن نیز بسیار سادهاست و میتوان این گزارشها را مستقل از سرور برنامه و از طریق وسایل مختلفی مانند گوشیهای همراه، تبلتها و غیره نیز بررسی کرد.
نحوهی نمایش خطاها در برنامههای Blazor
در حین توسعهی برنامههای Blazor، اگر استثنائی رخ دهد، نوار زرد رنگی در پایین صفحه، ظاهر میشود که امکان هدایت توسعه دهنده را به کنسول مرورگر، برای مشاهدهی جزئیات بیشتر آن خطا را دارد. در حالت توزیع برنامه، این نوار زرد رنگ تنها به ذکر خطایی رخ دادهاست اکتفا کرده و گزینهی راه اندازی مجدد برنامه را با ریفرش کردن مرورگر، پیشنهاد میدهد. سفارشی سازی آن هم در فایل wwwroot/index.html در قسمت زیر صورت میگیرد:
که شیوه نامههای پیشفرض آن در فایل wwwroot/css/app.css قرار دارند. در حالت عادی المان blazor-error-ui به همراه یک display: none است که از نمایش آن جلوگیری میکند. اما در زمان بروز خطایی، فریمورک آنرا به صورت display: block نمایش میدهد.
نحوهی مدیریت استثناءها در برنامههای Blazor
توصیه شدهاست که کار مدیریت استثناءها باید توسط توسعه دهنده صورت گیرد و بهتر است جزئیات آنها و یا stack-trace آنها را به کاربر نمایش نداد؛ تا مبادا اطلاعات حساسی فاش شوند و یا کاربر مهاجم بتواند توسط آنها اطلاعات ارزشمندی را از نحوهی عملکرد برنامه بدست آورد.
برخلاف برنامههای ASP.NET Core که دارای یک middleware pipeline هستند و برای مثال توسط آنها میتوان مدیریت سراسری خطاهای رخداده را انجام داد، چنین ویژگی در برنامههای Blazor وجود ندارد؛ چون در اینجا مرورگر است که هاست برنامه بوده و processing pipeline آنرا تشکیل میدهد.
اما ... اگر استثنائی مدیریت نشده در یک برنامهی Blazor رخدهد، این استثناء در ابتدا توسط یک ILogger، لاگ شده و سپس در کنسول مرورگر نمایش داده میشود. در اینجا Console Logging Provider، تامین کنندهی پیشفرض سیستم ثبت وقایع برنامههای Blazor است. به همین جهت استثناءهای مدیریت نشدهی برنامه را میتوان در کنسول توسعه دهندگان مرورگر نیز مشاهده کرد. برای مثال اگر سطح لاگ ارائه شده LogLevel.Error باشد، به صورت خودکار به معادل console.error ترجمه میشود.
بنابراین اگر در برنامهی Blazor جاری یک ILoggerProvider سفارشی را تهیه و آنرا به سیستم تزریق وابستگیهای برنامه معرفی کنیم، میتوان از تمام وقایع سیستم (هر قسمتی از آن که از ILogger استفاده میکند)، منجمله تمام خطاهای رخداده (و مدیریت نشده) مطلع شد و برای مثال آنها را به سمت Web API برنامه، جهت ثبت در بانک اطلاعاتی و یا نمایش در برنامهی تلگرام، ارسال کرد و این دقیقا همان کاری است که قصد داریم در ادامه انجام دهیم.
نوشتن یک ILoggerProvider سفارشی جهت ارسال رخدادها برنامهی سمت کلاینت، به یک Web API
برای ارسال تمام وقایع برنامهی کلاینت به سمت سرور، نیاز است یک ILoggerProvider سفارشی را تهیه کنیم که شروع آن به صورت زیر است:
توضیحات:
زمانیکه قرار است یک لاگر سفارشی را به سیستم تزریق وابستگیهای برنامه معرفی کنیم، روش آن به صورت زیر است:
باید کلاسی را داشته باشیم مانند ClientLoggerProvider که یک ILoggerProvider را پیاده سازی میکند و نحوهی ثبت آن نیز باید حتما Singleton باشد. مزیت معرفی ILoggerProvider به این نحو، امکان دسترسی به سرویسهای برنامه در سازندهی کلاس ClientLoggerProvider است و در این حالت دیگر نیاز به نوشتن new ClientLoggerProvider نبوده و خود سیستم تزریق وابستگیها، سازندههای ClientLoggerProvider را تامین میکند.
در کلاس ClientLoggerProvider فوق، سه وابستگی تزریق شده را مشاهده میکنید:
با استفاده از IServiceProvider میتوان به HttpClient برنامه دسترسی یافت. از این جهت که چون HttpClient به صورت پیشفرض با طول عمر Scoped به سیستم معرفی شده، امکان تزریق مستقیم آن به سازندهی یک ILoggerProvider از نوع Singleton وجود ندارد. به همین جهت از IServiceProvider برای تامین آن استفاده خواهیم کرد. مابقی موارد مانند IOptions که تنظیمات این لاگر را فراهم میکند و یا NavigationManager استاندارد برنامه که امکان دسترسی به Url جاری را میسر میکند، به صورت پیشفرض دارای طول عمر Singleton هستند و میتوان آنها را بدون مشکل، به سازندهی لاگر سفارشی، تزریق کرد.
مهمترین قسمت ILoggerProvider سفارشی، متد CreateLogger آن است که یک ILogger را بازگشت میدهد:
بنابراین در ادامه نیاز است، یک ILogger سفارشی را نیز پیاده سازی کنیم:
نحوهی عملکرد این ILogger سفارشی بسیار سادهاست:
- متد IsEnabled آن مشخص میکند که چه سطحی از رخدادهای سیستم را باید لاگ کند. این سطح را نیز از تنظیمات برنامه دریافت میکند:
در این تنظیمات مشخص میکنیم که Url مربوط به اکشن متد Web API ما که قرار است اطلاعات به سمت آن ارسال شوند، چیست؟ همچنین حداقل سطح لاگ مدنظر را نیز باید مشخص کنیم. اطلاعات آن توسط فایل Client\wwwroot\appsettings.json با این محتوای فرضی قابل تنظیم است:
و همچنین باید کلاس WebApiLoggerOptions را به نحو زیر در کلاس Program برنامه به سیستم تزریق وابستگیها، معرفی کرد تا <IOptions<WebApiLoggerOptions قابلیت تزریق به سازندهی تامین کنندهی لاگر را پیدا کند:
- متد لاگ این لاگر سفارشی، پیام نهایی قابل ارسال به سمت Web API را تشکیل داده و توسط متد httpClient.PostAsJsonAsync آنرا ارسال میکند. به همین جهت ساختار لاگ مدنظر را در فایل Shared\ClientLog.cs به صورت زیر تعریف کردهایم که بین برنامهی کلاینت و سرور، مشترک است:
این اطلاعاتی است که کلاینت به ازای رخدادی خاص، جمع آوری کرده و به سمت سرور ارسال میکند.
در آخر هم کار ثبت متد ()AddWebApiLogger که معرفی ILoggerProvider سفارشی ما را انجام میدهد، به صورت زیر خواهد بود:
تا اینجا اگر هر نوع استثنای مدیریت نشدهای در برنامهی Blazor WASM رخ دهد، چون سطح لاگ آن بالاتر از Warning تنظیم شدهی در فایل Client\wwwroot\appsettings.json است:
به صورت خودکار به سمت کنترلر api/logs ارسال خواهد شد. بنابراین مرحلهی بعدی، تکمیل کنترلر یاد شدهاست.
ایجاد سرویسی برای ارسال لاگهای برنامه به سمت تلگرام
پیش از اینکه کار تکمیل کنترلر api/logs را در برنامهی Web API انجام دهیم، ابتدا در همان برنامهی Web API، سرویسی را برای ارسال لاگهای رسیده به سمت تلگرام، تهیه میکنیم. علت اینکه این قسمت را به برنامهی سمت سرور محول کردهایم، شامل موارد زیر است:
- درست است که میتوان کتابخانههای مرتبط با تلگرام را به برنامهی سیشارپی Blazor خود اضافه کرد، اما هر وابستگی سمت کلاینتی، سبب حجیمتر شدن توزیع نهایی برنامه خواهد شد که مطلوب نیست.
- برای کار با تلگرام نیاز است توکن اتصال به آنرا در یک محل امن، نگهداری کرد. قرار دادن این نوع اطلاعات حساس، در برنامهی سمت کلاینتی که تمام اجزای آن از مرورگر قابل استخراج و بررسی است، کار اشتباهی است.
- ارسال اطلاعات لاگ برنامهی سمت کلاینت به Web API، مزیت لاگ سمت سرور آنرا مانند ثبت در یک فایل محلی، ثبت در بانک اطلاعاتی و غیره را نیز میسر میکند و صرفا محدود به تلگرام نیست.
برای ارسال اطلاعات به تلگرام، سرویس سمت سرور زیر را تهیه میکنیم:
توضیحات:
- برای کار با API تلگرام، از کتابخانهی معروف Telegram.Bot استفاده کردهایم که به صورت زیر، وابستگی آن به برنامهی Web API اضافه میشود:
- این سرویس برای کار کردن، نیاز به تنظیمات زیر را دارد:
- برای دریافت AccessToken، در برنامهی تلگرام خود، بات مخصوصی را به نام https://t.me/botfather یافته و سپس آنرا استارت کنید:
پس از شروع این بات، ابتدا دستور newbot/ را صادر کنید. سپس یک نام را از شما میپرسد. نام دلخواهی را وارد کنید. در ادامه یک نام منحصربفرد را جهت شناسایی این بات خواهد پرسید. پس از دریافت آن، توکن خود را همانند تصویر فوق، مشاهده میکنید.
- مرحلهی بعد تنظیم ChatId است. نحوهی کار برنامه به این صورت است که پیامها را به این بات سفارشی خود ارسال کرده و این بات، آنها را به کانال اختصاصی ما هدایت میکند. بنابراین یک کانال جدید را ایجاد کنید. ترجیحا بهتر است این کانال خصوصی باشد. سپس کاربر test_2021_logs_bot@ (همان نام منحصربفرد بات که حتما باید با @ شروع شود) را به عنوان عضو جدید کانال خود اضافه کنید. در اینجا عنوان میکند که این کاربر چون بات است، باید دسترسی ادمین را داشته باشد که دقیقا این دسترسی را نیز باید برقرار کنید تا بتوان توسط این بات، پیامی را به کانال اختصاصی خود ارسال کرد.
بنابراین تا اینجا یک کانال خصوصی را ایجاد کردهایم که بات جدید test_2021_logs_bot@ عضو با دسترسی ادمین آن است. اکنون باید Id این کانال را بیابیم. برای اینکار بات دیگری را به نام JsonDumpBot@ یافته و استارت کنید. سپس در کانال خود یک پیام آزمایشی جدید را ارسال کنید و در ادامه این پیام را به بات JsonDumpBot@ ارسال کنید (forward کنید). همان لحظهای که کار ارسال پیام به این بات صورت گرفت، Id کانال خود را در پاسخ آن میتوانید مشاهده کنید:
در این تصویر مقدار forward_from_chat:id همان ChatId تنظیمات برنامهی شما است.
در آخر این اطلاعات را در فایل Server\appsettings.json قرار میدهیم:
که نحوهی ثبت و معرفی آنها به سیستم تزریق وابستگیهای برنامهی Web API، به صورت زیر است:
سرویس ITelegramBotService را با طول عمر Singleton معرفی کردهایم. چون new TelegramBotClient ای که در سازندهی آن صورت میگیرد:
باید فقط یکبار در طول عمر برنامه انجام شود و از این پس، هر بار که متد client.SendTextMessageAsync_ آن فراخوانی میگردد، پیامی به سمت بات و سپس کانال اختصاصی ما ارسال میشود.
ایجاد کنترلر Logs، جهت دریافت لاگهای رسیدهی از سمت کلاینت
مرحلهی آخر کار بسیار سادهاست. سرویس تکمیل شدهی ITelegramBotService را به سازندهی کنترلر Logs تزریق کرده و سپس متد SendLogAsync آنرا فراخوانی میکنیم تا لاگی را که از کلاینت دریافت کرده، به سمت تلگرام هدایت کند:
آزمایش برنامه
برای آزمایش برنامه، برای مثال در فایل Client\Pages\Counter.razor یک استثنای عمدی مدیریت نشده را قرار دادهایم:
اکنون اگر برنامه را اجرا کرده و سپس بر روی دکمهی شمارشگر کلیک کنیم، همان تصویر ابتدای مطلب را که حاصل از ارسال جزئیات این استثنای مدیریت نشده به سمت تلگرام است، مشاهده خواهیم کرد.
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید: BlazorWasmTelegramLogger.zip
نحوهی نمایش خطاها در برنامههای Blazor
در حین توسعهی برنامههای Blazor، اگر استثنائی رخ دهد، نوار زرد رنگی در پایین صفحه، ظاهر میشود که امکان هدایت توسعه دهنده را به کنسول مرورگر، برای مشاهدهی جزئیات بیشتر آن خطا را دارد. در حالت توزیع برنامه، این نوار زرد رنگ تنها به ذکر خطایی رخ دادهاست اکتفا کرده و گزینهی راه اندازی مجدد برنامه را با ریفرش کردن مرورگر، پیشنهاد میدهد. سفارشی سازی آن هم در فایل wwwroot/index.html در قسمت زیر صورت میگیرد:
<div id="blazor-error-ui"> An unhandled error has occurred. <a href="" class="reload">Reload</a> <a class="dismiss">🗙</a> </div>
نحوهی مدیریت استثناءها در برنامههای Blazor
توصیه شدهاست که کار مدیریت استثناءها باید توسط توسعه دهنده صورت گیرد و بهتر است جزئیات آنها و یا stack-trace آنها را به کاربر نمایش نداد؛ تا مبادا اطلاعات حساسی فاش شوند و یا کاربر مهاجم بتواند توسط آنها اطلاعات ارزشمندی را از نحوهی عملکرد برنامه بدست آورد.
برخلاف برنامههای ASP.NET Core که دارای یک middleware pipeline هستند و برای مثال توسط آنها میتوان مدیریت سراسری خطاهای رخداده را انجام داد، چنین ویژگی در برنامههای Blazor وجود ندارد؛ چون در اینجا مرورگر است که هاست برنامه بوده و processing pipeline آنرا تشکیل میدهد.
اما ... اگر استثنائی مدیریت نشده در یک برنامهی Blazor رخدهد، این استثناء در ابتدا توسط یک ILogger، لاگ شده و سپس در کنسول مرورگر نمایش داده میشود. در اینجا Console Logging Provider، تامین کنندهی پیشفرض سیستم ثبت وقایع برنامههای Blazor است. به همین جهت استثناءهای مدیریت نشدهی برنامه را میتوان در کنسول توسعه دهندگان مرورگر نیز مشاهده کرد. برای مثال اگر سطح لاگ ارائه شده LogLevel.Error باشد، به صورت خودکار به معادل console.error ترجمه میشود.
بنابراین اگر در برنامهی Blazor جاری یک ILoggerProvider سفارشی را تهیه و آنرا به سیستم تزریق وابستگیهای برنامه معرفی کنیم، میتوان از تمام وقایع سیستم (هر قسمتی از آن که از ILogger استفاده میکند)، منجمله تمام خطاهای رخداده (و مدیریت نشده) مطلع شد و برای مثال آنها را به سمت Web API برنامه، جهت ثبت در بانک اطلاعاتی و یا نمایش در برنامهی تلگرام، ارسال کرد و این دقیقا همان کاری است که قصد داریم در ادامه انجام دهیم.
نوشتن یک ILoggerProvider سفارشی جهت ارسال رخدادها برنامهی سمت کلاینت، به یک Web API
برای ارسال تمام وقایع برنامهی کلاینت به سمت سرور، نیاز است یک ILoggerProvider سفارشی را تهیه کنیم که شروع آن به صورت زیر است:
using System; using System.Net.Http; using Microsoft.AspNetCore.Components; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Options; namespace BlazorWasmTelegramLogger.Client.Logging { public class ClientLoggerProvider : ILoggerProvider { private readonly HttpClient _httpClient; private readonly WebApiLoggerOptions _options; private readonly NavigationManager _navigationManager; public ClientLoggerProvider( IServiceProvider serviceProvider, IOptions<WebApiLoggerOptions> options, NavigationManager navigationManager) { if (serviceProvider is null) { throw new ArgumentNullException(nameof(serviceProvider)); } if (options is null) { throw new ArgumentNullException(nameof(options)); } _httpClient = serviceProvider.CreateScope().ServiceProvider.GetRequiredService<HttpClient>(); _options = options.Value; _navigationManager = navigationManager ?? throw new ArgumentNullException(nameof(navigationManager)); } public ILogger CreateLogger(string categoryName) { return new WebApiLogger(_httpClient, _options, _navigationManager); } public void Dispose() { } } }
زمانیکه قرار است یک لاگر سفارشی را به سیستم تزریق وابستگیهای برنامه معرفی کنیم، روش آن به صورت زیر است:
using System; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; namespace BlazorWasmTelegramLogger.Client.Logging { public static class ClientLoggerProviderExtensions { public static ILoggingBuilder AddWebApiLogger(this ILoggingBuilder builder) { if (builder == null) { throw new ArgumentNullException(nameof(builder)); } builder.Services.AddSingleton<ILoggerProvider, ClientLoggerProvider>(); return builder; } } }
در کلاس ClientLoggerProvider فوق، سه وابستگی تزریق شده را مشاهده میکنید:
public ClientLoggerProvider( IServiceProvider serviceProvider, IOptions<WebApiLoggerOptions> options, NavigationManager navigationManager)
مهمترین قسمت ILoggerProvider سفارشی، متد CreateLogger آن است که یک ILogger را بازگشت میدهد:
public ILogger CreateLogger(string categoryName) { return new WebApiLogger(_httpClient, _options, _navigationManager); }
using System; using System.Net.Http; using System.Net.Http.Json; using BlazorWasmTelegramLogger.Shared; using Microsoft.AspNetCore.Components; using Microsoft.Extensions.Logging; namespace BlazorWasmTelegramLogger.Client.Logging { public class WebApiLogger : ILogger { private readonly WebApiLoggerOptions _options; private readonly HttpClient _httpClient; private readonly NavigationManager _navigationManager; public WebApiLogger(HttpClient httpClient, WebApiLoggerOptions options, NavigationManager navigationManager) { _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient)); _options = options ?? throw new ArgumentNullException(nameof(options)); _navigationManager = navigationManager ?? throw new ArgumentNullException(nameof(navigationManager)); } public IDisposable BeginScope<TState>(TState state) => default; public bool IsEnabled(LogLevel logLevel) => logLevel >= _options.LogLevel; public void Log<TState>( LogLevel logLevel, EventId eventId, TState state, Exception exception, Func<TState, Exception, string> formatter) { if (!IsEnabled(logLevel)) { return; } if (formatter is null) { throw new ArgumentNullException(nameof(formatter)); } try { ClientLog log = new() { LogLevel = logLevel, EventId = eventId, Message = formatter(state, exception), Exception = exception?.Message, StackTrace = exception?.StackTrace, Url = _navigationManager.Uri }; _httpClient.PostAsJsonAsync(_options.LoggerEndpointUrl, log); } catch { // don't throw exceptions from the logger } } } }
- متد IsEnabled آن مشخص میکند که چه سطحی از رخدادهای سیستم را باید لاگ کند. این سطح را نیز از تنظیمات برنامه دریافت میکند:
using Microsoft.Extensions.Logging; namespace BlazorWasmTelegramLogger.Client.Logging { public class WebApiLoggerOptions { public string LoggerEndpointUrl { set; get; } public LogLevel LogLevel { get; set; } = LogLevel.Information; } }
{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" } }, "WebApiLogger": { "LogLevel": "Warning", "LoggerEndpointUrl": "/api/logs" } }
namespace BlazorWasmTelegramLogger.Client { public class Program { public static async Task Main(string[] args) { var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.RootComponents.Add<App>("#app"); builder.Services.Configure<WebApiLoggerOptions>(options => builder.Configuration.GetSection("WebApiLogger").Bind(options)); // … } } }
using Microsoft.Extensions.Logging; namespace BlazorWasmTelegramLogger.Shared { public class ClientLog { public LogLevel LogLevel { get; set; } public EventId EventId { get; set; } public string Message { get; set; } public string Exception { get; set; } public string StackTrace { get; set; } public string Url { get; set; } } }
در آخر هم کار ثبت متد ()AddWebApiLogger که معرفی ILoggerProvider سفارشی ما را انجام میدهد، به صورت زیر خواهد بود:
namespace BlazorWasmTelegramLogger.Client { public class Program { public static async Task Main(string[] args) { var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.RootComponents.Add<App>("#app"); builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) }); builder.Services.Configure<WebApiLoggerOptions>(options => builder.Configuration.GetSection("WebApiLogger").Bind(options)); builder.Services.AddLogging(configure => { configure.AddWebApiLogger(); }); await builder.Build().RunAsync(); } } }
public bool IsEnabled(LogLevel logLevel) => logLevel >= _options.LogLevel;
ایجاد سرویسی برای ارسال لاگهای برنامه به سمت تلگرام
پیش از اینکه کار تکمیل کنترلر api/logs را در برنامهی Web API انجام دهیم، ابتدا در همان برنامهی Web API، سرویسی را برای ارسال لاگهای رسیده به سمت تلگرام، تهیه میکنیم. علت اینکه این قسمت را به برنامهی سمت سرور محول کردهایم، شامل موارد زیر است:
- درست است که میتوان کتابخانههای مرتبط با تلگرام را به برنامهی سیشارپی Blazor خود اضافه کرد، اما هر وابستگی سمت کلاینتی، سبب حجیمتر شدن توزیع نهایی برنامه خواهد شد که مطلوب نیست.
- برای کار با تلگرام نیاز است توکن اتصال به آنرا در یک محل امن، نگهداری کرد. قرار دادن این نوع اطلاعات حساس، در برنامهی سمت کلاینتی که تمام اجزای آن از مرورگر قابل استخراج و بررسی است، کار اشتباهی است.
- ارسال اطلاعات لاگ برنامهی سمت کلاینت به Web API، مزیت لاگ سمت سرور آنرا مانند ثبت در یک فایل محلی، ثبت در بانک اطلاعاتی و غیره را نیز میسر میکند و صرفا محدود به تلگرام نیست.
برای ارسال اطلاعات به تلگرام، سرویس سمت سرور زیر را تهیه میکنیم:
using System; using System.Text; using System.Threading.Tasks; using BlazorWasmTelegramLogger.Shared; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Options; using Telegram.Bot; using Telegram.Bot.Types.Enums; namespace BlazorWasmTelegramLogger.Server.Services { public class TelegramLoggingBotOptions { public string AccessToken { get; set; } public string ChatId { get; set; } } public interface ITelegramBotService { Task SendLogAsync(ClientLog log); } public class TelegramBotService : ITelegramBotService { private readonly string _chatId; private readonly TelegramBotClient _client; public TelegramBotService(IOptions<TelegramLoggingBotOptions> options) { _chatId = options.Value.ChatId; _client = new TelegramBotClient(options.Value.AccessToken); } public async Task SendLogAsync(ClientLog log) { var text = formatMessage(log); if (string.IsNullOrWhiteSpace(text)) { return; } await _client.SendTextMessageAsync(_chatId, text, ParseMode.Markdown); } private static string formatMessage(ClientLog log) { if (string.IsNullOrWhiteSpace(log.Message)) { return string.Empty; } var sb = new StringBuilder(); sb.Append(toEmoji(log.LogLevel)) .Append(" *") .AppendFormat("{0:hh:mm:ss}", DateTime.Now) .Append("* ") .AppendLine(log.Message); if (!string.IsNullOrWhiteSpace(log.Exception)) { sb.AppendLine() .Append('`') .AppendLine(log.Exception) .AppendLine(log.StackTrace) .AppendLine("`") .AppendLine(); } sb.Append("*Url:* ").AppendLine(log.Url); return sb.ToString(); } private static string toEmoji(LogLevel level) => level switch { LogLevel.Trace => "⬜️", LogLevel.Debug => "🟦", LogLevel.Information => "⬛️️️", LogLevel.Warning => "🟧", LogLevel.Error => "🟥", LogLevel.Critical => "❌", LogLevel.None => "🔳", _ => throw new ArgumentOutOfRangeException(nameof(level), level, null) }; } }
- برای کار با API تلگرام، از کتابخانهی معروف Telegram.Bot استفاده کردهایم که به صورت زیر، وابستگی آن به برنامهی Web API اضافه میشود:
<Project Sdk="Microsoft.NET.Sdk.Web"> <ItemGroup> <PackageReference Include="Telegram.Bot" Version="15.7.1" /> </ItemGroup> </Project>
public class TelegramLoggingBotOptions { public string AccessToken { get; set; } public string ChatId { get; set; } }
پس از شروع این بات، ابتدا دستور newbot/ را صادر کنید. سپس یک نام را از شما میپرسد. نام دلخواهی را وارد کنید. در ادامه یک نام منحصربفرد را جهت شناسایی این بات خواهد پرسید. پس از دریافت آن، توکن خود را همانند تصویر فوق، مشاهده میکنید.
- مرحلهی بعد تنظیم ChatId است. نحوهی کار برنامه به این صورت است که پیامها را به این بات سفارشی خود ارسال کرده و این بات، آنها را به کانال اختصاصی ما هدایت میکند. بنابراین یک کانال جدید را ایجاد کنید. ترجیحا بهتر است این کانال خصوصی باشد. سپس کاربر test_2021_logs_bot@ (همان نام منحصربفرد بات که حتما باید با @ شروع شود) را به عنوان عضو جدید کانال خود اضافه کنید. در اینجا عنوان میکند که این کاربر چون بات است، باید دسترسی ادمین را داشته باشد که دقیقا این دسترسی را نیز باید برقرار کنید تا بتوان توسط این بات، پیامی را به کانال اختصاصی خود ارسال کرد.
بنابراین تا اینجا یک کانال خصوصی را ایجاد کردهایم که بات جدید test_2021_logs_bot@ عضو با دسترسی ادمین آن است. اکنون باید Id این کانال را بیابیم. برای اینکار بات دیگری را به نام JsonDumpBot@ یافته و استارت کنید. سپس در کانال خود یک پیام آزمایشی جدید را ارسال کنید و در ادامه این پیام را به بات JsonDumpBot@ ارسال کنید (forward کنید). همان لحظهای که کار ارسال پیام به این بات صورت گرفت، Id کانال خود را در پاسخ آن میتوانید مشاهده کنید:
در این تصویر مقدار forward_from_chat:id همان ChatId تنظیمات برنامهی شما است.
در آخر این اطلاعات را در فایل Server\appsettings.json قرار میدهیم:
{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" } }, "AllowedHosts": "*", "TelegramLoggingBot": { "AccessToken": "1826…", "ChatId": "-1001…" } }
namespace BlazorWasmTelegramLogger.Server { public class Startup { // ... public void ConfigureServices(IServiceCollection services) { services.Configure<TelegramLoggingBotOptions>(options => Configuration.GetSection("TelegramLoggingBot").Bind(options)); services.AddSingleton<ITelegramBotService, TelegramBotService>(); // ... } // ... } }
public class TelegramBotService : ITelegramBotService { private readonly string _chatId; private readonly TelegramBotClient _client; public TelegramBotService(IOptions<TelegramLoggingBotOptions> options) { _chatId = options.Value.ChatId; _client = new TelegramBotClient(options.Value.AccessToken); }
ایجاد کنترلر Logs، جهت دریافت لاگهای رسیدهی از سمت کلاینت
مرحلهی آخر کار بسیار سادهاست. سرویس تکمیل شدهی ITelegramBotService را به سازندهی کنترلر Logs تزریق کرده و سپس متد SendLogAsync آنرا فراخوانی میکنیم تا لاگی را که از کلاینت دریافت کرده، به سمت تلگرام هدایت کند:
using System; using System.Threading.Tasks; using BlazorWasmTelegramLogger.Server.Services; using BlazorWasmTelegramLogger.Shared; using Microsoft.AspNetCore.Mvc; using Microsoft.Extensions.Logging; namespace BlazorWasmTelegramLogger.Server.Controllers { [ApiController] [Route("api/[controller]")] public class LogsController : ControllerBase { private readonly ILogger<LogsController> _logger; private readonly ITelegramBotService _telegramBotService; public LogsController(ILogger<LogsController> logger, ITelegramBotService telegramBotService) { _logger = logger ?? throw new ArgumentNullException(nameof(logger)); _telegramBotService = telegramBotService; } [HttpPost] public async Task<IActionResult> PostLog(ClientLog log) { // TODO: Save the client's `log` in the database _logger.Log(log.LogLevel, log.EventId, log.Url + Environment.NewLine + log.Message); await _telegramBotService.SendLogAsync(log); return Ok(); } } }
آزمایش برنامه
برای آزمایش برنامه، برای مثال در فایل Client\Pages\Counter.razor یک استثنای عمدی مدیریت نشده را قرار دادهایم:
@page "/counter" <h1>Counter</h1> <p>Current count: @currentCount</p> <button class="btn btn-primary" @onclick="IncrementCount">Click me</button> @code { private int currentCount = 0; private void IncrementCount() { currentCount++; throw new InvalidOperationException("This is an exception message from the client!"); } }
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید: BlazorWasmTelegramLogger.zip
پیش از شروع به کار توسعهی برنامههای مبتنی بر Blazor، باید با مبانی Razor آشنایی داشت. Razor امکان ترکیب کدهای #C و HTML را در یک فایل میسر میکند. دستور زبان آن از @ برای سوئیچ بین کدهای #C و HTML استفاده میکند. کدهای Razor را میتوان در فایلهای cshtml. نوشت که عموما مخصوص صفحات و Viewها هستند و یا در فایلهای razor. که برای توسعهی کامپوننتهای Balzor بکار گرفته میشوند. در اینجا مهم نیست که پسوند فایل مورد استفاده چیست؛ چون اصول razor بکار گرفته شده در آنها یکی است. البته در اینجا تاکید ما بیشتر بر روی فایلهای razor. است که در برنامههای مبتنی بر Blazor بکار گرفته میشوند.
ایجاد یک پروژهی جدید Blazor WASM
برای پیاده سازی و اجرای مثالهای این قسمت، نیاز به یک پروژهی جدید Blazor WASM را داریم که میتوان آنرا با اجرای دستور dotnet new blazorwasm --hosted در یک پوشهی خالی، ایجاد کرد.
یک نکته: دستور فوق به همراه یک سری پارامتر اختیاری مانند hosted-- نیز هست. برای مشاهدهی لیست آنها دستور dotnet new blazorwasm --help را صادر کنید. برای مثال ذکر پارامتر hosted-- سبب میشود تا یک ASP.NET Core host نیز برای Blazor WebAssembly app ایجاد شده تولید شود.
حالت hosted-- آن یک چنین ساختاری را دارد که از سه پروژه و پوشهی Client ،Server و Shared تشکیل میشود:
در اینجا یک پروژهی خالی WASM ایجاد شده که برخلاف حالت معمولی dotnet new blazorwasm که در قسمت قبل آنرا بررسی کردیم، دیگر از فایل استاتیک wwwroot\sample-data\weather.json در آن خبری نیست. بجای آن، یک پروژهی استاندارد ASP.NET Core Web API را در پوشهی جدید Server ایجاد کرده که کار ارائهی اطلاعات این سرویس آب و هوا را انجام میدهد و برنامهی WASM ایجاد شده، این اطلاعات را توسط HTTP Client خود، از سرور Web API دریافت میکند.
بنابراین اگر مدل برنامهای که قصد دارید تهیه کنید، ترکیبی از یک Web API و WASM است، روش hosted--، آغاز آنرا بسیار ساده میکند.
نکته: روش اجرای این نوع برنامهها با اجرای دستور dotnet run در داخل پوشهی Server پروژه، انجام میشود. با اینکار هم سرور ASP.NET Core آغاز میشود و هم برنامهی WASM توسط آن ارائه میگردد. در این حالت اگر آدرس https://localhost:5001 را در مرورگر باز کنیم، هم قسمتهای بدون نیاز به سرور پروژهی WASM قابل دسترسی است (مانند کار با شمارشگر آن) و هم قسمت دریافت اطلاعات از سرور آن، در منوی Fetch Data.
شروع به کار با Razor
پس از ایجاد یک پروژهی جدید WASM، به فایل Client\Pages\Index.razor آن مراجعه کرده و محتوای پیشفرض آنرا بجز سطر اول زیر، حذف میکنیم:
این سطر، بیانگر مسیریابی منتهی به کامپوننت جاری است. یعنی با گشودن برنامهی WASM در مرورگر و مراجعه به ریشهی سایت، محتوای این کامپوننت را مشاهده خواهیم کرد.
در فایلهای razor. میتوان ترکیبی از کدهای #C و HTML را نوشت. برای مثال:
در اینجا قصد داریم مقدار یک متغیر را در یک پاراگراف درج کنیم. به همین جهت برای تعریف آن و شروع به کدنویسی میتوان با تعریف یک قطعه کد که در فایلهای razor با code@ شروع میشود، اینکار را انجام داد. در این قطعه کد، نوشتن هر نوع کد #C ای مجاز است که نمونهای از آنرا در اینجا با تعریف یک متغیر مشاهده میکنید. اکنون برای درج مقدار این متغیر در بین کدهای HTML از حرف @ استفاده میکنیم؛ مانند name@ در اینجا. نمونهای از خروجی تغییرات فوق را در تصویر زیر مشاهده میکنید:
یک نکته: با توجه به اینکه تغییرات زیادی را در فایل جاری اعمال خواهیم کرد، بهتر است برنامه را با دستور dotnet watch run اجرا کرد، تا این تغییرات را تحت نظر قرار داده و آنها را به صورت خودکار کامپایل کند. به این صورت دیگر نیازی نخواهد بود به ازای هر تغییر، یکبار دستور dotnet run اجرا شود.
در زمان درج متغیرهای #C در بین کدهای HTML توسط razor، استفاده از تمام متدهای الحاقی زبان #C نیز مجاز هستند؛ مانند:
بنابراین درج حرف @ در بین کدهای HTML به این معنا است که به کامپایلر razor اعلام میکنیم، پس از این حرف، هر عبارتی که قرار میگیرد، یک عبارت معتبر #C است.
یا حتی میتوان یک متد جدید را مانند CustomToUpper در قطعه کد razor، تعریف کرد و از آن به صورت زیر استفاده نمود:
در این مثالها، ابتدای عبارت #C تعریف شده با حرف @ شروع میشود و انتهای آنرا خود کامپایلر razor بر اساس بسته شدن تگ p تعریف شده، تشخیص میدهد. اما اگر قصد داشته باشیم برای مثال جمع دو عدد را در اینجا محاسبه کنیم چطور؟
در این حالت امکان تشخیص ابتدا و انتهای عبارت #C توسط کامپایلر میسر نیست. برای رفع این مشکل میتوان از پرانتزها استفاده کرد:
نمونهی دیگر نیاز به تعریف ابتدا و انتهای یک قطعه کد، در حین تعریف مدیریت کنندگان رویدادها است:
در اینجا onclick@ مشخص میکند که با کلیک بر روی این دکمه قرار است قطعه کد #C ای اجرا شود. سپس با استفاده از ()@ محدودهی این قطعه کد، مشخص میشود و اکنون در داخل آن میتوان یک anonymous function را تعریف کرد که خروجی آن را در قسمت console ابزارهای توسعه دهندگان مرورگر میتوان مشاهده کرد:
در اینجا اگر از Console.WriteLine("Test")@ استفاده میشد، به معنای انتساب یک رشتهی محاسبه شده به رویداد onclick بود که مجاز نیست.
روش دیگر انجام اینکار به صورت زیر است:
میتوان یک متد void را تعریف کرد و سپس فقط نام آنرا توسط @ به onlick انتساب داد. ذکر این نام، اشارهگری خواهد بود به متد اجرا نشدهی WriteLog. در این حالت اگر نیاز به ارسال پارامتری به متد WriteLog بود، چطور؟
در این حالت نیز میتوان از روش بکارگیری anonymous functionها برای تعریف پارامتر استفاده کرد.
یک نکته: اگر به اشتباه بجای WriteLogWithParam، همان WriteLog قبلی را بنویسیم، کامپایلر (در حال اجرای توسط دستور dotnet watch run) خطای زیر را نمایش میدهد؛ پیش از اینکه برنامه در مرورگر اجرا شود:
امکان تعریف کلاسها در فایلهای razor.
در فایلهای razor.، محدود به تعریف یک سری متدها و متغیرهای ساده نیستیم. در اینجا امکان تعریف کلاسها نیز وجود دارد و همچنین میتوان از کلاسهای خارجی (کلاسهایی که خارج از فایل razor جاری تعریف شدهاند) نیز استفاده کرد.
برای نمونه در اینجا یک کلاس کمکی را جهت تعریف متد MyCustomToUpper، اضافه کردهایم. در ادامه نحوهی استفاده از این متد را در پاراگراف تعریف شده، مشاهده میکنید که همانند کار با کلاس و متدهای متداول #C است.
البته این کلاس را تنها میتوان داخل همین کامپوننت استفاده کرد. برای اینکه بتوان از امکانات این کلاس، در سایر کامپوننتها نیز استفاده کرد، میتوان آنرا در پروژهی Shared قرار داد. اگر به تصویر ابتدای مطلب جاری دقت کنید، سه پروژه ایجاد شدهاست:
الف) پروژهی کلاینت: که همان WASM است.
ب) پروژهی سرور: که یک پروژهی ASP.NET Core Web API ارائه کنندهی سرویس و API آب و هوا است و همچنین هاست کنندهی WASM ما.
ج) پروژهی Shared: کدهای این پروژه، بین هر دو پروژه به اشتراک گذاشته میشوند و برای مثال محل مناسبی است برای تعریف DTO ها. برای نمونه WeatherForecast.cs قرار گرفتهی در آن، DTO یا data transfer object سرویس API برنامه است که قرار است به کلاینت بازگشت داده شود. به این ترتیب دیگر نیازی نخواهد بود تا این تعاریف را در پروژههای سرور و کلاینت تکرار کنیم و میتوان کدهای اینگونه را به اشتراک گذاشت.
کاربرد دیگر آن تعریف کلاسهای کمکی است؛ مانند StringUtils فوق. به همین به پروژهی Shared مراجعه کرده و کلاس StringUtils را به صورت زیر در آن تعریف میکنیم (و یا حتی میتوان این قطعه کد را داخل یک پوشهی جدید، در همان پروژهی WASM نیز قرار داد):
اگر به فایلهای csproj دو پروژهی سرور و کلاینت جاری مراجعه کنیم، از پیش، مدخلی را به فایل Shared\BlazorRazorSample.Shared.csproj دارند. بنابراین جهت معرفی این اسمبلی به آنها، نیاز به کار خاصی نیست و از پیش، ارجاعی به آن تعریف شدهاست.
پس از آن روش استفادهی از این کلاس کمکی خارجی اشتراکی به صورت زیر است:
ابتدا فضای نام این کلاس را با استفاده از using@ مشخص میکنیم و سپس امکان دسترسی به امکانات آن میسر میشود.
یک نکته: میتوان به فایل Client\_Imports.razor مراجعه و مدخل زیر را به انتهای آن اضافه کرد:
به این ترتیب دیگر نیازی به ذکر این using@ تکراری، در هیچکدام از فایلهای razor. پروژهی کلاینت نخواهد بود؛ چون تعاریف درج شدهی در فایل Client\_Imports.razor سراسری هستند.
کار با حلقهها در فایلهای razor.
همانطور که عنوان شد، یکی از کاربردهای پروژهی Shared، امکان به اشتراک گذاشتن مدلها، در برنامههای کلاینت و سرور است. برای مثال یک پوشهی جدید Models را در این پروژه ایجاد کرده و کلاس MovieDto را به صورت زیر در آن تعریف میکنیم:
سپس به فایل Client\_Imports.razor مراجعه کرده و فضای نام این پوشه را اضافه میکنیم؛ تا دیگر نیازی به تکرار آن در تمام فایلهای razor. برنامهی کلاینت نباشد:
اکنون میخواهیم لیستی از فیلمها را در فایل Client\Pages\Index.razor نمایش دهیم:
در اینجا در ابتدا لیستی از MovieDtoها در قسمت code@ تعریف شده و سپس روش استفادهی از یک حلقهی foreach سیشارپ را در کدهای razor نوشته شده، مشاهده میکنید که این خروجی را ایجاد میکند:
یک نکته: در حین تعریف فیلدهای code@، امکان استفادهی از var وجود ندارد؛ مگر اینکه از آن بخواهیم در داخل بدنهی یک متد استفاده کنیم.
و یا نمونهی دیگری از حلقههای #C مانند for را میتوان به صورت زیر تعریف کرد:
در اینجا روش تغییر پویای background-color هر ردیف را نیز به کمک کدهای razor، مشاهده میکنید. اگر شمارهی ردیفی زوج بود، با آبی نمایش داده میشود؛ در غیراینصورت با قرمز. در اینجا نیز از ()@ برای تعیین محدودهی کدهای #C نوشته شده، کمک گرفتهایم.
نمایش شرطی عبارات در فایلهای razor.
اگر به مثال توکار Client\Pages\FetchData.razor مراجعه کنیم (مربوط به حالت host-- که در ابتدای مطلب عنوان شد)، کدهای زیر قابل مشاهده هستند:
در این مثال، روش کار با یک سرویس تزریق شدهی async که قرار است از Web API اطلاعاتی را دریافت کند، مشاهده میکنید. در اینجا برخلاف مثال قبلی ما، از روال رویدادگردان OnInitializedAsync برای مقدار دهی لیست یا آرایهای از اطلاعات وضعیت هوا استفاده شدهاست (و نه به صورت مستقیم در یک فیلد قسمت code@). این مورد جزو life-cycleهای کامپوننتهای razor است که در قسمتهای بعد بیشتر بررسی خواهد شد. متد OnInitializedAsync برای بارگذاری اطلاعات یک سرویس از راه دور استفاده میشود و در اولین بار اجرای کامپوننت فراخوانی خواهد شد. نکتهی مهمی که در اینجا وجود دارد، نال بودن فیلد forecasts در زمان رندر اولیهی کامپوننت جاری است؛ از این جهت که کار دریافت اطلاعات از سرور زمانبر است ولی رندر کامپوننت، به صورت آنی صورت میگیرد. در این حالت زمانیکه نوبت به اجرای foreach (var forecast in forecasts)@ میرسد، برنامه با یک استثنای نال بودن forecasts، متوقف خواهد شد؛ چون هنوز کار OnInitializedAsync به پایان نرسیدهاست:
برای رفع این مشکل، ابتدا یک if@ مشاهده میشود، تا نال بودن forecasts را بررسی کند:
و همچنین عبارت در حال بارگذاری را نمایش میدهد. سپس در قسمت else آن، نمایش اطلاعات دریافت شده را توسط یک حلقهی foreach مشاهده میکنید. با مقدار دهی forecasts در متد OnInitializedAsync، مجددا کار رندر جدول انجام خواهد شد.
روش نمایش عبارات HTML در فایلهای razor.
فرض کنید عنوان اول فیلم مثال جاری، به همراه یک تگ HTML هم هست:
در این حالت اگر برنامه را اجرا کنیم، خروجی آن دقیقا به صورت <Title: <i>Movie 1</i خواهد بود. این مورد به دلایل امنیتی انجام شدهاست. اگر پیشتر تگهای HTML را تمیز کردهاید و مطمئن هستید که خطری را ایجاد نمیکنند، میتوانید با استفاده از روش زیر، آنها را رندر کرد:
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید: Blazor-5x-Part-03.zip
برای اجرای آن وارد پوشهی Server شده و دستور dotnet run را اجرا کنید.
ایجاد یک پروژهی جدید Blazor WASM
برای پیاده سازی و اجرای مثالهای این قسمت، نیاز به یک پروژهی جدید Blazor WASM را داریم که میتوان آنرا با اجرای دستور dotnet new blazorwasm --hosted در یک پوشهی خالی، ایجاد کرد.
یک نکته: دستور فوق به همراه یک سری پارامتر اختیاری مانند hosted-- نیز هست. برای مشاهدهی لیست آنها دستور dotnet new blazorwasm --help را صادر کنید. برای مثال ذکر پارامتر hosted-- سبب میشود تا یک ASP.NET Core host نیز برای Blazor WebAssembly app ایجاد شده تولید شود.
حالت hosted-- آن یک چنین ساختاری را دارد که از سه پروژه و پوشهی Client ،Server و Shared تشکیل میشود:
در اینجا یک پروژهی خالی WASM ایجاد شده که برخلاف حالت معمولی dotnet new blazorwasm که در قسمت قبل آنرا بررسی کردیم، دیگر از فایل استاتیک wwwroot\sample-data\weather.json در آن خبری نیست. بجای آن، یک پروژهی استاندارد ASP.NET Core Web API را در پوشهی جدید Server ایجاد کرده که کار ارائهی اطلاعات این سرویس آب و هوا را انجام میدهد و برنامهی WASM ایجاد شده، این اطلاعات را توسط HTTP Client خود، از سرور Web API دریافت میکند.
بنابراین اگر مدل برنامهای که قصد دارید تهیه کنید، ترکیبی از یک Web API و WASM است، روش hosted--، آغاز آنرا بسیار ساده میکند.
نکته: روش اجرای این نوع برنامهها با اجرای دستور dotnet run در داخل پوشهی Server پروژه، انجام میشود. با اینکار هم سرور ASP.NET Core آغاز میشود و هم برنامهی WASM توسط آن ارائه میگردد. در این حالت اگر آدرس https://localhost:5001 را در مرورگر باز کنیم، هم قسمتهای بدون نیاز به سرور پروژهی WASM قابل دسترسی است (مانند کار با شمارشگر آن) و هم قسمت دریافت اطلاعات از سرور آن، در منوی Fetch Data.
شروع به کار با Razor
پس از ایجاد یک پروژهی جدید WASM، به فایل Client\Pages\Index.razor آن مراجعه کرده و محتوای پیشفرض آنرا بجز سطر اول زیر، حذف میکنیم:
@page "/"
در فایلهای razor. میتوان ترکیبی از کدهای #C و HTML را نوشت. برای مثال:
@page "/" <p>Hello, @name</p> @code { string name = "Vahid N."; }
یک نکته: با توجه به اینکه تغییرات زیادی را در فایل جاری اعمال خواهیم کرد، بهتر است برنامه را با دستور dotnet watch run اجرا کرد، تا این تغییرات را تحت نظر قرار داده و آنها را به صورت خودکار کامپایل کند. به این صورت دیگر نیازی نخواهد بود به ازای هر تغییر، یکبار دستور dotnet run اجرا شود.
در زمان درج متغیرهای #C در بین کدهای HTML توسط razor، استفاده از تمام متدهای الحاقی زبان #C نیز مجاز هستند؛ مانند:
<p>Hello, @name.ToUpper()</p>
یا حتی میتوان یک متد جدید را مانند CustomToUpper در قطعه کد razor، تعریف کرد و از آن به صورت زیر استفاده نمود:
@page "/" <p>Hello, @name.ToUpper()</p> <p>Hello, @CustomToUpper(name)</p> @code { string name = "Vahid N."; string CustomToUpper(string value) => value.ToUpper(); }
<p>Let's add 2 + 2 : @2 + 2 </p>
<p>Let's add 2 + 2 : @(2 + 2) </p>
<button @onclick="@(()=>Console.WriteLine("Test"))">Click me</button>
در اینجا اگر از Console.WriteLine("Test")@ استفاده میشد، به معنای انتساب یک رشتهی محاسبه شده به رویداد onclick بود که مجاز نیست.
روش دیگر انجام اینکار به صورت زیر است:
@page "/" <button @onclick="@WriteLog">Click me 2</button> @code { void WriteLog() { Console.WriteLine("Test"); } }
@page "/" <button @onclick="@(()=>WriteLogWithParam("Test 3"))">Click me 3</button> @code { void WriteLogWithParam(string value) { Console.WriteLine(value); } }
یک نکته: اگر به اشتباه بجای WriteLogWithParam، همان WriteLog قبلی را بنویسیم، کامپایلر (در حال اجرای توسط دستور dotnet watch run) خطای زیر را نمایش میدهد؛ پیش از اینکه برنامه در مرورگر اجرا شود:
BlazorRazorSample\Client\Pages\Index.razor(12,25): error CS1501: No overload for method 'WriteLog' takes 1 arguments
امکان تعریف کلاسها در فایلهای razor.
در فایلهای razor.، محدود به تعریف یک سری متدها و متغیرهای ساده نیستیم. در اینجا امکان تعریف کلاسها نیز وجود دارد و همچنین میتوان از کلاسهای خارجی (کلاسهایی که خارج از فایل razor جاری تعریف شدهاند) نیز استفاده کرد.
@page "/" <p>Hello, @StringUtils.MyCustomToUpper(name)</p> @code { public class StringUtils { public static string MyCustomToUpper(string value) => value.ToUpper(); } }
البته این کلاس را تنها میتوان داخل همین کامپوننت استفاده کرد. برای اینکه بتوان از امکانات این کلاس، در سایر کامپوننتها نیز استفاده کرد، میتوان آنرا در پروژهی Shared قرار داد. اگر به تصویر ابتدای مطلب جاری دقت کنید، سه پروژه ایجاد شدهاست:
الف) پروژهی کلاینت: که همان WASM است.
ب) پروژهی سرور: که یک پروژهی ASP.NET Core Web API ارائه کنندهی سرویس و API آب و هوا است و همچنین هاست کنندهی WASM ما.
ج) پروژهی Shared: کدهای این پروژه، بین هر دو پروژه به اشتراک گذاشته میشوند و برای مثال محل مناسبی است برای تعریف DTO ها. برای نمونه WeatherForecast.cs قرار گرفتهی در آن، DTO یا data transfer object سرویس API برنامه است که قرار است به کلاینت بازگشت داده شود. به این ترتیب دیگر نیازی نخواهد بود تا این تعاریف را در پروژههای سرور و کلاینت تکرار کنیم و میتوان کدهای اینگونه را به اشتراک گذاشت.
کاربرد دیگر آن تعریف کلاسهای کمکی است؛ مانند StringUtils فوق. به همین به پروژهی Shared مراجعه کرده و کلاس StringUtils را به صورت زیر در آن تعریف میکنیم (و یا حتی میتوان این قطعه کد را داخل یک پوشهی جدید، در همان پروژهی WASM نیز قرار داد):
namespace BlazorRazorSample.Shared { public class StringUtils { public static string MyNewCustomToUpper(string value) => value.ToUpper(); } }
پس از آن روش استفادهی از این کلاس کمکی خارجی اشتراکی به صورت زیر است:
@page "/" @using BlazorRazorSample.Shared <p>Hello, @StringUtils.MyNewCustomToUpper(name)</p>
یک نکته: میتوان به فایل Client\_Imports.razor مراجعه و مدخل زیر را به انتهای آن اضافه کرد:
@using BlazorRazorSample.Shared
کار با حلقهها در فایلهای razor.
همانطور که عنوان شد، یکی از کاربردهای پروژهی Shared، امکان به اشتراک گذاشتن مدلها، در برنامههای کلاینت و سرور است. برای مثال یک پوشهی جدید Models را در این پروژه ایجاد کرده و کلاس MovieDto را به صورت زیر در آن تعریف میکنیم:
using System; namespace BlazorRazorSample.Shared.Models { public class MovieDto { public string Title { set; get; } public DateTime ReleaseDate { set; get; } } }
@using BlazorRazorSample.Shared.Models
@page "/" <div> <h3>Movies</h3> @foreach(var movie in movies) { <p>Title: <b>@movie.Title</b></p> <p>ReleaseDate: @movie.ReleaseDate.ToString("dd MMM yyyy")</p> } </div> @code { List<MovieDto> movies = new List<MovieDto> { new MovieDto { Title = "Movie 1", ReleaseDate = DateTime.Now.AddYears(-1) }, new MovieDto { Title = "Movie 2", ReleaseDate = DateTime.Now.AddYears(-2) }, new MovieDto { Title = "Movie 3", ReleaseDate = DateTime.Now.AddYears(-3) } }; }
یک نکته: در حین تعریف فیلدهای code@، امکان استفادهی از var وجود ندارد؛ مگر اینکه از آن بخواهیم در داخل بدنهی یک متد استفاده کنیم.
و یا نمونهی دیگری از حلقههای #C مانند for را میتوان به صورت زیر تعریف کرد:
@for(var i = 0; i < movies.Count; i++) { <div style="background-color: @(i % 2 == 0 ? "blue" : "red")"> <p>Title: <b>@movies[i].Title</b></p> <p>ReleaseDate: @movies[i].ReleaseDate.ToString("dd MMM yyyy")</p> </div> }
نمایش شرطی عبارات در فایلهای razor.
اگر به مثال توکار Client\Pages\FetchData.razor مراجعه کنیم (مربوط به حالت host-- که در ابتدای مطلب عنوان شد)، کدهای زیر قابل مشاهده هستند:
@page "/fetchdata" @using BlazorRazorSample.Shared @inject HttpClient Http <h1>Weather forecast</h1> <p>This component demonstrates fetching data from the server.</p> @if (forecasts == null) { <p><em>Loading...</em></p> } else { <table class="table"> <thead> <tr> <th>Date</th> <th>Temp. (C)</th> <th>Temp. (F)</th> <th>Summary</th> </tr> </thead> <tbody> @foreach (var forecast in forecasts) { <tr> <td>@forecast.Date.ToShortDateString()</td> <td>@forecast.TemperatureC</td> <td>@forecast.TemperatureF</td> <td>@forecast.Summary</td> </tr> } </tbody> </table> } @code { private WeatherForecast[] forecasts; protected override async Task OnInitializedAsync() { forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast"); } }
برای رفع این مشکل، ابتدا یک if@ مشاهده میشود، تا نال بودن forecasts را بررسی کند:
@if (forecasts == null) { <p><em>Loading...</em></p> }
روش نمایش عبارات HTML در فایلهای razor.
فرض کنید عنوان اول فیلم مثال جاری، به همراه یک تگ HTML هم هست:
new MovieDto { Title = "<i>Movie 1</i>", ReleaseDate = DateTime.Now.AddYears(-1) },
<p>Title: <b>@((MarkupString)movie.Title)</b></p>
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید: Blazor-5x-Part-03.zip
برای اجرای آن وارد پوشهی Server شده و دستور dotnet run را اجرا کنید.
یک نکتهی تکمیلی: چگونه VSCode را برای NET Core 3.0. و C# 8.0 آماده کنیم؟
مرحلهی اول: نصب SDK مربوطه
در این تاریخ، این SDK در مرحلهی پیشنمایش است و نگارش نهایی آن قرار است صرفا با VS 2019 سازگار و هماهنگ باشد (و با VS 2017 کار نمیکند)؛ اما هم اکنون در VSCode قابل استفادهاست. برای این منظور SDK آنرا از آدرس https://dotnet.microsoft.com/download/dotnet-core/3.0 دریافت و نصب کنید. پس از نصب، یک چنین خروجی را در خط فرمان مشاهده خواهید کرد:
مشکل: پس از نصب نگارش 3، ممکن است برنامههایی که از SDK نگارش 2 استفاده میکنند، به مشکل بر بخورند.
راه حل: برنامههای مبتنی بر NET Core.، شماره نگارش SDK خود را از فایل ویژهای به نام global.json دریافت میکنند. اگر این فایل در ریشهی پروژهی شما وجود نداشته باشد، یعنی همواره از آخرین شمارهی SDK نصب شده استفاده شود. بنابراین ابتدا لیست SDKهای نصب شده را با دستور زیر پیدا کنید:
سپس برای پروژههای قدیمی خود که فعلا قصد به روز رسانی آنها را ندارید، یک فایل global.json را به صورت زیر، در ریشهی پروژه تولید کنید:
در اینجا 2.2.100 یکی از شمارههایی است که توسط دستور dotnet --list-sdks یافتهاید و پروژهی قبلی شما بر اساس آن کار میکند.
مرحلهی دوم: نصب افزونهی پیشنمایش VSCode مخصوص C# 8.0
در این تاریخ هنوز این افزونه در نگارش بتای آن قرار دارد. بنابراین در لیست دریافتهای خودکار VSCode قرار نمیگیرد و باید دستی نصب شود. برای این منظور به آدرس https://github.com/OmniSharp/omnisharp-vscode/releases مراجعه کرده و آخرین نگارش بتای آنرا دریافت کنید.
در VSCode، قسمتیکه افزونهها را نمایش میدهد، یک دکمهی ... مانند وجود دارد. بر روی آن که کلیک کنید. در منوی باز شده، گزینهی install from vsix نیز موجود است که دقیقا برای نصب دستی یک چنین افزونههایی پیشبینی شدهاست. پس از نصب فایل vsix دریافت شدهی از GitHub، شماره نگارش 1.18.0-beta7 در قسمت افزونههای VSCode قابل مشاهده خواهد بود.
مرحلهی آخر: ایجاد یک پروژهی جدید مخصوص NET Core 3x. با پشتیبانی از C# 8.0
اکنون یک پوشهی جدید را ایجاد کرده و در خط فرمان دستور dotnet new console را صادر کنید. سپس فایل csproj آنرا به صورت زیر تغییر دهید تا از NET Core 3x. و C# 8.0 و قابلیت جدید Nullable Reference Types آن پشتیبانی کند:
یک نکته: اگر دستور dotnet new classlib را صادر کنید، هنوز TargetFramework آنرا netstandard2.0 تنظیم میکند. فایل csproj آن نیز باید دقیقا مانند مثال فوق تنظیم شود، با این تفاوت که سطر OutputType را ندارد.
مرحلهی اول: نصب SDK مربوطه
در این تاریخ، این SDK در مرحلهی پیشنمایش است و نگارش نهایی آن قرار است صرفا با VS 2019 سازگار و هماهنگ باشد (و با VS 2017 کار نمیکند)؛ اما هم اکنون در VSCode قابل استفادهاست. برای این منظور SDK آنرا از آدرس https://dotnet.microsoft.com/download/dotnet-core/3.0 دریافت و نصب کنید. پس از نصب، یک چنین خروجی را در خط فرمان مشاهده خواهید کرد:
> dotnet --version 3.0.100-preview-010184
مشکل: پس از نصب نگارش 3، ممکن است برنامههایی که از SDK نگارش 2 استفاده میکنند، به مشکل بر بخورند.
راه حل: برنامههای مبتنی بر NET Core.، شماره نگارش SDK خود را از فایل ویژهای به نام global.json دریافت میکنند. اگر این فایل در ریشهی پروژهی شما وجود نداشته باشد، یعنی همواره از آخرین شمارهی SDK نصب شده استفاده شود. بنابراین ابتدا لیست SDKهای نصب شده را با دستور زیر پیدا کنید:
> dotnet --list-sdks
> dotnet new globaljson --sdk-version 2.2.100 > type global.json
مرحلهی دوم: نصب افزونهی پیشنمایش VSCode مخصوص C# 8.0
در این تاریخ هنوز این افزونه در نگارش بتای آن قرار دارد. بنابراین در لیست دریافتهای خودکار VSCode قرار نمیگیرد و باید دستی نصب شود. برای این منظور به آدرس https://github.com/OmniSharp/omnisharp-vscode/releases مراجعه کرده و آخرین نگارش بتای آنرا دریافت کنید.
در VSCode، قسمتیکه افزونهها را نمایش میدهد، یک دکمهی ... مانند وجود دارد. بر روی آن که کلیک کنید. در منوی باز شده، گزینهی install from vsix نیز موجود است که دقیقا برای نصب دستی یک چنین افزونههایی پیشبینی شدهاست. پس از نصب فایل vsix دریافت شدهی از GitHub، شماره نگارش 1.18.0-beta7 در قسمت افزونههای VSCode قابل مشاهده خواهد بود.
مرحلهی آخر: ایجاد یک پروژهی جدید مخصوص NET Core 3x. با پشتیبانی از C# 8.0
اکنون یک پوشهی جدید را ایجاد کرده و در خط فرمان دستور dotnet new console را صادر کنید. سپس فایل csproj آنرا به صورت زیر تغییر دهید تا از NET Core 3x. و C# 8.0 و قابلیت جدید Nullable Reference Types آن پشتیبانی کند:
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <OutputType>Exe</OutputType> <TargetFramework>netcoreapp3.0</TargetFramework> <LangVersion>8.0</LangVersion> <NullableContextOptions>enable</NullableContextOptions> </PropertyGroup> </Project>
اکنون یک چنین پروژهای قابلیت کار و دیباگ در VSCode را پیدا میکند.
نظرات مطالب
بیلد سیستم گریدل Gradle Build System
این سیستم در حالی که امکانات خوبی دارد و مشکلات زیادی را نسبت به سیستمهای قدیمی رفع کرده ولی عین حال یکی از کندترین سیستمهای بیلد موجود است. به طوری که در Android Studio یکی از عذابهای برنامه نویسی آندروید مربوط به این سیستم میشود.
مهم نیست در ایران باشید یا آمریکا، اینترنت با فیبر نوری داشته باشید یا دایال آپ، یک سوپر کامپیوتر داشته باشید یا یک سیتسم ضعیف، آنلاین کار کنید یا آفلاین و .... در هر صورت در هر بار بیلد کلی از وقت شما را میگیرد...
اشتراکها