الف) فعال سازی ارائهی فایلهای استاتیک
ب) فعال سازی ASP.NET MVC
ج) آشنایی با تغییرات مسیریابی
و مابقی آن صرفا یک سری نکات تکمیلی هستند که در ادامه آنها را بررسی خواهیم کرد.
تعریف مسیریابی کلی کنترلر
در اینجا همانند مطلب «ارتقاء به ASP.NET Core 1.0 - قسمت 9 - بررسی تغییرات مسیریابی»، میتوان در صورت نیاز، مسیریابی کلی کنترلر را توسط ویژگی Route بازنویسی کرد و برای مثال درخواستهای آنرا محدود به درخواستهایی کرد که با api/ شروع شوند:
[Route("api/[controller]")] // http://localhost:7742/api/test public class TestController : Controller { private readonly ILogger<TestController> _logger; public TestController(ILogger<TestController> logger) { _logger = logger; }
در مورد سرویس ثبت وقایع نیز در مطلب «ارتقاء به ASP.NET Core 1.0 - قسمت 17 - بررسی فریم ورک Logging» بحث کردیم و از آن میتوان برای ثبت استثناءهای رخ داده استفاده کرد.
یک کنترلر ، اما با قابلیتهای متعدد
همانطور که ملاحظه میکنید، اینبار کلاس پایهی این کنترلر Test، همان Controller متداول ASP.NET MVC ذکر شدهاست و نه Api Controller سابق. تمام قابلیتهای موجود در ایندو توسط همان Controller ارائه میشوند.
هنوز پیش فرضهای سابق Web API برقرار هستند
در مثال ذیل که به نظر یک کنترلر ASP.NET MVC است،
- هنوز متد Get مربوط به Web API که به صورت پیش فرض به درخواستهای Get ختم شدهی به نام کنترلر پاسخ میدهد، برقرار است (متد IEnumerable<string> Get). برای مثال اگر شخصی در مرورگر، آدرس http://localhost:7742/api/test را درخواست دهد، متد Get اجرا میشود.
- در اینجا میتوان نوع خروجی متد را دقیقا از همان نوع اشیاء مدنظر، تعیین کرد؛ برای نمونه تعریف <IEnumerable<string در مثال زیر.
- مهم نیست که از return Json استفاده کنید و یا خروجی را مستقیما با فرمت <IEnumerable<string ارائه دهید.
- اگر نیاز به کنترل بیشتری بر روی HTTP Response Status بازگشتی داشتید، میتوانید از متدهایی مانند return Ok و یا return BadRequest در صورت بروز مشکلی استفاده نمائید. برای مثال در متد IActionResult GetEpisodes2، استثنای فرضی حاصل، ابتدا توسط سرویس ثبت وقایع ذخیره شده و در آخر یک BadRequest بازگشت داده میشود.
- تمام مسیریابیها را توسط ویژگی Route و یا نوعهای درخواستی مانند HttpGet، میتوان بازنویسی کرد؛ مانند مسیر /api/path1
- امکان محدود ساختن نوع پارامترهای دریافتی همانند متد Get(int page) ذیل، توسط ویژگیهای مسیریابی وجود دارد.
[Route("api/[controller]")] // http://localhost:7742/api/test public class TestController : Controller { private readonly ILogger<TestController> _logger; public TestController(ILogger<TestController> logger) { _logger = logger; } [HttpGet] public IEnumerable<string> Get() // http://localhost:7742/api/test { return new [] { "value1", "value2" }; } [HttpGet("{page:int}")] public IActionResult Get(int page) // http://localhost:7742/api/test/1 { return Json(new[] { "value3", "value4" }); } [HttpGet("/api/path1")] public IActionResult GetEpisodes1() // http://localhost:7742/api/path1 { return Json(new[] { "value5", "value6" }); } [HttpGet("/api/path2")] public IActionResult GetEpisodes2() // http://localhost:7742/api/path2 { try { // get data from the DB ... return Ok(new[] { "value7", "value8" }); } catch (Exception ex) { _logger.LogError("Failed to get data from the API", ex); return BadRequest(); } } }
[Route("api/[controller]")] public class ValuesController : Controller { // GET: api/values [HttpGet] public IEnumerable<string> Get() { return new string[] { "value1", "value2" }; } // GET api/values/5 [HttpGet("{id}")] public string Get(int id) { return "value"; } // POST api/values [HttpPost] public void Post([FromBody]string value) { } // PUT api/values/5 [HttpPut("{id}")] public void Put(int id, [FromBody]string value) { } // DELETE api/values/5 [HttpDelete("{id}")] public void Delete(int id) { } } }
یک نکته: اگر میخواهید خروجی Web API شما همواره JSON باشد، میتوانید ویژگی جدید Produces را به شکل ذیل به کلاس کنترلر اعمال کنید:
[Produces("application/json")] [Route("api/[controller]")] // http://localhost:7742/api/test public class TestController : Controller
تغییرات Model binding پیش فرض، برای پشتیبانی از ASP.NET MVC و ASP.NET Web API
فرض کنید مدل زیر را به برنامه اضافه کردهاید:
namespace Core1RtmEmptyTest.Models { public class Person { public string FirstName { get; set; } public string LastName { get; set; } public int Age { get; set; } } }
using Core1RtmEmptyTest.Models; using Microsoft.AspNetCore.Mvc; namespace Core1RtmEmptyTest.Controllers { public class PersonController : Controller { public IActionResult Index() { return View(); } [HttpPost] public IActionResult Index(Person person) { return Json(person); } } }
@section scripts { <script type="text/javascript"> $(function () { $.ajax({ type: 'POST', url: '/Person/Index', dataType: 'json', contentType: 'application/json; charset=utf-8', data: JSON.stringify({ FirstName: 'F1', LastName: 'L1', Age: 23 }), success: function (result) { console.log('Data received: '); console.log(result); } }); }); </script> }
همانطور که مشاهده میکنید، اگر در ابتدای این متد یک break-point قرار دهیم، اطلاعاتی را از سمت کاربر دریافت نکردهاست و مقادیر دریافتی نال هستند.
این مورد یکی از مهمترین تغییرات Model binding این نگارش از ASP.NET MVC با نگارشهای قبلی آن است. در اینجا اشیاء پیچیده از request body دریافت و bind نمیشوند و باید به نحو ذیل، محل دریافت و تفسیر آنها را دقیقا مشخص کرد:
public IActionResult Index([FromBody]Person person)
نکتهی مهم: حتی اگر FromBody را ذکر کنید ولی از JSON.stringify در سمت کاربر استفاده نکنید، باز هم نال دریافت خواهید کرد. بنابراین در این نگارش ذکر JSON.stringify نیز الزامی است.
حالتهای دیگر تغییرات Model Binding در ASP.NET Core
تا اینجا مشخص شد که اگر یک درخواست Ajax ایی را به سمت سرور یک برنامهی ASP.NET Core ارسال کنیم، به صورت پیش فرض به اشیاء پیچیدهی سمت سرور bind نمیشود و باید حتما ویژگی FromBody را نیز مشخص کرد تا اطلاعات را از request body واکشی کند (محل دریافت اطلاعات پیش فرض آن نامشخص است).
یک سؤال: اگر به سمت یک چنین اکشن متدی، اطلاعات فرمی را به حالت معمول ارسال کنیم، چه اتفاقی رخ خواهد داد؟
ارسال اطلاعات فرمها به سرور، همواره شامل دو تغییر ذیل است:
var dataType = 'application/x-www-form-urlencoded; charset=utf-8'; var data = $('form').serialize();
[HttpPost] public IActionResult Index([FromForm]Person person)
علت این مساله نیز بالا رفتن میزان امنیت سیستم است. در نگارشهای قبلی، تمام مکانها و حالتهای میسر جستجو میشوند و اگر یکی از آنها قابلیت تطابق با خواص شیء مدنظر را داشته باشد، کار binding به پایان میرسد. اما در اینجا با مشخص شدن محل دقیق منبع اطلاعات، دیگر سایر حالات جستجو نشده و سطح حمله کاهش پیدا میکند.
در اینجا باید مشخص کرد که دقیقا اطلاعاتی که قرار است به یک شیء پیچیده Bind شوند، آیا از یک Form تامین میشوند، یا از Body و یا از هدر، کوئری استرینگ، مسیریابی و یا حتی از یک سرویس.
تمام این حالتها مشخص هستند (برای مثال دریافت اطلاعات از هدر درخواست HTTP و انتساب آنها به خواص متناظری در شیء مشخص شده)، منهای FromService آن که به نحو ذیل عمل میکند:
در این حالت میتوان در سازندهی کلاس مدل خود، سرویسی را تزریق کرد و توسط آن خاصیتی را مقدار دهی نمود:
public class ProductModel { public ProductModel(IProductService prodService) { Value = prodService.Get(productId); } public IProduct Value { get; private set; } }
public async Task<IActionResult> GetProduct([FromServices]ProductModel product) { }
تغییر تنظیمات اولیهی خروجیهای ASP.NET Web API
در اینجا حالت ارائهی خروجی XML به صورت پیش فرض فعال نیست. اگر علاقمند به افزودن آن نیز باشید، نحوهی کار را در متد ConfigureServices کلاس آغازین برنامه در کدهای ذیل مشاهده میکنید:
public void ConfigureServices(IServiceCollection services) { services.AddMvc(options => { options.FormatterMappings.SetMediaTypeMappingForFormat("xml", new MediaTypeHeaderValue("application/xml")); }).AddJsonOptions(options => { options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver(); options.SerializerSettings.DefaultValueHandling = DefaultValueHandling.Include; options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore; });
Senior Developer .Net Technologies Resume : ------------------------------------
احتمالا اکثر شما هم در آگهیهای استخدام برنامه نویس، با واژه Senior Developer یا برنامه نویس ارشد برخورد داشته اید. حال به راستی به چه کسی برنامه نویس ارشد گفته میشود. یا بهتره بگم که چه زمانی ما میتونیم خودمون را یک برنامه نویس ارشد بدونیم؟
از آنجا که تعریف مشخصی برای این واژهها در فرهنگ خاصی وجود ندارد و عموما هر کسی یک تعریف خاص با توجه به سلیقه خودش در این زمینه ارائه میدهد نمیتوان یک شرح واحد از این واژهها نظیر Senior Developer یا حتی Junior Developer ارائه داد. در نتیجه قصد دارم با توجه به تجربیات شخصی، این موارد رو تشریح کنم.
در خیلی موارد منظور از برنامه نویس ارشد، کسی است که:
- در حداقل یک یا دو زبان برنامه نویسی تجربه داشته باشد؛
- با تکنولوژیهای مهم و کارآمد ارائه شده در آن زبان آشنایی کامل داشته باشد؛
- توانایی استفاده از این تکنولوژیها را در جای مناسب پروژه دارا باشد؛
- با الگوهای برنامه نویسی (Design Pattern) آشنایی کامل داشته باشد؛
- بتواند به سایر اعضای تیم در حل مشکلات و باگهای برنامه کمک کند؛
- یک خطایاب قهار باشد(منظور این است با اکثر استثنائات و خطاهای متداول زبان و تکنولوژی که پروژه با آن پیاده سازی میشود آشنا باشد و بداند که چه زمان این خطا به وجود میآید و چگونه میتوان این موارد را برطرف کرد)؛
- باید با پیاده سازی سیستمهای سرویس گرا (SOA) جدای از تکنولوژی پیاده سازی آن آشنایی کامل داشته باشد؛
- باید با روشهای تست و خطایابی و ابزارهای توسعه و پیاده سازی آن آشنا بوده و توانایی استفاده از آنها را در پروژههای خود داشته باشد؛
- یک برنامه نویس ارشد باید در زمینه تخمین زمان تکمیل پروژه مهارت داشته باشد. باید بتواند مدت زمان لازم برای تکمیل یک Task را تخمین بزند و در همین مدت زمان، Task مربوطه را به صورت کامل پیاده سازی نماید.
- در خیلی موارد باید بتواند هماهنگی لازم را بین اعضای تیم برنامه نویسی ایجاد نماید؛
- و...
*ترتیب عبارات بالا دلیلی بر اولویت موارد ذکر شده نیست.
*منظور از آشنایی در عبارات بالا، یعنی تسلط و توانایی استفاده از آن با آگاهی تمام.
چه مدت زمان برای تبدیل شدن به یک برنامه نویس ارشد نیاز است؟
برای به دست آوردن مهارتها و تواناییهای یک برنامه نویس ارشد لازم است که حداقل 8 تا 10 سال تجربه برنامه نویسی در یک زبان را داشته باشید. البته این در مورد همگان صادق نیست . شاید کسی بتواند این راه را در کمتر از 8 سال طی نماید. این بستگی به تلاش و استعداد فرد دارد. اما تجربه بیشتر یعنی شرکت در پروژههای بیشتر و آمادگی بیشتر در حل مشکلات و مسائل مختلف در طی روند تکمیل پروژه. برای مثال در زمینه تخمین اجرای یک Task داشتن تجربه بیشتر خیلی به شما کمک خواهد کرد.
در پایان چهار ردیف یا رده مختلف را که بین برنامه نویسان رواج دارد ذکر میکنم.(از پایین به بالا)
Junior : عموما به کسی گفته میشود که 1 تا 3 سال تجربه برنامه نویسی دارد. معمولا کدهای نوشته شده توسط این افراد باید بررسی شود چون احتمال اشتباه در آن زیاد است. اکثر کدهای نوشته شده توسط این افراد به صورت dirty code است. راهنمایی هایی که به این افراد داده میشود شامل راهنمایی در زمینه ساختاری و الگوریتمی نیز میباشد.
Mid-Level : برنامه نویسان در این رده بین 4 تا 6 سال تجربه دارند. میتوانند به تنهایی نیز یک مشکل موجود در پروژه را حل نمایند. با مباحث مربوطه به طراحی کامپوننت آشنایی دارند و پروژه را بی نیاز از کامپوننت خواهند کرد. حتی در بعضی موارد میتوانند به تنهایی یک پروژه در سطح کوچک با متوسط را توسعه دهند.
Senior Developer : در بالا به صورت کامل شرح داده شد.
Luminary : به صورت معمول به کسی گفته میشود که تمام تواناییهای یک برنامه نویس ارشد را داراست و فقط تجربه برنامه نویسی آن قطعا از 10 سال بیشتر است.
از این واژه کمتر در ردههای برنامه نویسی استفاده میشود و بیشتر به همان واژه Senior Developer بسنده میکنند.
معرفی Angular tour
اگر از سرور ویندوزی استفاده میکنید، ثبت لاگهای برنامه در Windows EventLog و مشاهدهی آنها توسط Event viewer ویندوز، یکی از روشهای مناسب بررسی مشکلات برنامه پس از publish آن است. برای کار با آن، ابتدا نیاز است Windows Compatibility Pack for .NET Core را نصب کنید:
> dotnet add package Microsoft.Windows.Compatibility --version 2.0.0-preview1-25914-04
پس از آن فعالسازی ثبت در EventLog ویندوز به صورت ذیل است:
var webHost = new WebHostBuilder() //... .ConfigureLogging((hostingContext, logging) => { logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging")); logging.AddEventLog(); }) //...
آشنایی با XSLT
اساس کار XSLT
در تصویر زیر، فایل xml به همراه xslt، به تجزیه کننده یا تحلیل کننده داده میشوند. در این قسمت هر دو فایل منبع تحلیل شده و از روی فایل xml، درختی در حافظه تهیه میشود و از فایل xslt یک سری قوانین استخراج میشوند. بعد این دو محتوای جدید تولید شده، در اختیار XSL Processor قرار گرفته و از روی آنها به ساخت درخت نتیجه (نوع درخواستی) در حافظه میرسد که در نهایت آن را به نام یک فایل مستند میکند.
پروژه نمونه
در این مقاله ما یک فایل xml داریم که قصد داریم آلبومهایی را طبق ساختار زیر، در آن قرار دهیم و سپس بر اساس قوانین xslt آن را در قالب یک فایل html نشان دهیم. فایلهای تمرینی این مقاله در این آدرس قابل دسترسی است.
ساختار فایل xml:
<Albums> <Album> <name>Modern Talking</name> <cover>http://album.com/a.jpg</cover> <Genres> <Genre>POP</Genre> <Genre>Jazz</Genre> <Genre>Classic</Genre> </Genres> <Description> this is a marvelous Album </Description> <price> 25.99$ </price> </Album> </Albums>
در ابتدا فایل، برای معرفی فایل و رعایت قرارداد، فضای نام مربوطه را یا به شکل زیر
<xsl:stylesheet version="1.0"xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/"> <html> .... </html> </xsl:template>
نمایش فیلدها
سپس در آن، کد html مورد نظر را وارد میکنیم و در میان این کدها، تگهای xslt را وارد مینماییم. کد زیر بخشی از صفحه هست که برای نمایش آلبومها استفاده میکنیم:
<div> <img src="" alt="image" /> <h3> <xsl:value-of select="albums/album/name" /> </h3> <h4>Artist Name 1</h4> <h5>POP</h5> <h6>25/5/2015</h6> <h7>this is description</h7> <div> <a href="#">More</a> </div> </div>
<xsl:for-each select="albums/album"> <div> <img src="" alt="image" /> <h3> <xsl:value-of select="name" /> </h3> <h4>Artist Name 1</h4> <h5>POP</h5> <h6>25/5/2015</h6> <h7>this is description</h7> <div> <a href="#">More</a> </div> </div> </xsl:for-each>
ایجاد ارتباط میان دو فایل XML و XSLT
برای اجرا و تست آن باید از طریق یک ابزار که توانایی تحلیل این دستورات را دارد، استفاده کنید. یکی از همین ابزارها، مرورگر شماست. برای اینکه به مرورگر ارتباط فایل xml و xsl را بفهمانیم، تکه کد زیر را در فایل xml جهت لینک شدن مینویسیم و سپس فایل xml را در مرورگر اجرا میکنیم:
<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="index.xslt"?>
ساخت المان یا تگ
در ادامه بقیه فیلدها را تکمیل میکنیم. فیلد بعدی تصویر است که تصویر دیگر مانند متن، بین تگها قرار نمیگیرد و باید داخل attribute تگ تصویر درج شود. برای نمایش تصویر میتوانیم به دو شکل عمل کنیم. کد را به صورت زیر بنویسیم:
<img src="{cover}" width="200px" height="200px"> <xsl:value-of select="cover" /> </img>
<xsl:element name="img"> <xsl:attribute name="src"> <xsl:value-of select="cover"/> </xsl:attribute> <xsl:attribute name="width"> 200px </xsl:attribute> <xsl:attribute name="height"> 200px </xsl:attribute> <xsl:value-of select="cover"/> </xsl:element>
دستور العملهای بیشتر (مرتب سازی)
<xsl:for-each select="Albums/Album"> <xsl:sort select="name"/>
دستورات شرطی
حال تصمیم میگیریم که آلبومهای با قیمت بالاتر از 10 دلار را 2 دلار تخفیف دهیم. برای اینکار نیاز است تا با تگ if آشنا شویم:
<xsl:variable name="numprice" select="number(substring(price,1,string-length(price)-1))" /> <xsl:if test="$numprice>=10"> <h4 > <span style='text-decoration:line-through'> <xsl:value-of select="price" /> </span> <b> <xsl:value-of select="$numprice -2" />$ </b> </h4> </xsl:if>
<xsl:variable name="numprice" select="number(substring(price,1,string-length(price)-1))" /> <xsl:choose> <xsl:when test="$numprice>=10"> <h4 > <span style='text-decoration:line-through;color:red'> <xsl:value-of select="price" /> </span> <b> <xsl:value-of select="$numprice -2" />$ </b> </h4> </xsl:when> <xsl:otherwise> <b> <xsl:value-of select="$numprice" />$ </b> </xsl:otherwise> </xsl:choose>
استفاده از template ها
<xsl:template match="DateOfRelease"> <xsl:variable name="date" select="."/> <xsl:variable name="day" select="substring($date,1,2)"/> <xsl:variable name="month" select="number(substring($date,4,2))"/> <xsl:variable name="year" select="substring($date,7,4)"/> Release Date: <xsl:choose> <xsl:when test="$month = 1"> <xsl:value-of select="$day"/>,Jan/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 2"> <xsl:value-of select="$day"/>,Feb/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 3"> <xsl:value-of select="$day"/>,Mar/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 4"> <xsl:value-of select="$day"/>,Apr/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 5"> <xsl:value-of select="$day"/>,May/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 6"> <xsl:value-of select="$day"/>,Jun/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 7"> <xsl:value-of select="$day"/>,Jul/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 8"> <xsl:value-of select="$day"/>,Aug/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 9"> <xsl:value-of select="$day"/>,Sep/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 10"> <xsl:value-of select="$day"/>,Oct/<xsl:value-of select="$year"/> </xsl:when> <xsl:when test="$month = 11"> <xsl:value-of select="$day"/>,Nov/<xsl:value-of select="$year"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="$day"/>,Dec/<xsl:value-of select="$year"/> </xsl:otherwise> </xsl:choose> </xsl:template>
<xsl:for-each select="Albums/Album"> <xsl:sort select="name"/> <div> <img src="{cover}" width="200px" height="200px"> <xsl:value-of select="cover" /> </img> <h3> <xsl:value-of select="name" /> </h3> <h4>POP</h4> <xsl:variable name="numprice" select="number(substring(price,1,string-length(price)-1))" /> <xsl:choose> <xsl:when test="$numprice>=10"> <h4 > <span style='text-decoration:line-through;color:red'> <xsl:value-of select="price" /> </span> <b> <xsl:value-of select="$numprice -2" />$ </b> </h4> </xsl:when> <xsl:otherwise> <h4 > <b> <xsl:value-of select="$numprice -2" />$ </b> </h4> </xsl:otherwise> </xsl:choose> <h4> <!-- محل صدا زدن قالب--> <xsl:apply-templates select="DateOfRelease"/> </h4> <h4> <xsl:value-of select="Description"/> </h4> <div> <a href="#">More</a> </div> </div> </xsl:for-each>
فیلترسازی
یکی از خصوصیات دیگری که فایل
XML داشت، فیلد ژانر موسیقی بود و قصد داریم با استفاده از فیلترسازی،
تنها سبک خاصی مثل سبک پاپ را نمایش دهیم و موسیقیهایی را که خارج از این سبک
هستند، از نتیجه حذف کنیم. به همین علت دستور for-each را به شکل زیر
تغییر میدهیم:
<xsl:for-each select="Albums/Album[contains(Genres/Genre, 'POP')]">
<xsl:for-each select="Albums/Album[not(contains(Genres/Genre, 'POP'))]">
<xsl:for-each select="Genres/Genre"> <xsl:value-of select="."/> <xsl:if test="position() != last()"> , </xsl:if> </xsl:for-each>
تبدیل xml و xsl در دات نت
string xmlfile = Application.StartupPath + "\\sampleXML.xml"; //بارگذاری فایل قوانین در حافظه XslTransform xslt = new XslTransform(); xslt.Load("sample-stylesheet.xsl"); //XPath ایجاد یک سند جدید بر اساس استاندارد XPathDocument xpath = new XPathDocument(xmlfile); //آماده سازی برای نوشتن فایل نهایی XmlTextWriter xwriter = new XmlTextWriter(xmlfile + ".html", Encoding.UTF8); //نوشتن فایل مقصد بر اساس قوانین مشخص شده xslt.Transform(xpath, null, xwriter, null); xwriter.Close();
XsltArgumentList xslArgs = new XsltArgumentList(); xslArgs.AddParam("logo", "", logo); xslArgs.AddParam("name", "", name); .... xslt.Transform(xpath, xslArgs, xwriter, null);
پیاده سازیهای زیادی را در مورد JSON Web Token با ASP.NET Web API، با کمی جستجو میتوانید پیدا کنید. اما مشکلی که تمام آنها دارند، شامل این موارد هستند:
- چون توکنهای JWT، خودشمول هستند (در پیشنیاز بحث مطرح شدهاست)، تا زمانیکه این توکن منقضی نشود، کاربر با همان سطح دسترسی قبلی میتواند به سیستم، بدون هیچگونه مانعی لاگین کند. در این حالت اگر این کاربر غیرفعال شود، کلمهی عبور او تغییر کند و یا سطح دسترسیهای او کاهش یابند ... مهم نیست! باز هم میتواند با همان توکن قبلی لاگین کند.
- در روش JSON Web Token، عملیات Logout سمت سرور بیمعنا است. یعنی اگر برنامهای در سمت کاربر، قسمت logout را تدارک دیده باشد، چون در سمت سرور این توکنها جایی ذخیره نمیشوند، عملا این logout بیمفهوم است و مجددا میتوان از همان توکن قبلی، برای لاگین به سرور استفاده کرد. چون این توکن شامل تمام اطلاعات لازم برای لاگین است و همچنین جایی هم در سرور ثبت نشدهاست که این توکن در اثر logout، باید غیرمعتبر شود.
- با یک توکن از مکانهای مختلفی میتوان دسترسی لازم را جهت استفادهی از قسمتهای محافظت شدهی برنامه یافت (در صورت دسترسی، چندین نفر میتوانند از آن استفاده کنند).
به همین جهت راه حلی عمومی برای ذخیره سازی توکنهای صادر شده از سمت سرور، در بانک اطلاعاتی تدارک دیده شد که در ادامه به بررسی آن خواهیم پرداخت و این روشی است که میتواند به عنوان پایه مباحث Authentication و Authorization برنامههای تک صفحهای وب استفاده شود. البته سمت کلاینت این راه حل با jQuery پیاده سازی شدهاست (عمومی است؛ برای طرح مفاهیم پایه) و سمت سرور آن به عمد از هیچ نوع بانک اطلاعات و یا ORM خاصی استفاده نمیکند. سرویسهای آن برای بکارگیری انواع و اقسام روشهای ذخیره سازی اطلاعات قابل تغییر هستند و الزامی نیست که حتما از EF استفاده کنید یا از ASP.NET Identity یا هر روش خاص دیگری.
نگاهی به برنامه
در اینجا تمام قابلیتهای این پروژه را مشاهده میکنید.
- امکان لاگین
- امکان دسترسی به یک کنترلر مزین شدهی با فلیتر Authorize
- امکان دسترسی به یک کنترلر مزین شدهی با فلیتر Authorize جهت کاربری با نقش Admin
- پیاده سازی مفهوم ویژهای به نام refresh token که نیاز به لاگین مجدد را پس از منقضی شدن زمان توکن اولیهی لاگین، برطرف میکند.
- پیاده سازی logout
بستههای پیشنیاز برنامه
پروژهای که در اینجا بررسی شدهاست، یک پروژهی خالی ASP.NET Web API 2.x است و برای شروع به کار با JSON Web Tokenها، تنها نیاز به نصب 4 بستهی زیر را دارد:
PM> Install-Package Microsoft.Owin.Host.SystemWeb PM> Install-Package Microsoft.Owin.Security.Jwt PM> Install-Package structuremap PM> Install-Package structuremap.web
از structuremap هم برای تنظیمات تزریق وابستگیهای برنامه استفاده شدهاست. به این صورت قسمت تنظیمات اولیهی JWT ثابت باقی خواهد ماند و صرفا نیاز خواهید داشت تا کمی قسمت سرویسهای برنامه را بر اساس بانک اطلاعاتی و روش ذخیره سازی خودتان سفارشی سازی کنید.
دریافت کدهای کامل برنامه
کدهای کامل این برنامه را از اینجا میتوانید دریافت کنید. در ادامه صرفا قسمتهای مهم این کدها را بررسی خواهیم کرد.
بررسی کلاس AppJwtConfiguration
کلاس AppJwtConfiguration، جهت نظم بخشیدن به تعاریف ابتدایی توکنهای برنامه در فایل web.config، ایجاد شدهاست. اگر به فایل web.config برنامه مراجعه کنید، یک چنین تعریفی را مشاهده خواهید کرد:
<appJwtConfiguration tokenPath="/login" expirationMinutes="2" refreshTokenExpirationMinutes="60" jwtKey="This is my shared key, not so secret, secret!" jwtIssuer="http://localhost/" jwtAudience="Any" />
<configSections> <section name="appJwtConfiguration" type="JwtWithWebAPI.JsonWebTokenConfig.AppJwtConfiguration" /> </configSections>
- در این تنظیمات، دو زمان منقضی شدن را مشاهده میکنید؛ یکی مرتبط است به access tokenها و دیگری مرتبط است به refresh tokenها که در مورد اینها، در ادامه بیشتر توضیح داده خواهد شد.
- jwtKey، یک کلید قوی است که از آن برای امضاء کردن توکنها در سمت سرور استفاده میشود.
- تنظیمات Issuer و Audience هم در اینجا اختیاری هستند.
یک نکته
جهت سهولت کار تزریق وابستگیها، برای کلاس AppJwtConfiguration، اینترفیس IAppJwtConfiguration نیز تدارک دیده شدهاست و در تمام تنظیمات ابتدایی JWT، از این اینترفیس بجای استفادهی مستقیم از کلاس AppJwtConfiguration استفاده شدهاست.
بررسی کلاس OwinStartup
شروع به کار تنظیمات JWT و ورود آنها به چرخهی حیات Owin از کلاس OwinStartup آغاز میشود. در اینجا علت استفادهی از SmObjectFactory.Container.GetInstance انجام تزریق وابستگیهای لازم جهت کار با دو کلاس AppOAuthOptions و AppJwtOptions است.
- در کلاس AppOAuthOptions تنظیماتی مانند نحوهی تهیهی access token و همچنین refresh token ذکر میشوند.
- در کلاس AppJwtOptions تنظیمات فایل وب کانفیگ، مانند کلید مورد استفادهی جهت امضای توکنهای صادر شده، ذکر میشوند.
حداقلهای بانک اطلاعاتی مورد نیاز جهت ذخیره سازی وضعیت کاربران و توکنهای آنها
همانطور که در ابتدای بحث عنوان شد، میخواهیم اگر سطوح دسترسی کاربر تغییر کرد و یا اگر کاربر logout کرد، توکن فعلی او صرفنظر از زمان انقضای آن، بلافاصله غیرقابل استفاده شود. به همین جهت نیاز است حداقل دو جدول زیر را در بانک اطلاعاتی تدارک ببینید:
الف) کلاس User
در کلاس User، بر مبنای اطلاعات خاصیت Roles آن است که ویژگی Authorize با ذکر نقش مثلا Admin کار میکند. بنابراین حداقل نقشی را که برای کاربران، در ابتدای کار نیاز است مشخص کنید، نقش user است.
همچنین خاصیت اضافهتری به نام SerialNumber نیز در اینجا درنظر گرفته شدهاست. این مورد را باید به صورت دستی مدیریت کنید. اگر کاربری کلمهی عبورش را تغییر داد، اگر مدیری نقشی را به او انتساب داد یا از او گرفت و یا اگر کاربری غیرفعال شد، مقدار خاصیت و فیلد SerialNumber را با یک Guid جدید به روز رسانی کنید. این Guid در برنامه با Guid موجود در توکن مقایسه شده و بلافاصله سبب عدم دسترسی او خواهد شد (در صورت عدم تطابق).
ب) کلاس UserToken
در کلاس UserToken کار نگهداری ریز اطلاعات توکنهای صادر شده صورت میگیرد. توکنهای صادر شده دارای access token و refresh token هستند؛ به همراه زمان انقضای آنها. به این ترتیب زمانیکه کاربری درخواستی را به سرور ارسال میکند، ابتدا token او را دریافت کرده و سپس بررسی میکنیم که آیا اصلا چنین توکنی در بانک اطلاعاتی ما وجود خارجی دارد یا خیر؟ آیا توسط ما صادر شدهاست یا خیر؟ اگر خیر، بلافاصله دسترسی او قطع خواهد شد. برای مثال عملیات logout را طوری طراحی میکنیم که تمام توکنهای یک شخص را در بانک اطلاعاتی حذف کند. به این ترتیب توکن قبلی او دیگر قابلیت استفادهی مجدد را نخواهد داشت.
مدیریت بانک اطلاعاتی و کلاسهای سرویس برنامه
در لایه سرویس برنامه، شما سه سرویس را مشاهده خواهید کرد که قابلیت جایگزین شدن با کدهای یک ORM را دارند (نوع آن ORM مهم نیست):
الف) سرویس TokenStoreService
public interface ITokenStoreService { void CreateUserToken(UserToken userToken); bool IsValidToken(string accessToken, int userId); void DeleteExpiredTokens(); UserToken FindToken(string refreshTokenIdHash); void DeleteToken(string refreshTokenIdHash); void InvalidateUserTokens(int userId); void UpdateUserToken(int userId, string accessTokenHash); }
پیاده سازی این کلاس بسیار شبیه است به پیاده سازی ORMهای موجود و فقط یک SaveChanges را کم دارد.
یک نکته:
در سرویس ذخیره سازی توکنها، یک چنین متدی قابل مشاهده است:
public void CreateUserToken(UserToken userToken) { InvalidateUserTokens(userToken.OwnerUserId); _tokens.Add(userToken); }
ب) سرویس UsersService
public interface IUsersService { string GetSerialNumber(int userId); IEnumerable<string> GetUserRoles(int userId); User FindUser(string username, string password); User FindUser(int userId); void UpdateUserLastActivityDate(int userId); }
همچنین متدهای دیگری برای یافتن یک کاربر بر اساس نام کاربری و کلمهی عبور او (جهت مدیریت مرحلهی لاگین)، یافتن کاربر بر اساس Id او (جهت استخراج اطلاعات کاربر) و همچنین یک متد اختیاری نیز برای به روز رسانی فیلد آخرین تاریخ فعالیت کاربر در اینجا پیش بینی شدهاند.
ج) سرویس SecurityService
public interface ISecurityService { string GetSha256Hash(string input); }
پیاده سازی قسمت لاگین و صدور access token
در کلاس AppOAuthProvider کار پیاده سازی قسمت لاگین برنامه انجام شدهاست. این کلاسی است که توسط کلاس AppOAuthOptions به OwinStartup معرفی میشود. قسمتهای مهم کلاس AppOAuthProvider به شرح زیر هستند:
برای درک عملکرد این کلاس، در ابتدای متدهای مختلف آن، یک break point قرار دهید. برنامه را اجرا کرده و سپس بر روی دکمهی login کلیک کنید. به این ترتیب جریان کاری این کلاس را بهتر میتوانید درک کنید. کار آن با فراخوانی متد ValidateClientAuthentication شروع میشود. چون با یک برنامهی وب در حال کار هستیم، ClientId آنرا نال درنظر میگیریم و برای ما مهم نیست. اگر کلاینت ویندوزی خاصی را تدارک دیدید، این کلاینت میتواند ClientId ویژهای را به سمت سرور ارسال کند که در اینجا مدنظر ما نیست.
مهمترین قسمت این کلاس، متد GrantResourceOwnerCredentials است که پس از ValidateClientAuthentication بلافاصله فراخوانی میشود. اگر به کدهای آن دقت کنید، خود owin دارای خاصیتهای user name و password نیز هست.
این اطلاعات را به نحو ذیل از کلاینت خود دریافت میکند. اگر به فایل index.html مراجعه کنید، یک چنین تعریفی را برای متد login میتوانید مشاهده کنید:
function doLogin() { $.ajax({ url: "/login", // web.config --> appConfiguration -> tokenPath data: { username: "Vahid", password: "1234", grant_type: "password" }, type: 'POST', // POST `form encoded` data contentType: 'application/x-www-form-urlencoded'
در متد GrantResourceOwnerCredentials کار بررسی نام کاربری و کلمهی عبور کاربر صورت گرفته و در صورت یافت شدن کاربر (صحیح بودن اطلاعات)، نقشهای او نیز به عنوان Claim جدید به توکن اضافه میشوند.
در اینجا یک Claim سفارشی هم اضافه شدهاست:
identity.AddClaim(new Claim(ClaimTypes.UserData, user.UserId.ToString()));
در انتهای این کلاس، از متد TokenEndpointResponse جهت دسترسی به access token نهایی صادر شدهی برای کاربر، استفاده کردهایم. هش این access token را در بانک اطلاعاتی ذخیره میکنیم (جستجوی هشها سریعتر هستند از جستجوی یک رشتهی طولانی؛ به علاوه در صورت دسترسی به بانک اطلاعاتی، اطلاعات هشها برای مهاجم قابل استفاده نیست).
اگر بخواهیم اطلاعات ارسالی به کاربر را پس از لاگین، نمایش دهیم، به شکل زیر خواهیم رسید:
در اینجا access_token همان JSON Web Token صادر شدهاست که برنامهی کلاینت از آن برای اعتبارسنجی استفاده خواهد کرد.
بنابراین خلاصهی مراحل لاگین در اینجا به ترتیب ذیل است:
- فراخوانی متد ValidateClientAuthenticationدر کلاس AppOAuthProvider . طبق معمول چون ClientID نداریم، این مرحله را قبول میکنیم.
- فراخوانی متد GrantResourceOwnerCredentials در کلاس AppOAuthProvider . در اینجا کار اصلی لاگین به همراه تنظیم Claims کاربر انجام میشود. برای مثال نقشهای او به توکن صادر شده اضافه میشوند.
- فراخوانی متد Protect در کلاس AppJwtWriterFormat که کار امضای دیجیتال access token را انجام میدهد.
- فراخوانی متد CreateAsync در کلاس RefreshTokenProvider. کار این متد صدور توکن ویژهای به نام refresh است. این توکن را در بانک اطلاعاتی ذخیره خواهیم کرد. در اینجا چیزی که به سمت کلاینت ارسال میشود صرفا یک guid است و نه اصل refresh token.
- فرخوانی متد TokenEndpointResponse در کلاس AppOAuthProvider . از این متد جهت یافتن access token نهایی تولید شده و ثبت هش آن در بانک اطلاعاتی استفاده میکنیم.
پیاده سازی قسمت صدور Refresh token
در تصویر فوق، خاصیت refresh_token را هم در شیء JSON ارسالی به سمت کاربر مشاهده میکنید. هدف از refresh_token، تمدید یک توکن است؛ بدون ارسال کلمهی عبور و نام کاربری به سرور. در اینجا access token صادر شده، مطابق تنظیم expirationMinutes در فایل وب کانفیگ، منقضی خواهد شد. اما طول عمر refresh token را بیشتر از طول عمر access token در نظر میگیریم. بنابراین طول عمر یک access token کوتاه است. زمانیکه access token منقضی شد، نیازی نیست تا حتما کاربر را به صفحهی لاگین هدایت کنیم. میتوانیم refresh_token را به سمت سرور ارسال کرده و به این ترتیب درخواست صدور یک access token جدید را ارائه دهیم. این روش هم سریعتر است (کاربر متوجه این retry نخواهد شد) و هم امنتر است چون نیازی به ارسال کلمهی عبور و نام کاربری به سمت سرور وجود ندارند.
سمت کاربر، برای درخواست صدور یک access token جدید بر اساس refresh token صادر شدهی در زمان لاگین، به صورت زیر عمل میشود:
function doRefreshToken() { // obtaining new tokens using the refresh_token should happen only if the id_token has expired. // it is a bad practice to call the endpoint to get a new token every time you do an API call. $.ajax({ url: "/login", // web.config --> appConfiguration -> tokenPath data: { grant_type: "refresh_token", refresh_token: refreshToken }, type: 'POST', // POST `form encoded` data contentType: 'application/x-www-form-urlencoded'
- فرخوانی متد ValidateClientAuthentication در کلاس AppOAuthProvider . طبق معمول چون ClientID نداریم، این مرحله را قبول میکنیم.
- فراخوانی متد ReceiveAsync در کلاس RefreshTokenProvider. در قسمت توضیح مراحل لاگین، عنوان شد که پس از فراخوانی متد GrantResourceOwnerCredentials جهت لاگین، متد CreateAsync در کلاس RefreshTokenProvider فراخوانی میشود. اکنون در متد ReceiveAsync این refresh token ذخیره شدهی در بانک اطلاعاتی را یافته (بر اساس Guid ارسالی از طرف کلاینت) و سپس Deserialize میکنیم. به این ترتیب است که کار درخواست یک access token جدید بر مبنای refresh token موجود آغاز میشود.
- فراخوانی GrantRefreshToken در کلاس AppOAuthProvider . در اینجا اگر نیاز به تنظیم Claim اضافهتری وجود داشت، میتوان اینکار را انجام داد.
- فراخوانی متد Protect در کلاس AppJwtWriterFormat که کار امضای دیجیتال access token جدید را انجام میدهد.
- فراخوانی CreateAsync در کلاس RefreshTokenProvider . پس از اینکه context.DeserializeTicket در متد ReceiveAsync بر مبنای refresh token قبلی انجام شد، مجددا کار تولید یک توکن جدید در متد CreateAsync شروع میشود و زمان انقضاءها تنظیم خواهند شد.
- فراخوانی TokenEndpointResponse در کلاس AppOAuthProvider . مجددا از این متد برای دسترسی به access token جدید و ذخیرهی هش آن در بانک اطلاعاتی استفاده میکنیم.
پیاده سازی فیلتر سفارشی JwtAuthorizeAttribute
در ابتدای بحث عنوان کردیم که اگر مشخصات کاربر تغییر کردند یا کاربر logout کرد، امکان غیرفعال کردن یک توکن را نداریم و این توکن تا زمان انقضای آن معتبر است. این نقیصه را با طراحی یک AuthorizeAttribute سفارشی جدید به نام JwtAuthorizeAttribute برطرف میکنیم. نکات مهم این فیلتر به شرح زیر هستند:
- در اینجا در ابتدا بررسی میشود که آیا درخواست رسیدهی به سرور، حاوی access token هست یا خیر؟ اگر خیر، کار همینجا به پایان میرسد و دسترسی کاربر قطع خواهد شد.
- سپس بررسی میکنیم که آیا درخواست رسیده پس از مدیریت توسط Owin، دارای Claims است یا خیر؟ اگر خیر، یعنی این توکن توسط ما صادر نشدهاست.
- در ادامه شماره سریال موجود در access token را استخراج کرده و آنرا با نمونهی موجود در دیتابیس مقایسه میکنیم. اگر این دو یکی نبودند، دسترسی کاربر قطع میشود.
- همچنین در آخر بررسی میکنیم که آیا هش این توکن رسیده، در بانک اطلاعاتی ما موجود است یا خیر؟ اگر خیر باز هم یعنی این توکن توسط ما صادر نشدهاست.
بنابراین به ازای هر درخواست به سرور، دو بار بررسی بانک اطلاعاتی را خواهیم داشت:
- یکبار بررسی جدول کاربران جهت واکشی مقدار فیلد شماره سریال مربوط به کاربر.
- یکبار هم جهت بررسی جدول توکنها برای اطمینان از صدور توکن رسیده توسط برنامهی ما.
و نکتهی مهم اینجا است که از این پس بجای فیلتر معمولی Authorize، از فیلتر جدید JwtAuthorize در برنامه استفاده خواهیم کرد:
[JwtAuthorize(Roles = "Admin")] public class MyProtectedAdminApiController : ApiController
نحوهی ارسال درخواستهای Ajax ایی به همراه توکن صادر شده
تا اینجا کار صدور توکنهای برنامه به پایان میرسد. برای استفادهی از این توکنها در سمت کاربر، به فایل index.html دقت کنید. در متد doLogin، پس از موفقیت عملیات دو متغیر جدید مقدار دهی میشوند:
var jwtToken; var refreshToken; function doLogin() { $.ajax({ // same as before }).then(function (response) { jwtToken = response.access_token; refreshToken = response.refresh_token; }
function doCallApi() { $.ajax({ headers: { 'Authorization': 'Bearer ' + jwtToken }, url: "/api/MyProtectedApi", type: 'GET' }).then(function (response) {
پیاده سازی logout سمت سرور و کلاینت
پیاده سازی سمت سرور logout را در کنترلر UserController مشاهده میکنید. در اینجا در اکشن متد Logout، کار حذف توکنهای کاربر از بانک اطلاعاتی انجام میشود. به این ترتیب دیگر مهم نیست که توکن او هنوز منقضی شدهاست یا خیر. چون هش آن دیگر در جدول توکنها وجود ندارد، از فیلتر JwtAuthorizeAttribute رد نخواهد شد.
سمت کلاینت آن نیز در فایل index.html ذکر شدهاست:
function doLogout() { $.ajax({ headers: { 'Authorization': 'Bearer ' + jwtToken }, url: "/api/user/logout", type: 'GET'
بررسی تنظیمات IoC Container برنامه
تنظیمات IoC Container برنامه را در پوشهی IoCConfig میتوانید ملاحظه کنید. از کلاس SmWebApiControllerActivator برای فعال سازی تزریق وابستگیها در کنترلرهای Web API استفاده میشود و از کلاس SmWebApiFilterProvider برای فعال سازی تزریق وابستگیها در فیلتر سفارشی که ایجاد کردیم، کمک گرفته خواهد شد.
هر دوی این تنظیمات نیز در کلاس WebApiConfig ثبت و معرفی شدهاند.
به علاوه در کلاس SmObjectFactory، کار معرفی وهلههای مورد استفاده و تنظیم طول عمر آنها انجام شدهاست. برای مثال طول عمر IOAuthAuthorizationServerProvider از نوع Singleton است؛ چون تنها یک وهله از AppOAuthProvider در طول عمر برنامه توسط Owin استفاده میشود و Owin هربار آنرا وهله سازی نمیکند. همین مساله سبب شدهاست که معرفی وابستگیها در سازندهی کلاس AppOAuthProvider کمی با حالات متداول، متفاوت باشند:
public AppOAuthProvider( Func<IUsersService> usersService, Func<ITokenStoreService> tokenStoreService, ISecurityService securityService, IAppJwtConfiguration configuration)
در اینجا سرویس IAppJwtConfiguration با Func معرفی نشدهاست؛ چون طول عمر تنظیمات خوانده شدهی از Web.config نیز Singleton هستند و معرفی آن به همین نحو صحیح است.
اگر علاقمند بودید که بررسی کنید یک سرویس چندبار وهله سازی میشود، یک سازندهی خالی را به آن اضافه کنید و سپس یک break point را بر روی آن قرار دهید و برنامه را اجرا و در این حالت چندبار Login کنید.
پیشنیاز: ایجاد یک برنامهی خالی React و ASP.NET Core
یک پوشهی خالی را ایجاد کرده و در آن دستور dotnet new react را صادر کنید، تا قالب خاص پروژههای React یکی سازی شدهی با پروژههای ASP.NET Core، یک پروژهی جدید را ایجاد کند.
همانطور که در تصویر فوق نیز مشاهده میکنید، این پروژه از دو برنامه تشکیل شدهاست:
الف) برنامهی SPA که در پوشهی ClientApp قرار گرفتهاست و شامل کدهای کامل یک برنامهی React است.
ب) برنامهی سمت سرور ASP.NET Core که یک برنامهی متداول وب، به همراه فایل Startup.cs و سایر فایلهای مورد نیاز آن است.
در ادامه نکات ویژهی ساختار این پروژه را بررسی خواهیم کرد.
تجربهی توسعهی برنامهها توسط این قالب ویژه
اکنون اگر این پروژهی وب را برای مثال با فشردن دکمهی F5 و یا اجرای دستور dotnet run، اجرا کنیم، چه اتفاقی رخ میدهد؟
- به صورت خلاصه برنامهی ASP.NET Core شروع به کار کرده و سبب ارائه همزمان برنامهی SPA نیز خواهد شد.
- پورتی که برنامهی وب بر روی آن قرار دارد، با پورتی که برنامهی React بر روی روی آن ارائه میشود، یکی است. یعنی نیازی به تنظیمات CORS را ندارد.
- در این حالت اگر در برنامهی React تغییری را ایجاد کنیم (در هر قسمتی از آن)، hot reloading آن هنوز هم برقرار است و سبب بارگذاری مجدد برنامهی SPA در مرورگر خواهد شد و برای اینکار نیازی به توقف و راه اندازی مجدد برنامهی ASP.NET Core نیست.
اما این تجربهی روان کاربری و توسعه، چگونه حاصل شدهاست؟
بررسی ساختار فایل Startup.cs یک پروژهی مبتنی بر dotnet new react
برای درک نحوهی عملکرد این قالب ویژه، نیاز است از فایل Startup.cs آن شروع کرد.
// ... using Microsoft.AspNetCore.SpaServices.ReactDevelopmentServer; namespace dotnet_template_sample { public class Startup { // ... public void ConfigureServices(IServiceCollection services) { services.AddControllersWithViews(); // In production, the React files will be served from this directory services.AddSpaStaticFiles(configuration => { configuration.RootPath = "ClientApp/build"; }); }
<ItemGroup> <PackageReference Include="Microsoft.AspNetCore.SpaServices.Extensions" Version="3.1.2" /> </ItemGroup>
در متد ConfigureServices، ثبت سرویسهای مرتبط با فایلهای استاتیک پروژهی SPA، توسط متد AddSpaStaticFiles صورت گرفتهاست. در اینجا RootPath آن، به پوشهی ClientApp/build اشاره میکند. البته این پوشه هنوز در این ساختار، قابل مشاهده نیست؛ اما زمانیکه پروژهی ASP.NET Core را برای ارائهی نهایی، publish کردیم، به صورت خودکار ایجاد شده و حاوی فایلهای قابل ارائهی برنامهی React نیز خواهد بود.
قسمت مهم دیگر کلاس آغازین برنامه، متد Configure آن است:
// ... using Microsoft.AspNetCore.SpaServices.ReactDevelopmentServer; namespace dotnet_template_sample { public class Startup { // ... public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { // ... app.UseStaticFiles(); app.UseSpaStaticFiles(); app.UseRouting(); app.UseEndpoints(endpoints => { endpoints.MapControllerRoute( name: "default", pattern: "{controller}/{action=Index}/{id?}"); }); app.UseSpa(spa => { spa.Options.SourcePath = "ClientApp"; if (env.IsDevelopment()) { spa.UseReactDevelopmentServer(npmScript: "start"); } }); } } }
- متد UseSpaStaticFiles، سبب ثبت میانافزاری میشود که امکان دسترسی به فایلهای استاتیک پوشهی ClientApp حاوی برنامهی React را میسر میکند؛ مسیر این پوشه را در متد ConfigureServices تنظیم کردیم.
- متد UseSpa، سبب ثبت میانافزاری میشود که دو کار مهم را انجام میدهد:
1- کار اصلی آن، ثبت مسیریابی معروف catch all است تا مسیریابیهایی را که توسط کنترلرهای برنامهی ASP.NET Core مدیریت نمیشوند، به سمت برنامهی React هدایت کند. برای مثال مسیر https://localhost:5001/api/users به یک کنترلر API برنامهی سمت سرور ختم میشود، اما سایر مسیرها مانند https://localhost:5001/login قرار است صفحهی login برنامهی سمت کلاینت SPA را نمایش دهند و متناظر با اکشن متد خاصی در کنترلرهای برنامهی وب ما نیستند. در این حالت، کار این مسیریابی catch all، نمایش صفحهی پیشفرض برنامهی SPA است.
2- بررسی میکند که آیا شرایط IsDevelopment برقرار است؟ آیا در حال توسعهی برنامه هستیم؟ اگر بله، میانافزار دیگری را به نام UseReactDevelopmentServer، اجرا و ثبت میکند.
برای درک عملکرد میانافزار ReactDevelopmentServer نیاز است به سورس آن مراجعه کرد. این میانافزار بر اساس پارامتر start ای که دریافت میکند، سبب اجرای npm run start خواهد شد. به این ترتیب دیگر نیازی به اجرای جداگانهی این دستور نخواهد بود و همچنین این اجرا، به همراه تنظیمات proxy مخصوصی نیز هست تا پورت اجرایی برنامهی React و برنامهی ASP.NET Core یکی شده و دیگر نیازی به تنظیمات CORS مخصوص برنامههای React نباشد. بنابراین hot reloading ای که از آن صحبت شد، توسط ASP.NET Core مدیریت نمیشود. در پشت صحنه همان npm run start اصلی برنامههای React، در حال اجرای وب سرور آزمایشی React است که از hot reloading پشتیبانی میکند.
یک مشکل: با این تنظیم، هربار که برنامهی ASP.NET Core اجرا میشود (به علت تغییرات در کدها و فایلهای پروژه)، سبب اجرای مجدد و پشت صحنهی react development server نیز خواهد شد که ... آغاز برنامه را در حالت توسعه، کند میکند. برای رفع این مشکل میتوان این وب سرور توسعهی برنامههای React را به صورت جداگانهای اجرا کرد و فقط تنظیمات پروکسی آنرا در اینجا ذکر نمود:
// replace spa.UseReactDevelopmentServer(npmScript: "start"); // with spa.UseProxyToSpaDevelopmentServer("http://localhost:3000");
تغییرات ویژهی فایل csproj برنامه
اگر به فایل csproj برنامه دقت کنیم، دو تغییر جدید نیز در آن قابل مشاهده هستند:
الف) نصب خودکار وابستگیهای برنامهی client
<Target Name="DebugEnsureNodeEnv" BeforeTargets="Build" Condition=" '$(Configuration)' == 'Debug' And !Exists('$(SpaRoot)node_modules') "> <!-- Ensure Node.js is installed --> <Exec Command="node --version" ContinueOnError="true"> <Output TaskParameter="ExitCode" PropertyName="ErrorCode" /> </Exec> <Error Condition="'$(ErrorCode)' != '0'" Text="Node.js is required to build and run this project. To continue, please install Node.js from https://nodejs.org/, and then restart your command prompt or IDE." /> <Message Importance="high" Text="Restoring dependencies using 'npm'. This may take several minutes..." /> <Exec WorkingDirectory="$(SpaRoot)" Command="npm install" /> </Target>
ب) یکی کردن تجربهی publish برنامهی ASP.NET Core با publish پروژههای React
<Target Name="PublishRunWebpack" AfterTargets="ComputeFilesToPublish"> <!-- As part of publishing, ensure the JS resources are freshly built in production mode --> <Exec WorkingDirectory="$(SpaRoot)" Command="npm install" /> <Exec WorkingDirectory="$(SpaRoot)" Command="npm run build" /> <!-- Include the newly-built files in the publish output --> <ItemGroup> <DistFiles Include="$(SpaRoot)build\**" /> <ResolvedFileToPublish Include="@(DistFiles->'%(FullPath)')" Exclude="@(ResolvedFileToPublish)"> <RelativePath>%(DistFiles.Identity)</RelativePath> <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory> <ExcludeFromSingleFile>true</ExcludeFromSingleFile> </ResolvedFileToPublish> </ItemGroup> </Target>
- ابتدا npm install را جهت اطمینان از به روز بودن وابستگیهای برنامه مجددا اجرا میکند.
- سپس npm run build را برای تولید فایلهای قابل ارائهی برنامهی React اجرا میکند.
- در آخر تمام فایلهای پوشهی ClientApp/build تولیدی را به بستهی نهایی توزیعی برنامهی ASP.NET Core، اضافه میکند.