- Label Control
- Button Control
- Grid/ListBox Control
- ComboBox Control
- CheckBox Control
- Radio Button Group Control
- Image Control
- TreeView Control
- ProgressBar Control
- Slider Control
- Panel Control
- Calender Control
- DatePicker Control
- Animated Bar Graph Control
- Animated Pie Chart Control
- Animated Multi Line Graph Control
- Animated Gauge Chart Control
- Animated Radar Graph Control
- Animated Line Area Graph Control
- Candlesticks Graph Control
- Doughnut Chart Control
- Stacked Bar Chart Control
- Bars mixed with Labeled Line Chart Control
- Tab Control
- Image Map Control
- Menu Bar Control
- TextBox Control
- Image Fader Control
- Image Slider Control
- Boundary Fillable Map Control
- Multi Line Label Control
- Word Processor Control
- Virtual Keyboard Control
- Splitter Control
این کتابخانه شامل کنترلهای زیر بوده که در مقاله در عمل نمایش داده شدهاند:
برخی اوقات نیاز است در یک فرم ویندوزی، کنترلهای آنرا در حال اجرا با استفاده از ماوس جابجا کنیم و یا اندازهی آنها را تغییر بدیم.
در وب راهکارهای مختلفی برای این کار ارائه شده، ولی این راهها معمولا یا فقط برای تغییر مکان و یا فقط برای تغییر اندازه کنترلها ارائه شدهاند. من یکی از مقالات کد پروجکت را که به جابجا کردن کنترلها پرداخته بود، توسعه دادم که امکان تغییر اندازه هم به آن اضافه شود. مقالهی من (به زبان انگلیسی) در اینجا قرار دارد.
چون از کلاس و متدهای استاتیک استفاده کردم، روش استفاده از این کلاس ساده بوده و افزودن قابلیت تغییر اندازه و جابجایی زمان اجرا با ماوس برای هر کنترل فقط با یک خط کد قابل انجام است:
نحوهی استفاده از کلاس:
برای فعال کردن قابلیت تغییر اندازه و جابجایی یک کنترل در حال اجرای برنامه با موس ما باید متد Init از کلاس MoveAndResizeControls را فراخوانی کنیم و کنترل را به عنوان پارامتر به آن بفرستیم.
اگر که ما بخواهیم به همراه تغییر کنترل ، خواص container آن را هم تغییر دهیم. باید کنترل container را به عنوان پارامتر دوم به متد مذکور ارسال کنیم.
برخی اوقات ممکن است که ما فقط بخواهیم که یا کنترلها را جابجا کنیم و یا اندازهی آنها را تغییر دهیم؛ در این مواقع ما باید خاصیت WorkType کلاس MoveAndResizeControls را تغییر دهیم به یکی از مقادیر ذیل تغییر دهیم .
مثالی از نحوهی کار با کلاس :
نکته :بعد از انجام تغییرات، جهت ذخیره وضعیت کنترلها و بازیابی مجدد آنها میتوان از متدهای زیر استفاده کرد:
در وب راهکارهای مختلفی برای این کار ارائه شده، ولی این راهها معمولا یا فقط برای تغییر مکان و یا فقط برای تغییر اندازه کنترلها ارائه شدهاند. من یکی از مقالات کد پروجکت را که به جابجا کردن کنترلها پرداخته بود، توسعه دادم که امکان تغییر اندازه هم به آن اضافه شود. مقالهی من (به زبان انگلیسی) در اینجا قرار دارد.
چون از کلاس و متدهای استاتیک استفاده کردم، روش استفاده از این کلاس ساده بوده و افزودن قابلیت تغییر اندازه و جابجایی زمان اجرا با ماوس برای هر کنترل فقط با یک خط کد قابل انجام است:
ControlMoverOrResizer.Init(button1);
برای فعال کردن قابلیت تغییر اندازه و جابجایی یک کنترل در حال اجرای برنامه با موس ما باید متد Init از کلاس MoveAndResizeControls را فراخوانی کنیم و کنترل را به عنوان پارامتر به آن بفرستیم.
ControlMoverOrResizer.Init(button1);
ControlMoverOrResizer.Init(button2,panel1);
internal enum MoveOrResize { Move, Resize, MoveAndResize }
مثالی از نحوهی کار با کلاس :
using System; using System.Windows.Forms; using ControlManager; namespace MoveAndResizeControls { public partial class Form1 : Form { public Form1() { InitializeComponent(); } private void Form1_Load(object sender, EventArgs e) { ControlMoverOrResizer.Init(button1); ControlMoverOrResizer.Init(groupBox1); ControlMoverOrResizer.Init(textBox1); ControlMoverOrResizer.Init(button2,panel1); comboBox1.SelectedIndex = 0; } private void comboBox1_SelectedIndexChanged(object sender, EventArgs e) { switch (comboBox1.SelectedIndex) { case 0: ControlMoverOrResizer.WorkType=ControlMoverOrResizer.MoveOrResize.MoveAndResize; break; case 1: ControlMoverOrResizer.WorkType = ControlMoverOrResizer.MoveOrResize.Move; break; case 2: ControlMoverOrResizer.WorkType = ControlMoverOrResizer.MoveOrResize.Resize; break; } } } }
نکته :بعد از انجام تغییرات، جهت ذخیره وضعیت کنترلها و بازیابی مجدد آنها میتوان از متدهای زیر استفاده کرد:
GetSizeAndPositionOfControlsToString , SetSizeAndPositionOfControlsFromString
شکل حالت نتیجه:
در مورد glimpse پیشتر مطالبی در سایت منتشر شده است :
آشنایی و بررسی ابزار Glimpse
بعد از آپلود سایت ما میتوانیم دسترسی به تنظیمات خاص glimpse را تنها به کاربران عضو محدود کنیم:
یا میتوانیم آنرا غیرفعال کنیم :
همچنین میتوانیم با پیاده سازی اینترفیس IRuntimePolicy سیاستهای مختلف نمایش تبهای glimpse را تعیین کنیم :
زمانیکه glimpse را از طریق Nuget نصب میکنید کلاس فوق به صورت اتوماتیک به پروژه اضافه میشود با این تفاوت که به صورت کامنت شده است تنها کاری شما باید انجام بدید کدهای فوق را از حالت کامنت خارج کنید و Role مربوطه را جایگزین کنید.
نکته : کلاس فوق نیاز به رجیستر شدن ندارد و تشخیص آن توسط Glimpse به صورت خودکار انجام میشود.
آشنایی و بررسی ابزار Glimpse
بعد از آپلود سایت ما میتوانیم دسترسی به تنظیمات خاص glimpse را تنها به کاربران عضو محدود کنیم:
<location path="Glimpse.axd" > <system.web> <authorization> <allow users="Administrator" /> <deny users="*" /> </authorization> </system.web> </location>
یا میتوانیم آنرا غیرفعال کنیم :
<glimpse defaultRuntimePolicy="Off" xdt:Transform="SetAttributes"> </glimpse>
همچنین میتوانیم با پیاده سازی اینترفیس IRuntimePolicy سیاستهای مختلف نمایش تبهای glimpse را تعیین کنیم :
using Glimpse.AspNet.Extensions; using Glimpse.Core.Extensibility; namespace Test { public class GlimpseSecurityPolicy:IRuntimePolicy { public RuntimePolicy Execute(IRuntimePolicyContext policyContext) { // You can perform a check like the one below to control Glimpse's permissions within your application. // More information about RuntimePolicies can be found at http://getglimpse.com/Help/Custom-Runtime-Policy var httpContext = policyContext.GetHttpContext(); if (!httpContext.User.IsInRole("Administrator ")) { return RuntimePolicy.Off; } return RuntimePolicy.On; } public RuntimeEvent ExecuteOn { get { return RuntimeEvent.EndRequest; } } } }
زمانیکه glimpse را از طریق Nuget نصب میکنید کلاس فوق به صورت اتوماتیک به پروژه اضافه میشود با این تفاوت که به صورت کامنت شده است تنها کاری شما باید انجام بدید کدهای فوق را از حالت کامنت خارج کنید و Role مربوطه را جایگزین کنید.
نکته : کلاس فوق نیاز به رجیستر شدن ندارد و تشخیص آن توسط Glimpse به صورت خودکار انجام میشود.
گروه بندی دکمهها در Twitter bootstrap
در این مثال دو دکمه را ملاحظه میکنید که در یک div با کلاس btn-group محصور شدهاند. به این ترتیب این دو دکمه در کنار هم، همانند دکمههای یک toolbar قرار خواهند گرفت. همچنین در بوتاسترپ امکان انتساب ویژگی data-toggle=buttons-radio نیز به این div وجود دارد. در این حالت، این دکمهها همانند دکمههای رادیویی رفتار خواهند کرد:
در ادامه قصد داریم یک Editor template و یک Display template مخصوص را جهت تدارک یک چنین دکمههایی، برای مدیریت خواص Boolean ایجاد کنیم. به عبارتی اگر مدل برنامه چنین تعاریفی را داشت:
فیلد nullable bool آن به صورت خودکار به شکل زیر رندر شود:
تهیه قالب ادیتور Views\Shared\EditorTemplates\BootstrapBoolean.cshtml
سورس کامل فایل BootstrapBoolean.cshtml را که در مسیر Views\Shared\EditorTemplates باید کپی شود، در اینجا ملاحظه میکنید.
نوع اطلاعاتی که این قالب ادیتور پردازش خواهد کرد از نوع nullable bool است. البته مشکلی هم با نوعهای bool معمولی ندارد. در حالت nullable، دکمه سومی را به نام «نامشخص» به مجموعه دکمههای «بلی» و «خیر» اضافه میکند. گاهی از اوقات در فرمهای دریافت اطلاعات نیاز است بررسی کنیم آیا واقعا کاربر اطلاعاتی را انتخاب کرده یا اینکه بدون توجه به فیلدها، بر روی دکمه ارسال کلیک کرده است. در یک چنین حالتی تعریف دکمههای سه وضعیتی Boolean میتواند مفهوم پیدا کند.
در مورد اصول تهیه این قالب در ابتدای مطلب، با کلاسهای btn-group و ویژگی data-toggle آشنا شدید. دقیقا این سه دکمه نیز در اینجا به همین نحو تعریف شدهاند.
در ابتدای نمایش یک View، خصوصا در حالت ویرایش اطلاعات، نیاز است اطلاعات موجود، به دکمههای تعریف شده اعمال شوند. در اینجا برای انتخاب یک دکمه، باید کلاس active به آن نسبت داده شود، که نحوه تدارک آنرا در سه متغیر yesIsSelected، noIsSelected و isIndeterminate ابتدای تعاریف قالب مشاهده میکنید.
سپس یک فیلد مخفی به صفحه اضافه شده است. از این جهت که به کمک jQuery، در حین کلیک بر روی یکی از دکمهها، مقدار آنرا به این فیلد که نهایتا به سرور ارسال خواهد شد، اعمال خواهیم کرد.
تهیه قالب نمایشی Views\Shared\DisplayTemplates\BootstrapBoolean.cshtml
در حالت صرفا نمایشی، فایل قالب BootstrapBoolean.cshtml قرار گرفته در مسیر Views\Shared\DisplayTemplates، یک چنین تعاریفی را خواهد داشت.
و نهایتا برای استفاده از آن تنها کافی است توسط ویژگی UIHint، نام این قالب، به خاصیت Boolean مدنظر اعمال شود:
<div class="btn-group" data-toggle="buttons-radio"> <button class="btn" type="button">بلی</button> <button class="btn" type="button">خیر</button> </div>
در ادامه قصد داریم یک Editor template و یک Display template مخصوص را جهت تدارک یک چنین دکمههایی، برای مدیریت خواص Boolean ایجاد کنیم. به عبارتی اگر مدل برنامه چنین تعاریفی را داشت:
using System.ComponentModel; using System.ComponentModel.DataAnnotations; namespace Mvc4TwitterBootStrapTest.Models { public class User { public int Id { set; get; } [DisplayName("نام")] [Required(ErrorMessage="لطفا نام را تکمیل کنید")] public string Name { set; get; } [DisplayName("نام خانوادگی")] [Required(ErrorMessage = "لطفا نام خانوادگی را تکمیل کنید")] public string LastName { set; get; } [DisplayName("فعال است؟")] [UIHint("BootstrapBoolean")] public bool? IsActive { set; get; } } }
تهیه قالب ادیتور Views\Shared\EditorTemplates\BootstrapBoolean.cshtml
@model bool? @{ var yesIsSelected = Model.HasValue && Model.Value ? "active" : null; var noIsSelected = Model.HasValue && !Model.Value ? "active" : null; var isIndeterminate = !Model.HasValue ? "active" : null; var htmlField = ViewData.TemplateInfo.HtmlFieldPrefix; } @Html.HiddenFor(model => model) <div class="btn-group" data-toggle="buttons-radio"> <button type="button" class="btn btn-info @yesIsSelected bool-@htmlField" onclick="$('#@htmlField').val(true);"> بلی</button> <button type="button" class="btn btn-info @noIsSelected bool-@htmlField" onclick="$('#@htmlField').val(false);"> خیر</button> @if (ViewData.ModelMetadata.IsNullableValueType) { <button type="button" class="btn btn-info @isIndeterminate bool-@htmlField" onclick="$('#@htmlField').val('');"> نامشخص</button> } </div>
نوع اطلاعاتی که این قالب ادیتور پردازش خواهد کرد از نوع nullable bool است. البته مشکلی هم با نوعهای bool معمولی ندارد. در حالت nullable، دکمه سومی را به نام «نامشخص» به مجموعه دکمههای «بلی» و «خیر» اضافه میکند. گاهی از اوقات در فرمهای دریافت اطلاعات نیاز است بررسی کنیم آیا واقعا کاربر اطلاعاتی را انتخاب کرده یا اینکه بدون توجه به فیلدها، بر روی دکمه ارسال کلیک کرده است. در یک چنین حالتی تعریف دکمههای سه وضعیتی Boolean میتواند مفهوم پیدا کند.
در مورد اصول تهیه این قالب در ابتدای مطلب، با کلاسهای btn-group و ویژگی data-toggle آشنا شدید. دقیقا این سه دکمه نیز در اینجا به همین نحو تعریف شدهاند.
در ابتدای نمایش یک View، خصوصا در حالت ویرایش اطلاعات، نیاز است اطلاعات موجود، به دکمههای تعریف شده اعمال شوند. در اینجا برای انتخاب یک دکمه، باید کلاس active به آن نسبت داده شود، که نحوه تدارک آنرا در سه متغیر yesIsSelected، noIsSelected و isIndeterminate ابتدای تعاریف قالب مشاهده میکنید.
سپس یک فیلد مخفی به صفحه اضافه شده است. از این جهت که به کمک jQuery، در حین کلیک بر روی یکی از دکمهها، مقدار آنرا به این فیلد که نهایتا به سرور ارسال خواهد شد، اعمال خواهیم کرد.
تهیه قالب نمایشی Views\Shared\DisplayTemplates\BootstrapBoolean.cshtml
@model bool? @if (Model.HasValue) { if (Model.Value) { <span class="label label-success">بلی</span> } else { <span class="label label-important">خیر</span> } } else { <span class="label label-inverse">نامشخص</span> }
و نهایتا برای استفاده از آن تنها کافی است توسط ویژگی UIHint، نام این قالب، به خاصیت Boolean مدنظر اعمال شود:
[UIHint("BootstrapBoolean")] public bool? IsActive { set; get; }
در ادامه میخواهیم برای هر اتاق ثبت شده، تعدادی تصویر مرتبط را نیز به سرور آپلود کرده و مشخصات آنها را در بانک اطلاعاتی ثبت کنیم. به همین جهت در این قسمت سرویس ثبت اطلاعات تصاویر در بانک اطلاعاتی و سرویس آپلود فایلها را تهیه میکنیم.
تعریف موجودیت و DbSet تصاویر یک اتاق هتل
برای اینکه بتوان اطلاعات تصاویر آپلودی را در بانک اطلاعاتی ثبت کرد، نیاز است یک رابطهی یک به چند را بین یک اتاق و تصاویر مرتبط با آن برقرار کرد. به همین جهت ابتدا به پروژهی BlazorServer.Entities.csproj مراجعه کرده و موجودیت ثبت اطلاعات تصاویر را تعریف میکنیم:
که در اینجا باید سر دیگر این رابطهی one-to-many، در جدول HotelRoom نیز تعریف شود:
در آخر باید این موجودیت جدید را به Context برنامه معرفی کرد. برای اینکار به پروژهی BlazorServer.DataAccess مراجعه کرده و DbSet متناظری را تعریف میکنیم:
پس از این تغییرات، نیاز است یکبار دیگر عملیات Migrations را اجرا کرد، تا ساختار متناظر بانک اطلاعاتی این تغییرات ایجاد شود. بنابراین توسط خط فرمان به پوشهی پروژهی BlazorServer.DataAccess وارد شده و دستورات زیر را اجرا میکنیم. در اینجا نگارش 5.0.3 باید معادل نگارشی از EF-Core باشد که از آن در حال استفادهاید:
در مورد این دستورات در قسمت 13 بیشتر بحث شدهاست.
تعریف مدل UI متناظر با هر تصویر
همانطور که در قسمت 13 نیز عنوان شد، در حین کار با رابط کاربری برنامه، با موجودیتهای بانک اطلاعاتی، به صورت مستقیم کار نخواهیم کرد و بر اساس نیازهای برنامه، یکسری کلاس DTO را تعریف میکنیم. بنابراین به پروژهی BlazorServer.Models مراجعه کرده و DTO متناظر با HotelRoomImage را به صورت زیر اضافه میکنیم:
و همچنین جهت سهولت تبدیل اطلاعات بین موجودیت تعریف شده و DTO ی آن، نگاشت AutoMapper دو طرفهای را در پروژهی BlazorServer.Models.Mappings برقرار میکنیم:
تعریف سرویس کار با HotelRoomImage
در اینجا نیز همانند سرویسی که برای انجام عملیات تجاری مرتبط با یک اتاق هتل، در قسمت 13 پیاده سازی کردیم، سرویس دیگری را در پروژهی BlazorServer.Services برای کار با تصاویر اتاقها تهیه میکنیم:
برای نمونه بر اساس اطلاعات مدل UI برنامه، نیاز است بتوانیم اطلاعات یک تصویر را ثبت و یا حذف کنیم و یا لیست تصاویر یک اتاق را از بانک اطلاعاتی دریافت کنیم؛ با این پیاده سازی:
پس از این تعاریف، به فایل BlazorServer\BlazorServer.App\Startup.cs مراجعه کرده و این سرویس را به سیستم تزریق وابستگیهای برنامه معرفی میکنیم:
تهیه سرویسی برای آپلود فایلهای یک برنامهی Blazor Server به سرور
جهت ساده سازی کار آپلود، در برنامههای Blazor Server، سرویس جدید FileUploadService را به پروژهی BlazorServer.Services اضافه میکنیم:
کار آن حذف یک فایل، بر اساس مسیر آن است و همچنین دریافت یک IBrowserFile از کاربر و ذخیره سازی اطلاعات آن در سرور؛ با این پیاده سازی:
اگر در ASP.NET Core، اطلاعات فایل ارسالی به سرور، توسط IFormFile به اکشن متدهای کنترلرها ارسال میشود، در برنامههای Blazor Server اینکار توسط IBrowserFile صورت میگیرد. کلیات کار با آن، بسیار شبیه به IFormFile است و اگر به مطلب «بررسی روش آپلود فایلها در ASP.NET Core» مراجعه کنید، تفاوت آنچنانی را مشاهده نخواهید کرد. تنها تفاوت پیاده سازی که در اینجا وجود دارد، نیاز به استفادهی از متد ()inputFile.OpenReadStream جهت دسترسی به محتوای فایل آپلودی، برای ذخیرهی آن در سمت سرور است؛ وگرنه مابقی کدهای آپلود آن، با ASP.NET Core یکی است.
همچنین برای دسترسی به IBrowserFile در یک سرویس، نیاز است وابستگی زیر را نیز به پروژهی سرویسها اضافه کرد:
پس از آن، به فایل BlazorServer\BlazorServer.App\Startup.cs مراجعه کرده و این سرویس را به سیستم تزریق وابستگیهای برنامه معرفی میکنیم:
در قسمت بعد، از این سرویسها جهت مدیریت آپلود تصاویر استفاده خواهیم کرد.
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید: Blazor-5x-Part-16.zip
تعریف موجودیت و DbSet تصاویر یک اتاق هتل
برای اینکه بتوان اطلاعات تصاویر آپلودی را در بانک اطلاعاتی ثبت کرد، نیاز است یک رابطهی یک به چند را بین یک اتاق و تصاویر مرتبط با آن برقرار کرد. به همین جهت ابتدا به پروژهی BlazorServer.Entities.csproj مراجعه کرده و موجودیت ثبت اطلاعات تصاویر را تعریف میکنیم:
using System.ComponentModel.DataAnnotations.Schema; namespace BlazorServer.Entities { public class HotelRoomImage { public int Id { get; set; } public string RoomImageUrl { get; set; } [ForeignKey("RoomId")] public virtual HotelRoom HotelRoom { get; set; } public int RoomId { get; set; } } }
namespace BlazorServer.Entities { public class HotelRoom { // ... public virtual ICollection<HotelRoomImage> HotelRoomImages { get; set; } } }
namespace BlazorServer.DataAccess { public class ApplicationDbContext : DbContext { public DbSet<HotelRoomImage> HotelRoomImages { get; set; } // ... } }
dotnet tool update --global dotnet-ef --version 5.0.3 dotnet build dotnet ef migrations --startup-project ../BlazorServer.App/ add Init --context ApplicationDbContext dotnet ef --startup-project ../BlazorServer.App/ database update --context ApplicationDbContext
تعریف مدل UI متناظر با هر تصویر
همانطور که در قسمت 13 نیز عنوان شد، در حین کار با رابط کاربری برنامه، با موجودیتهای بانک اطلاعاتی، به صورت مستقیم کار نخواهیم کرد و بر اساس نیازهای برنامه، یکسری کلاس DTO را تعریف میکنیم. بنابراین به پروژهی BlazorServer.Models مراجعه کرده و DTO متناظر با HotelRoomImage را به صورت زیر اضافه میکنیم:
namespace BlazorServer.Models { public class HotelRoomImageDTO { public int Id { get; set; } public int RoomId { get; set; } public string RoomImageUrl { get; set; } } }
using AutoMapper; using BlazorServer.Entities; namespace BlazorServer.Models.Mappings { public class MappingProfile : Profile { public MappingProfile() { // ... CreateMap<HotelRoomImageDTO, HotelRoomImage>().ReverseMap(); // two-way mapping } } }
تعریف سرویس کار با HotelRoomImage
در اینجا نیز همانند سرویسی که برای انجام عملیات تجاری مرتبط با یک اتاق هتل، در قسمت 13 پیاده سازی کردیم، سرویس دیگری را در پروژهی BlazorServer.Services برای کار با تصاویر اتاقها تهیه میکنیم:
namespace BlazorServer.Services { public interface IHotelRoomImageService { Task<int> CreateHotelRoomImageAsync(HotelRoomImageDTO imageDTO); Task<int> DeleteHotelRoomImageByImageIdAsync(int imageId); Task<int> DeleteHotelRoomImageByRoomIdAsync(int roomId); Task<List<HotelRoomImageDTO>> GetHotelRoomImagesAsync(int roomId); } }
namespace BlazorServer.Services { public class HotelRoomImageService : IHotelRoomImageService { private readonly ApplicationDbContext _dbContext; private readonly IMapper _mapper; private readonly IConfigurationProvider _mapperConfiguration; public HotelRoomImageService(ApplicationDbContext dbContext, IMapper mapper) { _dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext)); _mapper = mapper ?? throw new ArgumentNullException(nameof(mapper)); _mapperConfiguration = mapper.ConfigurationProvider; } public async Task<int> CreateHotelRoomImageAsync(HotelRoomImageDTO imageDTO) { var image = _mapper.Map<HotelRoomImage>(imageDTO); await _dbContext.HotelRoomImages.AddAsync(image); return await _dbContext.SaveChangesAsync(); } public async Task<int> DeleteHotelRoomImageByImageIdAsync(int imageId) { var image = await _dbContext.HotelRoomImages.FindAsync(imageId); _dbContext.HotelRoomImages.Remove(image); return await _dbContext.SaveChangesAsync(); } public async Task<int> DeleteHotelRoomImageByRoomIdAsync(int roomId) { var imageList = await _dbContext.HotelRoomImages.Where(x => x.RoomId == roomId).ToListAsync(); _dbContext.HotelRoomImages.RemoveRange(imageList); return await _dbContext.SaveChangesAsync(); } public Task<List<HotelRoomImageDTO>> GetHotelRoomImagesAsync(int roomId) { return _dbContext.HotelRoomImages .Where(x => x.RoomId == roomId) .ProjectTo<HotelRoomImageDTO>(_mapperConfiguration) .ToListAsync(); } } }
namespace BlazorServer.App { public class Startup { public void ConfigureServices(IServiceCollection services) { services.AddScoped<IHotelRoomImageService, HotelRoomImageService>(); // ...
تهیه سرویسی برای آپلود فایلهای یک برنامهی Blazor Server به سرور
جهت ساده سازی کار آپلود، در برنامههای Blazor Server، سرویس جدید FileUploadService را به پروژهی BlazorServer.Services اضافه میکنیم:
using Microsoft.AspNetCore.Components.Forms; using System.Threading.Tasks; namespace BlazorServer.Services { public interface IFileUploadService { void DeleteFile(string fileName, string webRootPath, string uploadFolder); Task<string> UploadFileAsync(IBrowserFile inputFile, string webRootPath, string uploadFolder); } }
using Microsoft.AspNetCore.Components.Forms; using System; using System.IO; using System.Threading.Tasks; namespace BlazorServer.Services { public class FileUploadService : IFileUploadService { private const int MaxBufferSize = 0x10000; public void DeleteFile(string fileName, string webRootPath, string uploadFolder) { var path = Path.Combine(webRootPath, uploadFolder, fileName); if (File.Exists(path)) { File.Delete(path); } } public async Task<string> UploadFileAsync(IBrowserFile inputFile, string webRootPath, string uploadFolder) { createUploadDir(webRootPath, uploadFolder); var (fileName, imageFilePath) = getOutputFileInfo(inputFile, webRootPath, uploadFolder); using (var outputFileStream = new FileStream( imageFilePath, FileMode.Create, FileAccess.Write, FileShare.None, MaxBufferSize, useAsync: true)) { using var inputStream = inputFile.OpenReadStream(); await inputStream.CopyToAsync(outputFileStream); } return $"{uploadFolder}/{fileName}"; } private static (string FileName, string FilePath) getOutputFileInfo( IBrowserFile inputFile, string webRootPath, string uploadFolder) { var fileName = Path.GetFileName(inputFile.Name); var imageFilePath = Path.Combine(webRootPath, uploadFolder, fileName); if (File.Exists(imageFilePath)) { var fileNameWithoutExtension = Path.GetFileNameWithoutExtension(fileName); var fileExtension = Path.GetExtension(fileName); fileName = $"{fileNameWithoutExtension}-{Guid.NewGuid()}{fileExtension}"; imageFilePath = Path.Combine(webRootPath, uploadFolder, fileName); } return (fileName, imageFilePath); } private static void createUploadDir(string webRootPath, string uploadFolder) { var folderDirectory = Path.Combine(webRootPath, uploadFolder); if (!Directory.Exists(folderDirectory)) { Directory.CreateDirectory(folderDirectory); } } } }
همچنین برای دسترسی به IBrowserFile در یک سرویس، نیاز است وابستگی زیر را نیز به پروژهی سرویسها اضافه کرد:
<Project Sdk="Microsoft.NET.Sdk"> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="5.0.3" /> </ItemGroup> </Project>
namespace BlazorServer.App { public class Startup { public void ConfigureServices(IServiceCollection services) { services.AddScoped<IFileUploadService, FileUploadService>(); // ...
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید: Blazor-5x-Part-16.zip
Want to learn about the latest and greatest in the 64-bit Visual Studio 2022? Join Scott Hanselman and Visual Studio product team as they take Visual Studio 2022 for a spin.
00:00 Intro
00:39 Why you should care about Visual Studio 2022?
02:20 Performance improvements in Visual Studio 2022
04:39 Why 64-bit now?
08:00 IntelliCode, type less code more
11:35 Hot reload for C++
13:47 New for WPF and WinForms (Hot Reload, Design time data, XAML
20:27 Profiling .NET apps in Visual Studio 2022
23:19 Cross platform apps with WSL and CMake in Visual Studio 2022
26:07 Testing your .NET app on Linux
28:00 Easily create CI/CD pipelines using GitHub actions with Visual Studio 2022
30:40 Balloon drop!
استثناء چیست؟
واژهی استثناء یا exception کوتاه شدهی عبارت exceptional event است. در واقع exception یک نوع رویداد است که در طول اجرای برنامه رخ میدهد و در نتیجه، جریان عادی برنامه را مختل میکند. زمانیکه خطایی درون یک متد رخ دهد، یک شیء (exception object) حاوی اطلاعاتی دربارهی خطا ایجاد خواهد شد. به فرآیند ایجاد یک exception object و تحویل دادن آن به سیستم runtime، اصطلاحاً throwing an exception یا صدور استثناء گفته میشود که در ادامه به آن خواهیم پرداخت.
بعد از اینکه یک متد استثناءایی را صادر میکند، سیستم runtime سعی در یافتن روشی برای مدیریت آن خواهد کرد.
خوب اکنون که با مفهوم استثناء آشنا شدید اجازه دهید دو سناریو را با هم بررسی کنیم.
- سناریوی اول:
فرض کنید یک فایل XML از پیش تعریف شده (برای مثال یک لیست از محصولات) قرار است در کنار برنامهی شما باشد و باید این لیست را درون برنامهی خود نمایش دهید. در این حالت برای خواندن این فایل انتظار دارید که فایل وجود داشته باشد. اگر این فایل وجود نداشته باشد برنامهی شما با اشکال روبرو خواهد شد.
- سناریوی دوم:
فرض کنید یک فایل XML از آخرین محصولات مشاهده شده توسط کاربران را به صورت cache در برنامهتان دارید. در این حالت در اولین بار اجرای برنامه توسط کاربر انتظار داریم که این فایل موجود نباشد و اگر فایل وجود نداشته باشد به سادگی میتوانیم فایل مربوط را ایجاده کرده و محصولاتی را که توسط کاربر مشاهده شده، درون این فایل اضافه کنیم.
در واقع استثناءها بستگی به حالتهای مختلفی دارد. در مثال اول وجود فایل حیاتی است ولی در حالت دوم بدون وجود فایل نیز برنامه میتواند به کار خود ادامه داده و فایل مورد نظر را از نو ایجاد کند.
استثناها مربوط به زمانی هستند که این احتمال وجود داشته باشد که برنامه طبق انتظار پیش نرود.
برای حالت اول کد زیر را داریم:
همانطور که عنوان شد در حالت اول انتظار داریم که فایلی بر روی دیسک موجود باشد. در نتیجه نیازی نیست هیچ استثناءایی را مدیریت کنیم (زیرا در واقع اگر
فایل موجود نباشد هیچ روشی برای ایجاد آن نداریم).
در مثال دوم میدانیم که ممکن است فایل از قبل موجود نباشد. بنابراین میتوانیم موجود بودن فایل را با یک شرط بررسی کنیم:
چه زمانی باید استثناءها را مدیریت کنیم؟
زمانیکه بتوان متدهایی که خروجی مورد انتظار را بر میگردانند ایجاد کرد.
اجازه دهید دوباره از مثالهای فوق استفاده کنیم:
همانطور که از نام آن پیداست این متد باید همیشه لیستی از محصولات را
برگرداند. اگر میتوانید اینکار را با استفاده از catch کردن یک استثنا
انجام دهید در غیر اینصورت نباید درون متد اینکار را انجام داد.
در متد فوق میتوانستیم از FileNotFoundException برای فایل موردنظر استفاده کنیم؛ اما مطمئن بودیم که فایل در ابتدا وجود ندارد.
در واقع استثناها حالتهایی هستند که غیرقابل پیشبینی هستند. این حالتها میتوانند یک خطای منطقی از طرف برنامهنویس و یا چیزی خارج کنترل برنامهنویس باشند (مانند خطاهای سیستمعامل، شبکه، دیسک). یعنی در بیشتر مواقع این نوع خطاها را نمیتوان مدیریت کرد.
اگر میخواهید استثناءها را catch کرده و آنها را لاگ کنید در بالاترین لایه اینکار را انجام دهید.
چه استثناءهایی باید مدیریت شوند و کدامها خیر؟
مدیریت صحیح استثناءها میتواند خیلی مفید باشد. همانطور که عنوان شد یک استثناء زمانی رخ میدهد که یک حالت استثناء در برنامه اتفاق بیفتد. این مورد را بخاطر داشته باشید، زیرا به شما یادآوری میکند که در همه جا نیازی به استفاده از try/catch نیست. در اینجا ذکر این نکته خیلی مهم است:
تنها استثناءهایی را catch کنید که بتوانید برای آن راهحلی ارائه دهید.
به عنوان مثال اگر در لایهی دسترسی به داده، خطایی رخ دهد و استثناءی SqlException صادر شود، میتوانیم آن را catch کرده و درون یک استثناء عمومیتر قرار دهیم:
همانطور که در کد فوق مشاهده میکنید به محض صدور استثنای SqlException آن
را درون قسمت catch به صورت یک استثنای عمومیتر همراه با افزودن یک سری
اطلاعات جدید صادر میکنیم. اما همانطور که عنوان شد کار لاگ کردن
استثناءها را بهتر است در لایههای بالاتر انجام دهیم.
اگر مطمئن نیستید که تمام استثناءها توسط شما مدیریت شدهاند، میتوانید در حالتهای زیر، دیگر استثناءها را مدیریت کنید:
ASP.NET: میتوانید Aplication_Error را پیادهسازی کنید. در اینجا فرصت خواهید داشت تا تمامی خطاهای مدیریت نشده را هندل کنید.
WinForms: استفاده از رویدادهای Application.ThreadException و AppDomain.CurrentDomain.UnhandledException
WCF: پیادهسازی اینترفیس IErrorHandler
ASMX: ایجاد یک Soap Extension سفارشی
ASP.NET WebAPI
چه زمانهایی باید یک استثناء صادر شود؟
صادر کردن یک استثناء به تنهایی کار سادهایی است. تنها کافی است throw را همراه شیء exception (exception object) فراخوانی کنیم. اما سوال اینجاست که چه زمانی باید یک استثناء را صادر کنیم؟ چه دادههایی را باید به استثناء اضافه کنیم؟ در ادامه به این سوالات خواهیم پرداخت.
همانطور که عنوان گردید استثناءها زمانی باید صادر شوند که یک استثناء اتفاق بیفتد.
اعتبارسنجی آرگومانها
سادهترین مثال، آرگومانهای مورد انتظار یک متد است:
در حالت فوق انتظار داریم مقداری برای پارامتر name تعیین شود. متد فوق با
آرگومان null نیز به خوبی کار خواهد کرد؛ یعنی مقدار خروجی یک خط خالی خواهد
بود. از لحاظ کدنویسی متد فوق به خوبی کار خود را انجام میدهد اما خروجی
مورد انتظار کاربر نمایش داده نمیشود. در این حالت نمیتوانیم تشخیص دهیم
مشکل از کجا ناشی میشود.
مشکل فوق را میتوانیم با صدور استثنای ArgumentNullException رفع کنیم:
خوب، name باید دارای طول ثابت و همچنین ممکن است حاوی عدد و حروف باشد:
برای حالت فوق و همچنین جلوگیری از تکرار کدهای داخل متد PrintName میتوانید یک متد Validator برای کلاسی با نام Person ایجاد کنید.
حالت دیگر صدور استثناء، زمانی است که متدی خروجی مورد انتظارمان را نتواند تحویل دهد. یک مثال بحثبرانگیز متدی با امضای زیر است:
کاملاً مشخص است که متدی همانند متد فوق زمانیکه کاربری را پیدا نکند، مقدار
null را برمیگرداند. اما این روش درستی است؟ خیر؛ زیرا همانطور که از نام
این متد پیداست باید یک کاربر به عنوان خروجی برگردانده شود.
با استفاده از بررسی null کدهایی شبیه به این را در همه جا خواهیم داشت:
به این چنین کدهایی معمولاً The null cancer گفته میشود (سرطان نال!) زیرا اجازه
دادهایم متد، خروجی null را بازگشت دهد. به جای کد فوق میتوانیم از این
روش استفاده کنیم:
نکتهایی که باید به آن توجه کنید این است که در هنگام صدور یک استثناء
اطلاعات کافی را نیز به آن پاس دهید. به عنوان مثال در
EntityNotFoundException مثال فوق پاس دادن "Failed to find user with id " + id کار دیباگ را برای مصرف کننده، راحتر خواهد کرد.
خطاهای متداول حین کار با استثناءها
مشکل کد فوق قسمت throw err است. این خط کد، محتویات stacktrace را از بین برده و استثناء را مجدداً برای شما ایجاد خواهد کرد. در این حالت هرگز نمیتوانیم تشخیص دهیم که منبع خطا از کجا آمده است. در این حالت پیشنهاد میشود که تنها از throw استفاده شود. در این حالت استثناء اصلی مجدداً صادر گردیده و مانع حذف شدن محتویات stacktrace خواهد شد(+).
هنگامی که کد فوق با خطا مواجه شود نمیتوان تنها با متن Socket failed تشخیص داد که مشکل از چه چیزی است. بنابراین پیشنهاد میشود اطلاعات کامل و در صورت امکان به صورت دقیق را به استثناء ارسال کنید. به عنوان مثال در کد زیر سعی شده است تا حد امکان context information کاملی برای استثناء ارائه شود:
نحوهی طراحی استثناءها
برای ایجاد یک استثناء سفارشی میتوانید از کلاس Exception ارثبری کنید و چهار سازندهی آن را اضافه کنید:
سازنده اول به عنوان default constructor شناخته میشود. اما پیشنهاد میشود که از آن استفاده نکنید، زیرا یک استثناء بدون context information از ارزش کمی برخوردار خواهد بود.
سازندهی دوم برای تعیین description بوده و همانطور که عنوان شد ارائه دادن context information از اهمیت بالایی برخوردار است. به عنوان مثال فرض کنید استثناء KeyNotFoundException که توسط کلاس Dictionary صادر شده است را دریافت کردهاید. این استثناء زمانی صادر خواهد شد که بخواهید به عنصری که درون دیکشنری پیدا نشده است دسترسی داشته باشید. در این حالت پیام زیر را دریافت خواهید کرد:
حالا فرض کنید اگر پیام به صورت زیر باشد چقدر باعث خوانایی و عیبیابی سادهتر خطا خواهد شد:
در نتیجه تا حد امکان سعی کنید که context information شما کاملتر باشد.
سازندهی سوم شبیه به سازندهی قبلی عمل میکند با این تفاوت که توسط پارامتر دوم میتوانیم یک استثناء دیگر را catch کرده یک استثناء جدید صادر کنیم.
سازندهی سوم زمانی مورد استفاده قرار میگیرد که بخواهید از Serialization پشتیبانی کنید (به عنوان مثال ذخیرهی استثناءها درون فایل و...)
خوب، برای یک استثناء سفارشی حداقل باید کدهای زیر را داشته باشیم:
اجباری کردن ارائهی Context information:
برای اجباری کردن context information کافی است یک فیلد اجباری درون سازنده تعریف کنیم. برای مثال اگر بخواهیم کاربر HTTP status code را برای استثناء ارائه دهد باید سازندهها را اینگونه تعریف کنیم:
همچنین بهتر است پراپرتی Message را برای نمایش پیام مناسب بازنویسی کنید:
مورد دیگری که باید در کد فوق مد نظر داشت این است که status code قابلیت سریالایز شدن را ندارد. بنابراین باید متد GetObjectData را برای سریالایز کردن بازنویسی کنیم:
در اینحالت فیلدهای اضافی در طول فرآیند Serialization به خوبی سریالایز خواهند شد.
در حین صدور استثناءها همیشه باید در نظر داشته باشیم که چه نوع context information را میتوان ارائه داد، این مورد در یافتن راهحل خیلی کمک خواهد کرد.
طراحی پیامهای مناسب
پیامهای exception مختص به توسعهدهندگان است نه کاربران نهایی.
نوشتن این نوع پیامها برای برنامهنویس کار خستهکنندهایی است. برای مثال دو مورد زیر را در نظر داشته باشید:
این نوع پیامها حتی اگر از لحاظ نوشتاری مشکلی نداشته باشند یافتن راهحل را خیلی سخت خواهند کرد. اگر در زمان برنامهنویسی با این نوع خطاها روبرو شوید ممکن است با استفاده از debugger ورودی نامعتبر را پیدا کنید. اما در یک برنامه و خارج از محیط برنامهنویسی، یافتن علت بروز خطا خیلی سخت خواهد بود.
توسعهدهندگانی که exception message را در اولویت قرار میدهند، معتقد هستند که از لحاظ تجربهی کاربری پیامها تا حد امکان باید فاقد اطلاعات فنی باشد. همچنین همانطور که پیشتر عنوان گردید این نوع پیامها همیشه باید در بالاترین سطح نمایش داده شوند نه در لایههای زیرین. همچنین پیامهایی مانند Unknown FaileType نه برای کاربر نهایی، بلکه برای برنامهنویس نیز ارزش چندانی ندارد زیرا فاقد اطلاعات کافی برای یافتن مشکل است.
در طراحی پیامها باید موارد زیر را در نظر داشته باشیم:
- امنیت:
یکی از مواردی که از اهمیت بالایی برخوردار است مسئله امنیت است از این جهت که پیامها باید فاقد مقادیر runtime باشند. زیرا ممکن است اطلاعاتی را در خصوص نحوهی عملکرد سیستم آشکار سازند.
- زبان:
همانطور که عنوان گردید پیامهای استثناء برای کاربران نهایی نیستند، زیرا کاربران نهایی ممکن است اشخاص فنی نباشند، یا ممکن است زبان آنها انگلیسی نباشد. اگر مخاطبین شما آلمانی باشند چطور؟ آیا تمامی پیامها را با زبان آلمانی خواهید نوشت؟ اگر هم اینکار را انجام دهید تکلیف استثناءهایی که توسط Base Class Library و دیگر کتابخانههای thirt-party صادر میشوند چیست؟ اینها انگلیسی هستند.
در تمامی حالتهایی که عنوان شد فرض بر این است که شما در حال نوشتن این نوع پیامها برای یک سیستم خاص هستید. اما اگر هدف نوشتن یک کتابخانه باشد چطور؟ در این حالت نمیدانید که کتابخانهی شما در کجا استفاده میشود.
اگر هدف نوشتن یک کتابخانه نباشد این نوع پیامهایی که برای کاربران نهایی باشند، وابستگیها را در سیستم افزایش خواهند داد، زیرا در این حالت پیامها به یک رابط کاربری خاص گره خواهند خورد.
خب اگر پیامها برای کاربران نهایی نیستند، پس برای کسانی مورد استفاده قرار خواهند گرفت؟ در واقع این نوع پیام میتواند به عنوان یک documentation برای سیستم شما باشند.
فرض کنید در حال استفاده از یک کتابخانه جدید هستید به نظر شما کدام یک از پیامهای زیر مناسب هستند:
یا:
یافتن مشکل در پیام اول خیلی سخت خواهد بود زیرا فاقد اطلاعات کافی برای یافتن مشکل است. اما پیام دوم مشکل را به صورت کامل توضیح داده است. در حالت اول شما قطعاً نیاز خواهید داشت تا از دیباگر برای یافتن مشکل استفاده کنید. اما در حالت دوم پیام به خوبی شما را برای یافتن راهحل راهنمایی میکند.
همیشه برای نوشتن پیامهای مناسب سعی کنید از لحاظ نوشتاری متن شما مشکلی نداشته باشد، اطلاعات کافی را درون پیام اضافه کنید و تا حد امکان نحوهی رفع مشکل را توضیح دهید
واژهی استثناء یا exception کوتاه شدهی عبارت exceptional event است. در واقع exception یک نوع رویداد است که در طول اجرای برنامه رخ میدهد و در نتیجه، جریان عادی برنامه را مختل میکند. زمانیکه خطایی درون یک متد رخ دهد، یک شیء (exception object) حاوی اطلاعاتی دربارهی خطا ایجاد خواهد شد. به فرآیند ایجاد یک exception object و تحویل دادن آن به سیستم runtime، اصطلاحاً throwing an exception یا صدور استثناء گفته میشود که در ادامه به آن خواهیم پرداخت.
بعد از اینکه یک متد استثناءایی را صادر میکند، سیستم runtime سعی در یافتن روشی برای مدیریت آن خواهد کرد.
خوب اکنون که با مفهوم استثناء آشنا شدید اجازه دهید دو سناریو را با هم بررسی کنیم.
- سناریوی اول:
فرض کنید یک فایل XML از پیش تعریف شده (برای مثال یک لیست از محصولات) قرار است در کنار برنامهی شما باشد و باید این لیست را درون برنامهی خود نمایش دهید. در این حالت برای خواندن این فایل انتظار دارید که فایل وجود داشته باشد. اگر این فایل وجود نداشته باشد برنامهی شما با اشکال روبرو خواهد شد.
- سناریوی دوم:
فرض کنید یک فایل XML از آخرین محصولات مشاهده شده توسط کاربران را به صورت cache در برنامهتان دارید. در این حالت در اولین بار اجرای برنامه توسط کاربر انتظار داریم که این فایل موجود نباشد و اگر فایل وجود نداشته باشد به سادگی میتوانیم فایل مربوط را ایجاده کرده و محصولاتی را که توسط کاربر مشاهده شده، درون این فایل اضافه کنیم.
در واقع استثناءها بستگی به حالتهای مختلفی دارد. در مثال اول وجود فایل حیاتی است ولی در حالت دوم بدون وجود فایل نیز برنامه میتواند به کار خود ادامه داده و فایل مورد نظر را از نو ایجاد کند.
استثناها مربوط به زمانی هستند که این احتمال وجود داشته باشد که برنامه طبق انتظار پیش نرود.
برای حالت اول کد زیر را داریم:
public IEnumerable<Product> GetProducts() { using (var stream = File.Read(Path.Combine(Environment.CurrentDirectory, "products.xml"))) { var serializer = new XmlSerializer(); return (IEnumerable<Product>)serializer.Deserialize(stream); } }
در مثال دوم میدانیم که ممکن است فایل از قبل موجود نباشد. بنابراین میتوانیم موجود بودن فایل را با یک شرط بررسی کنیم:
public IEnumerable<Product> GetCachedProducts() { var fullPath = Path.Combine(Environment.CurrentDirectory, "ProductCache.xml"); if (!File.Exists(fullPath)) return new Product[0]; using (var stream = File.Read(fullPath)) { var serializer = new XmlSerializer(); return (IEnumerable<Product>)serializer.Deserialize(stream); } }
چه زمانی باید استثناءها را مدیریت کنیم؟
زمانیکه بتوان متدهایی که خروجی مورد انتظار را بر میگردانند ایجاد کرد.
اجازه دهید دوباره از مثالهای فوق استفاده کنیم:
IEnumerable<Product> GetProducts()
IEnumerable<Product> GetCachedProducts()
در واقع استثناها حالتهایی هستند که غیرقابل پیشبینی هستند. این حالتها میتوانند یک خطای منطقی از طرف برنامهنویس و یا چیزی خارج کنترل برنامهنویس باشند (مانند خطاهای سیستمعامل، شبکه، دیسک). یعنی در بیشتر مواقع این نوع خطاها را نمیتوان مدیریت کرد.
اگر میخواهید استثناءها را catch کرده و آنها را لاگ کنید در بالاترین لایه اینکار را انجام دهید.
چه استثناءهایی باید مدیریت شوند و کدامها خیر؟
مدیریت صحیح استثناءها میتواند خیلی مفید باشد. همانطور که عنوان شد یک استثناء زمانی رخ میدهد که یک حالت استثناء در برنامه اتفاق بیفتد. این مورد را بخاطر داشته باشید، زیرا به شما یادآوری میکند که در همه جا نیازی به استفاده از try/catch نیست. در اینجا ذکر این نکته خیلی مهم است:
تنها استثناءهایی را catch کنید که بتوانید برای آن راهحلی ارائه دهید.
به عنوان مثال اگر در لایهی دسترسی به داده، خطایی رخ دهد و استثناءی SqlException صادر شود، میتوانیم آن را catch کرده و درون یک استثناء عمومیتر قرار دهیم:
public class UserRepository : IUserRepository { public IList<User> Search(string value) { try { return CreateConnectionAndACommandAndReturnAList("WHERE value=@value", Parameter.New("value", value)); } catch (SqlException err) { var msg = String.Format("Ohh no! Failed to search after users with '{0}' as search string", value); throw new DataSourceException(msg, err); } } }
اگر مطمئن نیستید که تمام استثناءها توسط شما مدیریت شدهاند، میتوانید در حالتهای زیر، دیگر استثناءها را مدیریت کنید:
ASP.NET: میتوانید Aplication_Error را پیادهسازی کنید. در اینجا فرصت خواهید داشت تا تمامی خطاهای مدیریت نشده را هندل کنید.
WinForms: استفاده از رویدادهای Application.ThreadException و AppDomain.CurrentDomain.UnhandledException
WCF: پیادهسازی اینترفیس IErrorHandler
ASMX: ایجاد یک Soap Extension سفارشی
ASP.NET WebAPI
چه زمانهایی باید یک استثناء صادر شود؟
صادر کردن یک استثناء به تنهایی کار سادهایی است. تنها کافی است throw را همراه شیء exception (exception object) فراخوانی کنیم. اما سوال اینجاست که چه زمانی باید یک استثناء را صادر کنیم؟ چه دادههایی را باید به استثناء اضافه کنیم؟ در ادامه به این سوالات خواهیم پرداخت.
همانطور که عنوان گردید استثناءها زمانی باید صادر شوند که یک استثناء اتفاق بیفتد.
اعتبارسنجی آرگومانها
سادهترین مثال، آرگومانهای مورد انتظار یک متد است:
public void PrintName(string name) { Console.WriteLine(name); }
مشکل فوق را میتوانیم با صدور استثنای ArgumentNullException رفع کنیم:
public void PrintName(string name) { if (name == null) throw new ArgumentNullException("name"); Console.WriteLine(name); }
public void PrintName(string name) { if (name == null) throw new ArgumentNullException("name"); if (name.Length < 5 || name.Length > 10) throw new ArgumentOutOfRangeException("name", name, "Name must be between 5 or 10 characters long"); if (name.Any(x => !char.IsAlphaNumeric(x)) throw new ArgumentOutOfRangeException("name", name, "May only contain alpha numerics"); Console.WriteLine(name); }
حالت دیگر صدور استثناء، زمانی است که متدی خروجی مورد انتظارمان را نتواند تحویل دهد. یک مثال بحثبرانگیز متدی با امضای زیر است:
public User GetUser(int id) { }
با استفاده از بررسی null کدهایی شبیه به این را در همه جا خواهیم داشت:
var user = datasource.GetUser(userId); if (user == null) throw new InvalidOperationException("Failed to find user: " + userId); // actual logic here
public User GetUser(int id) { if (id <= 0) throw new ArgumentOutOfRangeException("id", id, "Valid ids are from 1 and above. Do you have a parsing error somewhere?"); var user = db.Execute<User>("WHERE Id = ?", id); if (user == null) throw new EntityNotFoundException("Failed to find user with id " + id); return user; }
خطاهای متداول حین کار با استثناءها
- صدور مجدد استثناء و از بین بردن stacktrace
کد زیر را در نظر بگیرید:
try { FutileAttemptToResist(); } catch (BorgException err) { _myDearLog.Error("I'm in da cube! Ohh no!", err); throw err; }
- اضافه نکردن اطلاعات استثناء اصلی به استثناء جدید
یکی دیگر از خطاهای رایج اضافه نکردن استثناء اصلی حین صدور استثناء جدید است:
try { GreaseTinMan(); } catch (InvalidOperationException err) { throw new TooScaredLion("The Lion was not in the m00d", err); //<---- استثناء اصلی بهتر است به استثناء جدید پاس داده شود }
- ارائه ندادن context information
در هنگام صدور یک استثناء بهتر است اطلاعات دقیقی را به آن ارسال کنیم تا دیباگ کردن آن به راحتی انجام شود. به عنوان مثال کد زیر را در نظر داشته باشید:
try { socket.Connect("somethingawful.com", 80); } catch (SocketException err) { throw new InvalidOperationException("Socket failed", err); }
void IncreaseStatusForUser(int userId, int newStatus) { try { var user = _repository.Get(userId); if (user == null) throw new UpdateException(string.Format("Failed to find user #{0} when trying to increase status to {1}", userId, newStatus)); user.Status = newStatus; _repository.Save(user); } catch (DataSourceException err) { var errMsg = string.Format("Failed to find modify user #{0} when trying to increase status to {1}", userId, newStatus); throw new UpdateException(errMsg, err); }
نحوهی طراحی استثناءها
برای ایجاد یک استثناء سفارشی میتوانید از کلاس Exception ارثبری کنید و چهار سازندهی آن را اضافه کنید:
public NewException() public NewException(string description ) public NewException(string description, Exception inner) protected or private NewException(SerializationInfo info, StreamingContext context)
سازندهی دوم برای تعیین description بوده و همانطور که عنوان شد ارائه دادن context information از اهمیت بالایی برخوردار است. به عنوان مثال فرض کنید استثناء KeyNotFoundException که توسط کلاس Dictionary صادر شده است را دریافت کردهاید. این استثناء زمانی صادر خواهد شد که بخواهید به عنصری که درون دیکشنری پیدا نشده است دسترسی داشته باشید. در این حالت پیام زیر را دریافت خواهید کرد:
“The given key was not present in the dictionary.”
“The key ‘abrakadabra’ was not present in the dictionary.”
سازندهی سوم شبیه به سازندهی قبلی عمل میکند با این تفاوت که توسط پارامتر دوم میتوانیم یک استثناء دیگر را catch کرده یک استثناء جدید صادر کنیم.
سازندهی سوم زمانی مورد استفاده قرار میگیرد که بخواهید از Serialization پشتیبانی کنید (به عنوان مثال ذخیرهی استثناءها درون فایل و...)
خوب، برای یک استثناء سفارشی حداقل باید کدهای زیر را داشته باشیم:
public class SampleException : Exception { public SampleException(string description) : base(description) { if (description == null) throw new ArgumentNullException("description"); } public SampleException(string description, Exception inner) : base(description, inner) { if (description == null) throw new ArgumentNullException("description"); if (inner == null) throw new ArgumentNullException("inner"); } public SampleException(SerializationInfo info, StreamingContext context) : base(info, context) { } }
اجباری کردن ارائهی Context information:
برای اجباری کردن context information کافی است یک فیلد اجباری درون سازنده تعریف کنیم. برای مثال اگر بخواهیم کاربر HTTP status code را برای استثناء ارائه دهد باید سازندهها را اینگونه تعریف کنیم:
public class HttpException : Exception { System.Net.HttpStatusCode _statusCode; public HttpException(System.Net.HttpStatusCode statusCode, string description) : base(description) { if (description == null) throw new ArgumentNullException("description"); _statusCode = statusCode; } public HttpException(System.Net.HttpStatusCode statusCode, string description, Exception inner) : base(description, inner) { if (description == null) throw new ArgumentNullException("description"); if (inner == null) throw new ArgumentNullException("inner"); _statusCode = statusCode; } public HttpException(SerializationInfo info, StreamingContext context) : base(info, context) { } public System.Net.HttpStatusCode StatusCode { get; private set; } }
public override string Message { get { return base.Message + "\r\nStatus code: " + StatusCode; } }
public class HttpException : Exception { // [...] public HttpException(SerializationInfo info, StreamingContext context) : base(info, context) { // this is new StatusCode = (HttpStatusCode) info.GetInt32("HttpStatusCode"); } public HttpStatusCode StatusCode { get; private set; } public override string Message { get { return base.Message + "\r\nStatus code: " + StatusCode; } } // this is new public override void GetObjectData(SerializationInfo info, StreamingContext context) { base.GetObjectData(info, context); info.AddValue("HttpStatusCode", (int) StatusCode); } }
در حین صدور استثناءها همیشه باید در نظر داشته باشیم که چه نوع context information را میتوان ارائه داد، این مورد در یافتن راهحل خیلی کمک خواهد کرد.
طراحی پیامهای مناسب
پیامهای exception مختص به توسعهدهندگان است نه کاربران نهایی.
نوشتن این نوع پیامها برای برنامهنویس کار خستهکنندهایی است. برای مثال دو مورد زیر را در نظر داشته باشید:
throw new Exception("Unknown FaileType"); throw new Exception("Unecpected workingDirectory");
توسعهدهندگانی که exception message را در اولویت قرار میدهند، معتقد هستند که از لحاظ تجربهی کاربری پیامها تا حد امکان باید فاقد اطلاعات فنی باشد. همچنین همانطور که پیشتر عنوان گردید این نوع پیامها همیشه باید در بالاترین سطح نمایش داده شوند نه در لایههای زیرین. همچنین پیامهایی مانند Unknown FaileType نه برای کاربر نهایی، بلکه برای برنامهنویس نیز ارزش چندانی ندارد زیرا فاقد اطلاعات کافی برای یافتن مشکل است.
در طراحی پیامها باید موارد زیر را در نظر داشته باشیم:
- امنیت:
یکی از مواردی که از اهمیت بالایی برخوردار است مسئله امنیت است از این جهت که پیامها باید فاقد مقادیر runtime باشند. زیرا ممکن است اطلاعاتی را در خصوص نحوهی عملکرد سیستم آشکار سازند.
- زبان:
همانطور که عنوان گردید پیامهای استثناء برای کاربران نهایی نیستند، زیرا کاربران نهایی ممکن است اشخاص فنی نباشند، یا ممکن است زبان آنها انگلیسی نباشد. اگر مخاطبین شما آلمانی باشند چطور؟ آیا تمامی پیامها را با زبان آلمانی خواهید نوشت؟ اگر هم اینکار را انجام دهید تکلیف استثناءهایی که توسط Base Class Library و دیگر کتابخانههای thirt-party صادر میشوند چیست؟ اینها انگلیسی هستند.
در تمامی حالتهایی که عنوان شد فرض بر این است که شما در حال نوشتن این نوع پیامها برای یک سیستم خاص هستید. اما اگر هدف نوشتن یک کتابخانه باشد چطور؟ در این حالت نمیدانید که کتابخانهی شما در کجا استفاده میشود.
اگر هدف نوشتن یک کتابخانه نباشد این نوع پیامهایی که برای کاربران نهایی باشند، وابستگیها را در سیستم افزایش خواهند داد، زیرا در این حالت پیامها به یک رابط کاربری خاص گره خواهند خورد.
خب اگر پیامها برای کاربران نهایی نیستند، پس برای کسانی مورد استفاده قرار خواهند گرفت؟ در واقع این نوع پیام میتواند به عنوان یک documentation برای سیستم شما باشند.
فرض کنید در حال استفاده از یک کتابخانه جدید هستید به نظر شما کدام یک از پیامهای زیر مناسب هستند:
"Unecpected workingDirectory"
"You tried to provide a working directory string that doesn't represent a working directory. It's not your fault, because it wasn't possible to design the FileStore class in such a way that this is a statically typed pre-condition, but please supply a valid path to an existing directory. "The invalid value was: "fllobdedy"."
همیشه برای نوشتن پیامهای مناسب سعی کنید از لحاظ نوشتاری متن شما مشکلی نداشته باشد، اطلاعات کافی را درون پیام اضافه کنید و تا حد امکان نحوهی رفع مشکل را توضیح دهید
اشتراکها