نظرات مطالب
JSLint.VS
- آیا نگارش VS.Net شما از افزونهها پشتیبانی میکند؟
- این پوشه در سیستم من در این مسیر قرار دارد:
C:\Documents and Settings\vahid\My Documents\Visual Studio 2008\Addins
- این پوشه در سیستم من در این مسیر قرار دارد:
C:\Documents and Settings\vahid\My Documents\Visual Studio 2008\Addins
در برنامههای ASP.NET Web Forms، هر درخواست (URL)، به یک فایل با پسوند aspx منطبق میشود. بطور مثال آدرس http://domain/studentsinfo.aspx بایستی با یک فایل فیزیکی به نام studentsinfo.aspx مطابقت داشته باشد. این فایل حاوی code و markup برای پاسخگویی به درخواست ارسالی و نمایش اطلاعات در مرورگر میباشد.
Asp.net با معرفی سیستم مسیریابی (Routing)، عملیات نگاشت آدرسها به فایلهای فیزیکی را حذف کرد. مسیریابی امکانی را فراهم میکند تا با طراحی الگوی URL، درخواستها را به مدیریت کنندهی درخواستها نگاشت کنیم. این مدیریت کنندهی URLها میتواند یک فایل و یا یک کلاس باشد. در برنامههای وب فرم این مدیریت کننده URL یک فایل فیزیکی است و در برنامههای MVC یک کلاس (کنترلر) و متد(اکشن) است. بطور مثال درخواست http://domain/students میتواند به آدرس http:domain/studentsinfo.aspx در یک برنامه وب فرم نگاشت شود و یا در یک برنامه MVC به کنترلر Student و اکشن Index .
Asp.net با معرفی سیستم مسیریابی (Routing)، عملیات نگاشت آدرسها به فایلهای فیزیکی را حذف کرد. مسیریابی امکانی را فراهم میکند تا با طراحی الگوی URL، درخواستها را به مدیریت کنندهی درخواستها نگاشت کنیم. این مدیریت کنندهی URLها میتواند یک فایل و یا یک کلاس باشد. در برنامههای وب فرم این مدیریت کننده URL یک فایل فیزیکی است و در برنامههای MVC یک کلاس (کنترلر) و متد(اکشن) است. بطور مثال درخواست http://domain/students میتواند به آدرس http:domain/studentsinfo.aspx در یک برنامه وب فرم نگاشت شود و یا در یک برنامه MVC به کنترلر Student و اکشن Index .
نکته : مسیریابی مربوط به فریم ورک MVC نمیباشد ، از مسیر یابی هم در WebForm application و هم در MVC Application استفاده میشود.
مسیر (Route) :
Route، الگوی URL و اطلاعات مدیریت کنندهی URL را تعریف میکند. تمامی Routeهای تعریف شدهی در یک برنامه، در جدولی به نام RouteTable ذخیره میشوند. اطلاعات این جدول توسط موتور مسیریابی (Routing Engine) برای پیدا کردن مدیریت کنندههای URLها مورد استفاده قرار میگیرد.
تصویر زیر فرآیند مسیریابی را نشان میدهد:
پیکربندی مسیر(Route Configuration) :
در برنامههای MVC میبایست حداقل یک Route، پیکربندی و تعریف شده باشد. شما میتوانید یک Route دلخواه را در کلاس RouteConfig که در پوشه App_Start پروژه قرار گرفته است، تعریف کنید. شکل زیر طریقه پیکربندی یک Route را در کلاس RouteConfig، نشان میدهد:
همانطور که در شکل بالا مشاهده میکنید برای پیکره بندی Route از متد الحاقی MapRoute از مجموعه RouteCollection استفاده شده است.
ساختار Route تعریف شده :
• نام: "Default"
• الگوی درخواست: {Id}/{Action}/{Controller}.
• پارامترهای پیش فرض: این بخش در مواقعی که کنترلر، اکشن و یا مقدار Id، در آدرس ارسالی وجود نداشته باشد مورد استفاده قرار میگیرد.
نکته : RouteCollection خصوصیتی از کلاس RouteTable میباشد.
الگوی درخواست (URL Pattern) :
الگوی URL باید بعد از نام دامنه قرار بگیرد. بطور مثال الگوی "{controller}/{action}/{id}" شبیه چنین درخواستی میباشد:
localhost:123/{controller}/{action}/{id}
هر چیزی بعد از نام دامنه ("/localhost:1234") بعنوان کنترلر در نظر گرفته خواهد شد. به همین ترتیب هر چیزی بعد از نام کنترلر، بعنوان اکشن و پس از آن مقدار پارامتر id .
اگر درخواست ارسالی بعد از نام دامنه، فاقد اطلاعات کنترلر و اکشن باشد، کنترلر و اکشن پیش فرض تعریف شده، جایگزین خواهند شد. بطور مثال درخواست localhost:1234 توسط کنترلر پیش فرض Home و متد Index مدیریت خواهد شد (با توجه به الگوی تعریف شده بالا):
جدول زیر وضعیت بررسی URLها بر اساس Route تعریف شدهی فوق را نشان میدهد:
جدول زیر وضعیت بررسی URLها بر اساس Route تعریف شدهی فوق را نشان میدهد:
Id | Action | Controller | URL |
null | Index | HomeController | http://localhost/home |
123 | Index | HomeController | http://localhost/home/index/123 |
null | About | HomeController | http://localhost/home/about |
null | contact | HomeController | http://localhost/home/contact |
null | Index | StudentController | http://localhost/student |
123 | Edit | StudentController | http://localhost/student/edit/123 |
مسیرهای چندگانه (Multiple Route) :
شما براحتی و از طریق MapRoute میتوانید چندین Route سفارشی را تعریف کنید. برای تعریف یک Route، حداقل دو پارامتر Name و الگوی URL الزامی است. بخش پارامترهای پیش فرض در تعریف یک Route، اختیاری است.
مثال: قصد داریم یک Route سفارشی را تعریف کنیم تا هر درخواستی، با الگوی domainName/students از طریق آن مدیریت شود:routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); routes.MapRoute( name: "Student", url: "students/{id}", defaults: new { controller = "Student", action = "Index" } ); routes.MapRoute( name: "Default", url: "{controller}/{action}/{id}", defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional } );
با تعریف Route فوق، کلیه درخواستهایی که با domainName/students شروع میشوند، باید بوسیلهی StudentController مدیریت شوند. همانطور که مشاهده میکنید، در الگوی URL فوق هیچ {action} ای را معرفی نکردهایم. به این خاطر که قصد داریم هر درخواستی که با student شروع میشود از متد Index نوشته شده در کنترلر student استفاده کند.
فریم ورک MVC، کلیه Route های تعریف شده را به ترتیب مورد بررسی قرار خواهد داد. بدین معنی که با آمدن هر درخواست، اولین Route در جدول Routeها را بررسی کرده و اگر درخواست با Students/ شروع نشده بود، به سراغ مسیر تعریف شده بعدی میرود.
فریم ورک MVC، کلیه Route های تعریف شده را به ترتیب مورد بررسی قرار خواهد داد. بدین معنی که با آمدن هر درخواست، اولین Route در جدول Routeها را بررسی کرده و اگر درخواست با Students/ شروع نشده بود، به سراغ مسیر تعریف شده بعدی میرود.
جدول زیر چگونگی نگاشت URLهای مختلف را از طریق Route تعریف شده Student، نشان میدهد:
Id | Action | Controller | URL |
123 | Index | StudentController | http://localhost/students/123 |
123 | Index | StudentController | http://localhost/students/index/123 |
123 | Index | StudentController | http://localhost/students/index/123 |
محدود کردن مسیرها (Route Constraints) :
به Route تعریف شده زیر دقت کنید :
routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); routes.MapRoute( name: "Product", url: "{Product}/{productid}", defaults: new { controller = "Product", action = "Details" } );
public class ProductController : Controller { // GET: Product public ActionResult Details(int prodcutId) { return View(); } }
/Product/24 /Product/4
/Product/apple /Product/kish
بررسی علت بروز خطا:
انتظار اکشن Details، دریافت یک پارامتر از نوع عددی میباشد. ارسال هر مقداری به غیر از عدد، سبب بروز خطا خواهد شد:
برای حل مشکل فوق باید بر روی الگوی تعریف شده، محدودیت ایجاد کنیم.
نحوه ایجاد محدودیت بر روی پارامتر id :
routes.MapRoute( name: "Product", url: "{Product}/{productid}", defaults: new { controller = "Product", action = "Details" }, constraints: new { productid = @"\d+" } );
در صورتیکه مقداری غیر عددی، به عنوان پارامتر id ارسال شود، درخواست توسط Route فوق پردازش نخواهد شد و سیستم مسیریابی مجددا به دنبال یک Route که شرایط درخواست را تامین کند، میگردد. در صورت پیدا نشدن یک Route برای پاسخدهی به این درخواست، خطای "The resource could not be found" نمایش داده خواهد شد.
ثبت مسیر (Register Route) :
بعد از پیکربندی کلیه Routeها در کلاس RouteConfig، باید Routeها از طریق رویداد Application_Start موجود در فایل Global.asx ثبت گردند.
بعد از این مرحله کلیه Routeهای تعریف شده به RouteTable اضافه خواهند شد.
public class MvcApplication : System.Web.HttpApplication { protected void Application_Start() { RouteConfig.RegisterRoutes(RouteTable.Routes); } }
قبل از ادامه، بهتر است یک مقدمه کوتاه درباره انواع منابع موجود در ASP.NET ارائه شود تا درک مطالب بعدی آسانتر شود.
نکات اولیه
- یک فایل Resource درواقع یک فایل XML شامل رشته هایی برای ذخیره سازی مقادیر (منابع) موردنیاز است. مثلا رشته هایی برای ترجمه به زبانهای دیگر، یا مسیرهایی برای یافتن تصاویر یا فایلها و ... . پسوند این فایلها resx. است (مثل MyResource.resx).
- این فایلها برای ذخیره منابع از جفت دادههای کلید-مقدار (key-value pair) استفاده میکنند. هر کلید معرف یک ورودی مجزاست. نام این کلیدها حساس به حروف بزرگ و کوچک نیست (Not Case-Sensitive).
- برای هر زبان (مثل fa برای فارسی) یا کالچر موردنظر (مثل fa-IR برای فارسی ایرانی) میتوان یک فایل Resource جداگانه تولید کرد. عناون زبان یا کالچر باید جزئی از نام فایل Resource مربوطه باشد (مثل MyResource.fa.resx یا MyResource.fa-IR.resx). هر منبع باید دارای یک فایل اصلی (پیشفرض) Resource باشد. این فایل، فایلی است که برای حالت پیشفرض برنامه (بدون کالچر) تهیه شده است و در عنوان آن از نام زیان یا کالچری استفاده نشده است (مثل MyResource.resx). برای اطلاعات بیشتر به قسمت اول این سری مراجعه کنید.
- تمامی فایلهای Resource باید دارای کلیدهای یکسان با فایل اصلی Resource باشند. البته لزومی ندارد که این فایلها حاوی تمامی کلیدهای منبع پیشفرض باشند. درصورت عدم وجود کلیدی در یک فایل Resource عملیات پیش فرض موجود در دات نت با استفاده از فرایند مشهور به fallback مقدار کلید موردنظر را از نزدیکترین و مناسبترین فایل موجود انتخاب میکند (درباره این رفتار در قسمت اول توضیحاتی ارائه شده است).
- در زمان اجرا موتور پیش فرض مدیریت منابع دات نت با توجه به کالچر UI در ثرد جاری اقدام به انتخاب مقدار مناسب برای کلیدهای درخواستی (به همراه فرایند fallback) میکند. فرایند نسبتا پیچیده fallback در اینجا شرح داده شده است.
منابع Global و Local
در ASP.NET دو نوع کلی Resource وجود دارد که هر کدام برای موقعیتهای خاصی مورد استفاده قرار میگیرند:
- Resourceهای Global: منابعی کلی هستند که در تمام برنامه در دسترسند. این فایلها در مسیر رزرو شده APP_GlobalResources در ریشه سایت قرار میگیرند. محتوای هر فایل resx. موجود در این فولدر دارای دسترسی کلی خواهد بود.
- Resourceهای Local: این منابع همانطور که از نامشان پیداست محلی! هستند و درواقع مخصوص همان مسیری هستند که در آن تعبیه شده اند! در استفاده از منابع محلی به ازای هر صفحه وب (aspx. یا master.) یا هر یوزرکنترل (ascx.) یک فایل resx. تولید میشود که تنها در همان صفحه یا یوزرکنترل در دسترس است. این فایلها درون فولدر رزرو شده APP_LocalResources در مسیرهای موردنظر قرار میگیرند. درواقع در هر مسیری که نیاز به این نوع از منابع باشد، باید فولدری با عنوان App_LocalResources ایجاد شود و فایلهای resx. مرتبط با صفحهها یا یوزرکنترلهای آن مسیر در این فولدر مخصوص قرار گیرد.
در تصویر زیر چگونگی افزودن این فولدرهای مخصوص به پروژه وب اپلیکیشن نشان داده شده است:
نکته: دقت کنید که تنها یک فولدر App_GlobalResources به هر پروزه میتوان افزود. همچنین در ریشه هر مسیر موجود در پروژه تنها میتوان یک فولدر Appp_LocalResources داشت. پس از افزودن هر یک از این فولدرهای مخصوص، منوی فوق به صورت زیر در خواهد آمد:
نکته: در زمان اجرا، عملیات استخراج دادههای موجود در این نوع منابع، به صورت خودکار توسط ASP.NET انجام میشود. این دادهها پس از استخراج در حافظه سرور کش خواهند شد.
برای روشنتر شدن مطالب اشاره شده در بالا به تصویر فرضی! زیر توجه کنید (اسمبلیهای تولید شده برای منابع کلی و محلی فرضی است):
در تصویر بالا محل قرارگیری انواع مختلف فایلهای Resource و نیز محل نهایی فرضی اسمبلیهای ستلایت تولید شده، برای حداقل یک زبان غیر از زبان پیش فرض برنامه، نشان داده شده است.
نکته: نحوه برخورد با این نوع از فایلهای Resource در پروژههای Web Site و Web Application کمی باهم فرق میکند. موارد اشاره شده در این مطلب بیشتر درباره Web Applicationها صدق میکند.
برای آشنایی بیشتر بهتر است یک برنامه وب اپلیکیشن جدید ایجاد کرده و همانند تصویر زیر یکسری فایل Resource به فولدرهای اشاره شده در بالا اضافه کنید:
همانطور که مشاهده میکنید به صورت پیشفرض برای منابع کلی یک فایل cs. تولید میشود. اما اثری از این فایل برای منابع محلی نیست.
حال اگر پنجره پراپرتی فایل منبع کلی را باز نمایید با چیزی شبیه به تصویر زیر مواجه خواهید شد:
میبینید که خاصیت Build Action آن به Content مقداردهی شده است. این مقدار موجب میشود تا این فایل به همین صورت و در همین مسیر مستقیما در پابلیش نهایی برنامه ظاهر شود. در قسمت قبل به خاصیت Buil Action و مقادیر مختلف آن اشاره شده است.
همچنین میبینید که مقدار پراپرتی Custom Tool به GlobalResourceProxyGenerator تنظیم شده است. این ابزار مخصوص تولید کلاس مربوط به منابع کلی در ویژوال استودیو است. با استفاده از این ابزار فایل Resource1.Designer.cs که در تصویر قبلی نیز نشان داده شده، تولید میشود.
حالا پنجره پراپرتیهای منبع محلی را باز کنید:
میبینید که همانند منبع کلی خاصیت Build Action آن به Content تنظیم شده است. همچنین مقداری برای پراپرتی Custom Tool تنظیم نشده است. این مقدار پیش فرض را تغییر ندهید، چون با تنظیم مقداری برای آن چیز مفیدی عایدتان نمیشود!
نکته: برای به روز رسانی مقادیر کلیدهای منابعی که با توجه به توضیحات بالا به همراه برنامه به صورت فایلهای resx. پابلیش میشوند، کافی است تا محتوای فایلهای resx. مربوطه با استفاده از یک ابزار (همانند نمونه ای که در قسمت قبل شرح داده شد) تغییر داده شوند. بقیه عملیات توسط ASP.NET انجام خواهد شد. اما با تغییر محتوای این فایلهای resx. با توجه به رفتار FCN در ASP.NET (که در قسمت قبل نیز توضیح داده شد) سایت Restart خواهد شد. البته این روش تنها برای منابع کلی و محلی درون مسیرهای مخصوص اشاره شده کار خواهد کرد.
استفاده از منابع Local و Global
پس از تولید فایلهای Resource، میتوان از آنها در صفحات وب استفاده کرد. معمولا از این نوع منابع برای مقداردهی پراپرتی کنترلها در صفحات وب استفاده میشود. برای استفاده از کلیدهای منابع محلی میتوان از روشی همانند زیر بهره برد:
<asp:Label ID="lblLocal" runat="server" meta:resourcekey="lblLocalResources" ></asp:Label>
اما برای منابع کلی تنها میتوان از روش زیر استفاده کرد (یعنی برای منابع محلی نیز میتوان از این روش استفاده کرد):
<asp:Label ID="lblGlobal" runat="server" Text="<%$ Resources:CommonTerms, HelloText %>" ></asp:Label>
به این عبارات که با فوت پررنگ مشخص شده اند اصطلاحا «عبارات بومیسازی» (Localization Expression) میگویند. در ادامه این سری مطالب با نحوه تعریف نمونههای سفارشی آن آشنا خواهیم شد.
به نمونه اول که برای منابع محلی استفاده میشود نوع ضمنی (Implicit Localization Expression) میگویند. زیرا نیازی نیست تا محل کلید موردنظر صراحتا ذکر شود!
به نمونه دوم که برای منابع کلی استفاه میشود نوع صریح (Explicit Localization Expression) میگویند. زیرا برای یافتن کلید موردنظر باید آدرس دقیق آن ذکر شود!
بومی سازی ضمنی (Implicit Localization) با منابع محلی
عنوان کلید مربوطه در این نوع عبارات همانطور که در بالا نشان داده شده است، با استفاده از پراپرتی مخصوص meta:resoursekey مشخص میشود. در استفاده از منابع محلی تنها یک نام برای کل خواص کنترل مربوطه در صفحات وب کفایت میکند. زیرا عنوان کلیدهای این منبع باید از طرح زیر پیروی کند:ResourceKey.Property
ResourceKey.Property.SubProperty یا ResourceKey.Property-SubProperty
برای مثال در لیبل بالا که نام کلید Resource آن به lblLocalResources تنظیم شده است، اگر نام صفحه وب مربوطه page1.aspx باشد، برای تنظیم خواص آن در فایل page1.aspx.resx مربوطه باید از کلیدهایی با عناوینی مثل عنوانهای زیر استفاه کرد:
lblLocalResources.Text
lblLocalResources.BackColor
برای نمونه به تصاویر زیر دقت کنید:
بومی سازی صریح (Explicit Localization)
در استفاده از این نوع عبارات، پراپرتی مربوطه و نام فایل منبع صراحتا در تگ کنترل مربوطه آورده میشود. بنابراین برای هر خاصیتی که میخواهیم مقدار آن از منبعی خاص گرفته شود باید از عبارتی با طرح زیر استفاده کنیم:
<%$ Resources: Class, ResourceKey %>
در این عبارت، رشته Resources پیشوند (Prefix) نام دارد و مشخص کننده استفاده از نوع صریح عبارات بومی سازی است. Class نام کلاس مربوط به فایل منبع بوده و اختیاری است که تنها برای منابع کلی باید آورده شود. ResourceKey نیز کلید مربوطه را در فایل منبع مشخص میکند.
برای نمونه به تصاویر زیر دقت کنید:
نکته: استفاده همزمان از این دو نوع عبارت بومی سازی در یک کنترل مجاز نیست!
نکته: به دلیل تولید کلاسی مخصوص منابع کلی (با توجه به توضیحات ابتدای این مطلب راجع به پراپرتی Custom Tool)، امکان استفاده مستقیم از آن درون کد نیز وجود دارد. این کلاسها که به صورت خودکار تولید میشوند، به صورت مستقیم از کلاس ResourceManager برای یافتن کلیدهای منابع استفاده میکنند. اما روش مستقیمی برای استفاده از کلیدهای منابع محلی درون کد وجود ندارد.
نکته: درون کلاس System.Web.UI.TemplateControl و نیز کلاس HttpContext دو متد با نامهای GetGlobalResourceObject و GetLocalResourceObject وجود دارد که برای یافتن کلیدهای منابع به صورت غیرمستقیم استفاده میشوند. مقدار برگشتی این دو متد از نوع object است. این دو متد به صورت مستقیم از کلاس ResourceManager استفاده نمیکنند! همچنین ازآنجاکه کلاس Page از کلاس TemplateControl مشتق شده است، بنابراین این دو متد در صفحات وب در دسترس هستند.
دسترسی با برنامه نویسی
همانطور که در بالا اشاره شد امکان دستیابی به کلیدهای منابع محلی و کلی ازطریق دو متد GetGlobalResourceObject و GetLocalResourceObject نیز امکان پذیر است. این دو متد با فراخوانی ResourceProviderFactory جاری سعی در یافتن مقادیر کلیدهای درخواستی در منابع موجود میکنند. درباره این فرایند در مطالب بعدی به صورت مفصل بحث خواهد شد.
کلاس TemplateControl
این دو متد در کلاس TemplateControl از نوع Instance (غیر استاتیک) هستند. امضای (Signature) این دو متد در این کلاس به صورت زیر است:
متد GetLocalResourceObject:
protected object GetLocalResourceObject(string resourceKey) protected object GetLocalResourceObject(string resourceKey, Type objType, string propName)
txtTest.Text = GetLocalResourceObject("txtTest.Text") as string;
متد دوم برای استخراج کلیدهای منبع محلی با مشخص کردن نوع داده محتوا (معمولا برای دادههای غیر رشتهای) و پراپرتی موردنظر به کار میرود. در این متد پارامتر objType برای معرفی نوع داده متناظر با داده موجود در کلید resourceKey استفاده میشود. از پارامتر propName نیز همانطور که از نامش پیداست برای مشخص کردن پراپرتی موردنظر از این نوع داده معرفی شده استفاده میشود.
متد GetGlobalResourceObject:
protected object GetGlobalResourceObject(string className, string resourceKey) protected object GetGlobalResourceObject(string className, string resourceKey, Type objType, string propName)
TextBox1.Text = GetGlobalResourceObject("Resource1", "String1") as string;
کلاس HttpContext
در این کلاس دو متد موردبحث از نوع استاتیک و به صورت زیر تعریف شدهاند:
متد GetLocalResourceObject:
public static object GetLocalResourceObject(string virtualPath, string resourceKey) public static object GetLocalResourceObject(string virtualPath, string resourceKey, CultureInfo culture)
در این دو متد، پارامتر virtualPath مشخص کننده مسیر نسبی صفحه وب متناظر با فایل منبع محلی موردنظر است، مثل "Default.aspx/~". پارامتر resourceKey نیز کلید منبع را تعیین میکند و پارامتر culture نیز به کالچر موردنظر اشاره دارد. مثال:
txtTest.Text = HttpContext.GetLocalResourceObject("~/Default.aspx", "txtTest.Text") as string;
public static object GetGlobalResourceObject(string classKey, string resourceKey) public static object GetGlobalResourceObject(string classKey, string resourceKey, CultureInfo culture)
TextBox1.Text = HttpContext.GetGlobalResourceObject("Resource1", "String1") as string;
نکته: بدیهی است که در MVC تنها میتوان از متدهای کلاس HttpContext استفاده کرد.
روش دیگری که تنها برای منابع کلی در دسترس است، استفاده مستقیم از کلاسی است که به صورت خودکار توسط ابزارهای Visual Studio برای فایل منبع اصلی تولید میشود. نمونهای از این کلاس را که برای یک فایل Resource1.resx (که تنها یک ورودی با نام String1 دارد) در پوشه App_GlobalResources تولید شده است، در زیر مشاهده میکنید:
//------------------------------------------------------------------------------ // <auto-generated> // This code was generated by a tool. // Runtime Version:4.0.30319.17626 // // Changes to this file may cause incorrect behavior and will be lost if // the code is regenerated. // </auto-generated> //------------------------------------------------------------------------------ namespace Resources { using System; /// <summary> /// A strongly-typed resource class, for looking up localized strings, etc. /// </summary> // This class was auto-generated by the StronglyTypedResourceBuilder // class via a tool like ResGen or Visual Studio. // To add or remove a member, edit your .ResX file then rerun ResGen // with the /str option or rebuild the Visual Studio project. [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.VisualStudio.Web.Application.StronglyTypedResourceProxyBuilder", "10.0.0.0")] [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] [global::System.Runtime.CompilerServices.CompilerGeneratedAttribute()] internal class Resource1 { private static global::System.Resources.ResourceManager resourceMan; private static global::System.Globalization.CultureInfo resourceCulture; [global::System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("Microsoft.Performance", "CA1811:AvoidUncalledPrivateCode")] internal Resource1() { } /// <summary> /// Returns the cached ResourceManager instance used by this class. /// </summary> [global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Advanced)] internal static global::System.Resources.ResourceManager ResourceManager { get { if (object.ReferenceEquals(resourceMan, null)) { global::System.Resources.ResourceManager temp = new global::System.Resources.ResourceManager("Resources.Resource1", global::System.Reflection.Assembly.Load("App_GlobalResources")); resourceMan = temp; } return resourceMan; } } /// <summary> /// Overrides the current thread's CurrentUICulture property for all /// resource lookups using this strongly typed resource class. /// </summary> [global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Advanced)] internal static global::System.Globalization.CultureInfo Culture { get { return resourceCulture; } set { resourceCulture = value; } } /// <summary> /// Looks up a localized string similar to String1. /// </summary> internal static string String1 { get { return ResourceManager.GetString("String1", resourceCulture); } } } }
نکته: فضای نام پیشفرض برای منابع کلی در این کلاسها همیشه Resources است که برابر پیشوند (Prefix) عبارت بومی سازی صریح است.
نکته: در کلاس بالا نحوه نمونه سازی کلاس ResourceManager نشان داده شده است. همانطور که مشاهده میکنید تعیین کردن مشخصات فایل اصلی Resource مربوطه که در اسمبلی نهایی تولید و کش میشود، اجباری است! در مطلب بعدی با این کلاس بیشتر آشنا خواهیم شد.
نکته: همانطور که قبلا نیز اشاره شد، کار تولید اسمبلی مربوط به فایلهای منابع کلی و محلی و کش کردن آنها در اسمبلی در زمان اجرا کاملا بر عهده ASP.NET است. مثلا در نمونه کد بالا میبینید که کلاس ResourceManager برای استخراج نوع Resources.Resource1 از اسمبلی App_GlobalResources نمونهسازی شده است، با اینکه این اسمبلی و نوع مذبور در زمان کامپایل و پابلیش وجود ندارد!
برای استفاده از این کلاس میتوان به صورت زیر عمل کرد:
TextBox1.Text = Resources.Resource1.String1;
نکته: همانطور که قبلا هم اشاره شد، متاسفانه روش بالا (برخلاف دو متدی که در قسمت قبل توضیح داده شد) به صورت مستقیم از کلاس ResourceManager استفاده میکند، که برای بحث سفارشی سازی پرووایدرهای منابع مشکلزاست. در مطالب بعدی با معایب آن و نیز راه حلهای موجود آشنا خواهیم شد.
نکات نهایی
حال که با مفاهیم کلی بیشتری آشنا شدیم بهتر است کمی هم به نکات ریزتر بپردازیم:
نکته: فایل تولیدی توسط ویژوال استودیو در فرایند مدیریت منابع ASP.NET تاثیرگذار نیست! باز هم تاکید میکنم که کار استخراج کلیدهای Resource از درون فایلهای resx. کاملا به صورت جداگانه و خودکار و در زمان اجرا انجام میشود (درباره این فرایند در مطالب بعدی شرح مفصلی خواهد آمد). درواقع شما میتوانید خاصیت Custom Tool مربوط به منابع کلی را نیز همانند منابع محلی به رشتهای خالی مقداردهی کنید و ببینید که خللی در فرایند مربوطه رخ نخواهد داد!
نکته: تنها برای حالتی که بخواهید از روش آخری که در بالا اشاره شد برای دسترسی با برنامهنویسی به منابع کلی بهره ببرید (روش مستقیم)، به این کلاس تولیدی توسط ویژوال استودیو نیاز خواهید داشت. دقت کنید که در این کلاس نیز کار اصلی برعهده کلاس ResourceManager است. درواقع میتوان کلا از این فایل خودکارتولیدشده صرفنظر کرد و کار استخراج کلیدهای منابع را به صورت مستقیم به نمونهای از کلاس ResourceManager سپرد. این روش نیز در قسمتهای بعدی شرح داده خواهد شد.
نکته: اگر فایلهای Resource درون اسمبلیهای جداگانهای باشند (مثلا در یک پروژه جداگانه، همانطور که در قسمت اول این سری مطالب پیشنهاد شده است)، موتور پیش فرض منابع در ASP.NET بدرد نخواهد خورد! بنابراین یا باید از نمونههای اختصاصی کلاس ResourceManager استفاده کرد (کاری که کلاسهای خودکار تولیدشده توسط ابزارهای ویژوال استودیو انجام میدهند)، یا باید از پرووایدرهای سفارشی استفاده کرد که در مطالب بعدی نحوه تولید آنها شرح داده خواهد شد.
همانطور که در ابتدای این مطلب اشاره شد، این مقدمه در اینجا صرفا برای آشنایی بیشتر با این دونوع Resource آورده شده تا ادامه مطلب روشنتر باشد، زیرا با توجه به مطالب ارائه شده در قسمت اول این سری، در پروژههای MVC استفاده از یک پروژه جداگانه برای نگهداری این منابع راه حل مناسبتری است.
در مطلب بعدی به شرح نحوه تولید پرووایدرهای سفارشی میپردازم.
امکان کنترل کامل و سفارشی سازی ظاهر نهایی Swagger-UI وجود دارد که جزئیات آنرا در این قسمت بررسی خواهیم کرد.
بهبود ظاهر کامنتها با بکارگیری Markdown
Markdown زبان سبکی است برای تعیین شیوهنامهی نمایش متون ساده. اگر پیشتر با سیستم ارسال نظرات Github و یا Stackoverflow کار کرده باشید، قطعا با آن آشنایی دارید. توضیحات کامل و جزئیات آنرا میتوانید در آدرس markdownguide.org مطالعه کنید. خوشبختانه امکان استفادهی از Markdown در OpenAPI spec نیز وجود دارد که سبب بهبود ظاهر مستندات نهایی حاصل از آن خواهد شد.
در قسمت سوم، سعی کردیم مثالی را توسط remarks، به قسمت Patch اضافه کنیم که ظاهر آن، آنچنان مطلوب به نظر نمیرسد و بهتر است آنرا به صورت یک قطعه کد نمایش داد:
برای بهبود این ظاهر میتوان از Markdown استفاده کرد. بنابراین ابتدا تمام backslashهای اضافه شده را که جهت نمایش خطوط جدید اضافه شده بودند، حذف میکنیم. در Markdown خطوط جدید با درج حداقل 2 فاصله (space) و یک سطر جدید مشخص میشوند. همچنین استفادهی از ** سبب ضخیم شدن نمایش عبارتها میشود. برای اینکه قطعه کد نوشته شده را در Markdown به صورت کدی با پس زمینهای مشخص نمایش دهیم، پیش از شروع هر سطر آن نیاز است یک tab و یا 4 فاصله (space) درج شوند:
پس از این تغییرات خواهیم داشت:
در نگارش فعلی، استفادهی از Markdown برای توضیحات remarks، پارامترها و response codes پشتیبانی میشود؛ اما نه برای قسمت summary که برای نگارش بعدی درنظر گرفته شدهاست. همچنین از قابلیتهای پیشترفتهی Markdown هم استفاده نکنید (در کل نیاز به مقداری سعی و خطا دارد تا مشخص شود چه قابلیتهایی را پشتیبانی میکند).
سفارشی سازی مقدماتی UI به کمک تنظیمات API آن
جائیکه تنظیمات میانافزار Swashbuckle.AspNetCore در کلاس Starup تعریف میشوند، میتوان تغییراتی را نیز در UI آن اعمال کرد:
با این خروجی که به علت تنظیم DocExpansion آن به None، اینبار لیست قابلیتها را به صورت باز شده نمایش نمیدهد:
همچنین چون DefaultModelRendering به Model تنظیم شدهاست، اینبار بجای مثال، مشخصات مدل را به صورت پیشفرض نمایش میدهد:
کار DisplayOperationId نمایش Id هر Operation است؛ مانند get_api_authors. در اینجا Operation همان مداخل API ما هستند و به عنوان هر قسمت، Tag گفته میشود؛ مانند Authors و یا Books:
با فعالسازی EnableDeepLinking، آدرسهایی مانند tagName/# و یا tagName/OperationId/# قابلیت مرور و بازشدن خودکار را پیدا میکنند (tagName همان نام کنترلر است و OperationId همان اکشن متدی که عمومی شدهاست). برای مثال اگر آدرس https://localhost:5001/index.html#/Books/get_api_authors__authorId__books را در یک برگهی جدید مرورگر باز کنیم، بلافاصله گروه Books، باز شده و سپس به اکشن متد یا مدخلی که Id آن ذکر شدهاست، هدایت میشویم:
اعمال تغییرات پیشرفته در UI
Swagger-UI در اصل از یک سری فایل html، css، js و فونت تشکیل شدهاست که آنها را میتوانید در آدرس src/Swashbuckle.AspNetCore.SwaggerUI مشاهده کنید. برای مثال فایل index.html آنرا در اینجا میتوانید مشاهده کنید. اصل آن در div ای با id مساوی swagger-ui رخ میدهد و در این قسمت است که رابط کاربری آن به صورت پویا تولید شده و رندر خواهد شد. بررسی فایلهای js و css آن در این مخزن کد مشکل است؛ چون نگارش فشرده شدهی آن هستند. به همین جهت میتوان به مخزن کد اصلی Swagger-UI که نگارش جایگذاری شدهی آن (embedded) توسط Swashbuckle.AspNetCore ارائه میشود، رجوع کرد. برای مثال در پوشهی src/styles آن، اصل فایلهای css آن برای سفارشی سازی وجود دارند.
پس از اعمال تغییرات خود، میتوانید css و یا js سفارشی خود را به نحو زیر به تنظیمات app.UseSwaggerUI سیستم معرفی کنید:
باید دقت داشت که این فایلها باید در پوشهی wwwroot قرار گرفته و قابل دسترسی باشند.
برای اعمال تغییرات اساسی و تزریق صفحهی index.html جدیدی، میتوان به صورت زیر عمل کرد:
نکتهی مهم: اینبار این فایل باید به صورت embedded ارائه شود. به همین جهت در مثال فوق، عبارت OpenAPISwaggerDoc.Web به فضای نام اصلی اسمبلی جاری اشاره میکند. سپس EmbeddedAssets، نام پوشهای است که فایل index.html سفارشی سازی شده، در آن قرار خواهد گرفت. اکنون برای اینکه این فایل را به صورت EmbeddedResource معرفی کنیم، نیاز است فایل csproj را به نحو زیر ویرایش کرد:
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: OpenAPISwaggerDoc-07.zip
بهبود ظاهر کامنتها با بکارگیری Markdown
Markdown زبان سبکی است برای تعیین شیوهنامهی نمایش متون ساده. اگر پیشتر با سیستم ارسال نظرات Github و یا Stackoverflow کار کرده باشید، قطعا با آن آشنایی دارید. توضیحات کامل و جزئیات آنرا میتوانید در آدرس markdownguide.org مطالعه کنید. خوشبختانه امکان استفادهی از Markdown در OpenAPI spec نیز وجود دارد که سبب بهبود ظاهر مستندات نهایی حاصل از آن خواهد شد.
در قسمت سوم، سعی کردیم مثالی را توسط remarks، به قسمت Patch اضافه کنیم که ظاهر آن، آنچنان مطلوب به نظر نمیرسد و بهتر است آنرا به صورت یک قطعه کد نمایش داد:
برای بهبود این ظاهر میتوان از Markdown استفاده کرد. بنابراین ابتدا تمام backslashهای اضافه شده را که جهت نمایش خطوط جدید اضافه شده بودند، حذف میکنیم. در Markdown خطوط جدید با درج حداقل 2 فاصله (space) و یک سطر جدید مشخص میشوند. همچنین استفادهی از ** سبب ضخیم شدن نمایش عبارتها میشود. برای اینکه قطعه کد نوشته شده را در Markdown به صورت کدی با پس زمینهای مشخص نمایش دهیم، پیش از شروع هر سطر آن نیاز است یک tab و یا 4 فاصله (space) درج شوند:
/// <remarks> /// Sample request (this request updates the author's **first name**) /// /// PATCH /authors/id /// [ /// { /// "op": "replace", /// "path": "/firstname", /// "value": "new first name" /// } /// ] /// </remarks>
که نسبت به حالت قبلی بسیار بهتر به نظر میرسد.
در نگارش فعلی، استفادهی از Markdown برای توضیحات remarks، پارامترها و response codes پشتیبانی میشود؛ اما نه برای قسمت summary که برای نگارش بعدی درنظر گرفته شدهاست. همچنین از قابلیتهای پیشترفتهی Markdown هم استفاده نکنید (در کل نیاز به مقداری سعی و خطا دارد تا مشخص شود چه قابلیتهایی را پشتیبانی میکند).
سفارشی سازی مقدماتی UI به کمک تنظیمات API آن
جائیکه تنظیمات میانافزار Swashbuckle.AspNetCore در کلاس Starup تعریف میشوند، میتوان تغییراتی را نیز در UI آن اعمال کرد:
namespace OpenAPISwaggerDoc.Web { public class Startup { public void Configure(IApplicationBuilder app, IHostingEnvironment env) { // ... app.UseSwaggerUI(setupAction => { setupAction.SwaggerEndpoint( url: "/swagger/LibraryOpenAPISpecification/swagger.json", name: "Library API"); setupAction.RoutePrefix = ""; setupAction.DefaultModelExpandDepth(2); setupAction.DefaultModelRendering(Swashbuckle.AspNetCore.SwaggerUI.ModelRendering.Model); setupAction.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None); setupAction.EnableDeepLinking(); setupAction.DisplayOperationId(); }); // ... } } }
همچنین چون DefaultModelRendering به Model تنظیم شدهاست، اینبار بجای مثال، مشخصات مدل را به صورت پیشفرض نمایش میدهد:
کار DisplayOperationId نمایش Id هر Operation است؛ مانند get_api_authors. در اینجا Operation همان مداخل API ما هستند و به عنوان هر قسمت، Tag گفته میشود؛ مانند Authors و یا Books:
با فعالسازی EnableDeepLinking، آدرسهایی مانند tagName/# و یا tagName/OperationId/# قابلیت مرور و بازشدن خودکار را پیدا میکنند (tagName همان نام کنترلر است و OperationId همان اکشن متدی که عمومی شدهاست). برای مثال اگر آدرس https://localhost:5001/index.html#/Books/get_api_authors__authorId__books را در یک برگهی جدید مرورگر باز کنیم، بلافاصله گروه Books، باز شده و سپس به اکشن متد یا مدخلی که Id آن ذکر شدهاست، هدایت میشویم:
اعمال تغییرات پیشرفته در UI
Swagger-UI در اصل از یک سری فایل html، css، js و فونت تشکیل شدهاست که آنها را میتوانید در آدرس src/Swashbuckle.AspNetCore.SwaggerUI مشاهده کنید. برای مثال فایل index.html آنرا در اینجا میتوانید مشاهده کنید. اصل آن در div ای با id مساوی swagger-ui رخ میدهد و در این قسمت است که رابط کاربری آن به صورت پویا تولید شده و رندر خواهد شد. بررسی فایلهای js و css آن در این مخزن کد مشکل است؛ چون نگارش فشرده شدهی آن هستند. به همین جهت میتوان به مخزن کد اصلی Swagger-UI که نگارش جایگذاری شدهی آن (embedded) توسط Swashbuckle.AspNetCore ارائه میشود، رجوع کرد. برای مثال در پوشهی src/styles آن، اصل فایلهای css آن برای سفارشی سازی وجود دارند.
پس از اعمال تغییرات خود، میتوانید css و یا js سفارشی خود را به نحو زیر به تنظیمات app.UseSwaggerUI سیستم معرفی کنید:
setupAction.InjectStylesheet("/Assets/custom-ui.css"); setupAction.InjectJavaScript("/Assets/custom-js.js");
برای اعمال تغییرات اساسی و تزریق صفحهی index.html جدیدی، میتوان به صورت زیر عمل کرد:
setupAction.IndexStream = () => GetType().Assembly.GetManifestResourceStream( "OpenAPISwaggerDoc.Web.EmbeddedAssets.index.html");
<Project Sdk="Microsoft.NET.Sdk.Web"> <ItemGroup> <None Remove="EmbeddedAssets\index.html" /> </ItemGroup> <ItemGroup> <EmbeddedResource Include="EmbeddedAssets\index.html" /> </ItemGroup> </Project>
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: OpenAPISwaggerDoc-07.zip
مطالب
Gulp #2
در قسمت قبلی بحث کردیم که گالپ چیست و چه کاربردی دارد و در نهایت آن را بر روی سیستم خود نصب کردیم. در این مقاله و مقالات بعد میخواهیم کار خود را با راه اندازی یک workflow برای بوت استرپ، روند شخصی سازی آن را بسیار آسان و لذت بخشتر کنیم. امیدوارم که برای ادامهی این بحث هیجان انگیز آماده باشید!
این دستور برایمان یک فایل package.json میسازد تا هم مشخصات پروژه را مثل نام، ورژن، نام توسعه دهنده، مخزن و ... مشخص کنیم و هم وابستگیهای آن را، تا توسعه دهندگان دیگر، هنگام استفاده از پروژه، با مشکل مواجه نشوند و فقط با اجرای دستور npm install تمام وابستگیهای پروژه را نصب کنند.
الان فایل package.json درست شده و چون ما در این پروژه میخواهیم از گالپ استفاده کنیم، یکی از وابستگیهای پروژهی ما گالپ خواهد بود. بدین معنی که اگر بخواهیم پروژه را توسعه دهیم و گالپ نصب نشده باشد، با مشکل مواجه میشویم.
تفاوتی آن با دستوری که در مقالهی قبلی اجرا کردیم، این است که این دستور فقط گالپ را در مسیر جاری در فولدر node_modules نصب میکند و save-dev -- آن را به وابستگیهای توسعهی پروژه در فایل package.json اضافه میکند.
و حالا آن را در ویراشگر مورد علاقهی خود باز کنید. من از ویرایشگر Atom استفاده میکنم. اما notepad هم کفایت میکند.
require به Node میگوید که به فولدر node_modules برای پکیج gulp نگاه کند. زمانیکه آن را پیدا کرد، آن را به متغیر gulp انتساب میدهیم تا از تابعهای گالپ بتوانیم استفاده کنیم. حال میخواهیم اولین تسک خود را بنویسیم:
گالپ دارای ۴ تابع task,src,dest,watch است که با آنها آشنا خواهیم شد. task یک کار را برای گالپ تعریف میکند و سه پارامتر دارد. اولی نام تسک، دومی (اختیاری) وابستگی این تسک (بدین معنا که اول باید این وظیفه اجرا شود، سپس تسک جاری) و در نهایت تابع درون تسکها را مینویسیم. برای مثال:
فایل را ذخیره کنید. میخواهیم به گالپ بگوییم که این وظیفه را انجام دهد. کافی است gulp hello را در خط فرمان وارد کنیم. نتیجه به صورت زیر خواهد بود:
البته که تسکهایی که برای گالپ مینویسیم، کاراتر از این است؛ برای مثال:
مخزن پروژه در گیت هاب : https://github.com/mmdsharifi/gulp-rtlBootstrap-fontawesome
ساخت پروژه گالپ
ابتدا یک پوشهی دلخواه به نام project را درست کنید.سپس خط فرمان خود را به این مسیر تغییر دهید و در نهایت دستور زیر را وارد کنید:
npm init
حتما مشاهده کردهاید که این دستور چند سوالی را از شما میپرسد. برای نمونه من آنها به این صورت پاسخ میدهم و در نهایت از من یک تایید میگیرد که yes را میزنم.
name: (Gulp-RTLbootstrap-fontawesome) version: (1.0.0) description: An Awesome workflow entry point: (index.js) index.html test command: test git repository: https://github.com/mmdsharifi/gulp-rtlBootstrap-fontawesome.git keywords: gulp,rtlbootstrap,persian bootstrap author: Mohammad Sharifi license: (ISC) MIT
نصب گالپ
در خط فرمان دستور زیر را وارد کنید تا گالپ در این پروژه نصب شود.
npm install gulp --save-dev
گام بعدی، ساخت فایلی است که گالپ به آن نیاز دارد تا با استفاده از آن، تسکها و کارهایی را که برایش نوشتهایم، از آن بخواند و اجرا کند.
ایجاد فایل gulpfile.js
این فایل را یا به صورت دستی ایجاد کنید یا با خط فرمان با دستور ذیل:
touch gulpfile.js
نوشتن اولین تسک گالپ
در ویراشگر خط زیر را مینویسیم:
var gulp = require('gulp');
gulp.task('task-name', function() { // Stuff here });
gulp.task('hello', function() { console.log('Hello Gulp !'); });
البته که تسکهایی که برای گالپ مینویسیم، کاراتر از این است؛ برای مثال:
gulp.task('task-name', function () { return gulp.src('source-files') // Get source files with gulp.src .pipe(aGulpPlugin()) // Sends it through a gulp plugin .pipe(gulp.dest('destination')) // Outputs the file in the destination folder })
با استفاده از متد src به گالپ میگوییم که مسیر مبداء فایلها، برای انجام تسک کجا است و dest هم بعد از انجام تسک، فایلهای خروجی را به مقصد مشخص میبرد. متد pipe یک تابع ند جی اس است که مطابق مستندات خودش متدی است که تمام جریانهای قابل خواندن را واکشی میکند و به مسیری [که به صورت آرگومان به عنوان مقصد] داده شده، هدایت میکند.
شاید در ابتدا نوشتن تسک برایتان کمی پیچیده باشد، اما بعد از ساخت اولین پروژه با گالپ، خواهید دانست که تسک نوشتن برای گالپ کاری بسیار آسان و شیرین است!مخزن پروژه در گیت هاب : https://github.com/mmdsharifi/gulp-rtlBootstrap-fontawesome
نام کامیت این قسمت: Init commit
نظرات اشتراکها
نسخه راستچین شده AdminLTE 2.2.1
با سلام.
واقعا ممنون بابت این اشتراک. فقط یک مورد رو من دیدم که گفتم بیان کنم.
در نسخه 40.0.3 فایرفاکس ، sidebar-menu بدین صورت هستش :
من فایل css شمارو به این صورت تغییر دادم :
مشکل برطرف شد :
موفق باشید
واقعا ممنون بابت این اشتراک. فقط یک مورد رو من دیدم که گفتم بیان کنم.
در نسخه 40.0.3 فایرفاکس ، sidebar-menu بدین صورت هستش :
من فایل css شمارو به این صورت تغییر دادم :
.sidebar-menu > li > a { padding: 12px 15px 12px 5px; display: block; height: 50px; } .sidebar-menu > li > a >i, .sidebar-menu > li > a >span:not([class*="label-primary"]){ float: right; line-height: 25px; }
مشکل برطرف شد :
البته در کروم مشکلی نداره. البته قطعا شما با فایل css تون آشنایی بهتری دارید و میتونید راه حلهای بهتری استفاده کنید
موفق باشید
اشتراکها