اضافه کردن NET Aspire. به اپلیکیشن‌های NET.موجود

 NET Aspire.یک استک جدید و آماده برای کلود است که برای NET. طراحی شده و به توسعه‌دهندگان کمک می‌کند تا به‌راحتی و با سرعت، اپلیکیشن‌های توزیع‌شده ایجاد کنند. شاید تا به حال دموهایی از پروژه‌های بزرگ NET . دیده باشید که وابستگی‌های پیچیده‌ای به سرویس‌های ابری دارند و با خود فکر کرده باشید که اگر روزی بخواهم یک اپلیکیشن بزرگ با ابزارهایی مثل Redis، Kafka و Postgres بسازم، از اینها استفاده می‌کنم. اما فعلاً برای من کاربردی ندارد.

NET Aspire. فقط برای تکنولوژی‌های پیشرفته یا اپلیکیشن‌های جدید نیست؛ بلکه هدف اصلی آن ساده‌تر کردن اپلیکیشن‌های فعلی شماست. با استفاده از 
NET Aspire.  ، می‌توانید فرآیند راه‌اندازی اپلیکیشن‌هایتان را آسان‌تر کنید، نظارت را بهبود ببخشید و قابلیت اطمینان برنامه‌های خود را افزایش دهید. حتی اگر هنوز آماده استفاده از ویژگی‌ها یا سرویس‌های پیچیده‌تری مثل Redis یا استقرار کانتینری نیستید، می‌توانید با استفاده از service discovery اپلیکیشن‌های خود را بهبود دهید.
در این مقاله، به شما نشان خواهیم داد که چطور می‌توان سولوشن‌های موجود را با ساده‌تر کردن نگهداری و افزودن ویژگی‌هایی که در حال حاضر روی آن‌ها کار می‌کنید، بهتر کرد. البته، اگر بتوانید وابستگی‌ها و ویژگی‌های پیچیده‌تر کلود را هم یکپارچه کنید، عالی است... اما حتی اگر این کار را نکنید، باز هم NET Aspire. به شما کمک می‌کند.
خلاصه: در کمتر از ۵ دقیقه می‌توانید NET Aspire. را به اپلیکیشن‌های موجود خود اضافه کنید و داشبورد، health checks و قابلیت‌های بیشتر را دریافت کنید... و همه اینها بدون نیاز به تغییر در نحوه کار اپلیکیشن‌هایتان، پایپلاین CI/CD، یا فرآیند استقرار انجام می‌شود. 

NET Aspire.  چیست؟

اگر از پنج نفر بپرسید، احتمالاً پنج جواب متفاوت خواهید گرفت. توضیح دادنش کمی پیچیده است، و خلاصه کردنش ممکن است به بازی با کلمات تخصصی تبدیل شود. اما به طور خلاصه، NET Aspire. راه‌حلی برای یک مشکل است: ساختن اپلیکیشن‌های توزیع‌شده کار سختی است. حتی راه‌اندازی یک اپلیکیشن به تنهایی نیازمند شروع چندین سرویس و یک front-end است، و مطمئن شدن از اینکه همه آن‌ها به‌درستی با هم کار می‌کنند، می‌تواند خسته‌کننده باشد.
چی می‌شد اگر این کارها راحت‌تر انجام می‌شد؟ NET Aspire. دقیقاً برای همین طراحی شده است؛ تا به عنوان بلوک‌های سازنده برای اپلیکیشن‌های توزیع‌شده شما عمل کند و آن‌ها را قابل مشاهده‌تر، مقاوم‌تر، مقیاس‌پذیرتر و مدیریت‌پذیرتر کند
  بیایید ببینیم چطور بسیاری از اپلیکیشن‌ها به مرور زمان تکامل پیدا می‌کنند. اغلب این اپلیکیشن‌ها به‌عنوان یک Proof of Concept ساده شروع می‌شوند؛ یک اپلیکیشن ساده که فقط به یک دیتابیس متصل است.

فرض کنید Proof of Concept شما در بازار موفق شد و در حال رشد است. تقریباً هر اپلیکیشن مدرن بعد از موفقیت اولیه، به جایی می‌رسد که حداقل یک frontend و backend به همراه دیتابیس داشته باشد.

 سپس، اگر استفاده و قابلیت‌های اپلیکیشن شما با گذر زمان افزایش یابد، اپلیکیشن شما به یک سیستم توزیع‌شده بزرگ تبدیل می‌شود که به مجموعه‌ای از وابستگی‌های توزیع‌شده تکیه دارد.

اما نکته مهم اینجاست! حتی در مراحل ابتدایی مانند Proof Of Concept و به‌خصوص در مرحله Frontend-Backend-Database، می‌توانید از NET Aspire. استفاده کنید. با چند خط کد ساده و بدون تغییرات پیچیده در CI یا فرآیند استقرار، می‌توانید کار توسعه‌دهنده‌ها را خیلی ساده‌تر کنید و تجربه روزانه آن‌ها را بهبود بخشید.

گام ۱: فعال کردن ویژگی‌های NET. که به دلیل مشغله زیاد، هنوز با ServiceDefaults روشن نکرده‌ایم.

تیم ASP.NET Core سال‌هاست که ویژگی‌های کاربردی مثل tracing، health checks و resiliency را توسعه داده است. من چندین کنفرانس با موضوع "The One Hour ASP.NET Makeover" برگزار کرده‌ام که در آن‌ها این ویژگی‌های مفید را که سال‌هاست وجود دارند، فعال و پیکربندی می‌کنیم. اما موضوع اینجاست که... برای انجام این کار در یک سخنرانی یک ساعته، بعد از خواندن مستندات و تمرین، به زمان زیادی نیاز است! حالا تصور کنید اگر می‌توانستید به‌جای این همه کار، فقط یک کلید "Enable Pro Mode" را روشن کنید، چقدر کار راحت‌تر می‌شد.
Service Defaults دقیقاً همین کار را برای شما انجام می‌دهد. شما فقط کافیست Service Defaults را فعال کنید و به‌طور خودکار از ویژگی‌هایی مثل smart logging، health checks، resiliency و غیره بر اساس توصیه‌های تیم NET. برای اپلیکیشن‌ها و سرویس‌های ASP.NET Core بهره‌مند شوید. اگر خواستید، می‌توانید به‌راحتی فایل Program.cs را در پروژه ServiceDefaults ویرایش کنید، اما اصلاً نیازی به این کار نیست. فقط آن را روشن کنید و از قابلیت‌های آن بهره ببرید.

اضافه کردن یک پروژه ServiceDefaults
 

بیایید با یک مثال از یک اپلیکیشن ساده Frontend – Backend این کار را انجام دهیم. من از نمونه جدید MyWeatherHub از سری رویدادهای Let's Learn .NET Aspire که توسط Jeff Fritz ارائه شده، استفاده می‌کنم و با کد start-with-api  شروع می‌کنم.
با باز کردن سولوشن، خواهیم دید که دو پروژه داریم:
‌    MyWeatherHub – پروژه وب frontend که داده‌های زنده هواشناسی را نمایش می‌دهد.
•    API – پروژه Minimal API که داده‌های زنده هواشناسی را از سرویس ملی هواشناسی آمریکا از طریق مجموعه‌ای از HTTP API endpointها استخراج می‌کند.
بیایید Service Defaults را به این سولوشن اضافه کنیم تا از health checks، logging، و سایر ویژگی‌های پیشنهادی برای هر دو بخش front و back بهره‌مند شویم.
در Visual Studio 2022 یا Visual Studio Code با C# Dev Kit نصب شده، کافیست مراحل زیر را انجام دهیم:
1.    روی سولوشن راست‌کلیک کرده و Add > New Project را انتخاب کنید.
2.    قالب پروژه .NET Aspire Service Defaults را انتخاب کنید.
3.    نام پروژه را  ServiceDefaults  قرار دهید.البته  هر نام دیگری هم می‌تواند انتخاب شود، اما در این پست فرض می‌کنیم که از نام ServiceDefaults استفاده می‌کنید .
4.    روی Next و سپس Create کلیک کنید.
اینجا نحوه انجام این کار در Visual Studio 2022 آمده است:
 

و در Visual Studio Code، به این صورت دیده می‌شود:

همچنین می‌توانید Service Defaults را از طریق خط فرمان با استفاده از دستور زیر اضافه کنید:

dotnet new aspire-servicedefaults -n ServiceDefaults

تمام روش های بالا یک پروژه جدید به سولوشن شما اضافه می‌کنند که بهترین تنظیمات را برای اکثر اپلیکیشن‌های توزیع‌شده ASP.NET Core در نظر دارد. با این حال، هنوز هیچ‌یک از اپلیکیشن‌های موجود شما از این تنظیمات استفاده نمی‌کنند. در مرحله بعدی، این ویژگی‌ها را به اپلیکیشن‌های خود متصل می‌کنیم.

پیکربندی Service Defaults
 

یک reference به پروژه ServiceDefaults در پروژه‌های Api و MyWeatherHub اضافه کنید:
1.    روی پروژه Api راست‌کلیک کرده و Add > Reference را انتخاب کنید.
2.    پروژه ServiceDefaults را انتخاب کنید و روی OK کلیک کنید.
3.    روی پروژه MyWeatherHub راست‌کلیک کرده و Add > Reference را انتخاب کنید.
4.    پروژه ServiceDefaults را انتخاب کنید و روی OK کلیک کنید.
نکته‌ای برای Visual Studio 2022: در Visual Studio 2022، می‌توانید پروژه را بکشید و روی پروژه دیگری رها کنید تا یک reference اضافه شود.
5.    در هر دو پروژه Api و MyWeatherHub، فایل Program.cs آن‌ها را به‌روزرسانی کرده و خط زیر را بلافاصله بعد از خط var builder = WebApplication.CreateBuilder(args); اضافه کنید:
 

 builder.AddServiceDefaults();

6.    در هر دو پروژه Api و MyWeatherHub، فایل Program.cs آن‌ها را به‌روزرسانی کرده و خط زیر را بلافاصله بعد از خط var app = builder.Build(); اضافه کنید:
 

app.MapDefaultEndpoints();

اجرای اپلیکیشن

برای شروع، می‌خواهیم اپلیکیشن را با استفاده از تنظیمات multiple-project launch configuration اجرا کنیم. این روش مشکلی ندارد؛ ما سال‌هاست که از آن استفاده می‌کنیم، اما باید بگویم واقعاً طرفدارش نیستم. به خاطر داشته باشید که در مرحله بعدی این فرآیند را ساده‌تر خواهیم کرد. این کار را در دو مرحله انجام می‌دهیم تا مشخص شود چه بخش‌هایی از Service Defaults و چه قسمت‌هایی توسط AppHost اضافه می‌شوند.
اگر از Visual Studio 2022 استفاده می‌کنید، روی MyWeatherHub solution راست‌کلیک کرده و به properties بروید. سپس، Api و MyWeatherHub را به‌عنوان پروژه‌های شروع (startup projects) انتخاب کنید و روی OK کلیک کنید.
 

Visual Studio دیالوگی برای تنظیم چندین پروژه به‌عنوان پروژه‌های شروع
اکنون روی Start کلیک کنید تا هر دو پروژه شروع و دیباگ شوند.

اگر از Visual Studio Code استفاده می‌کنید، پروژه‌های Api و MyWeatherHub را با استفاده از پنل Run and Debug اجرا کنید. پروژه نمونه قبلاً شامل یک فایل launch.json با تنظیمات لازم برای اجرای هر دو پروژه است.

تست تغییرات Service Defaults

1.    اپلیکیشن را با مرور به آدرس‌های زیر تست کنید:
 

•    https://localhost:7032/swagger/index.html – API
•    https://localhost:7274/ – MyWeatherHub
2.    شما باید Swagger UI را برای API و صفحه اصلی MyWeatherHub را مشاهده کنید.
3.    همچنین می‌توانید با آدرس https://localhost:7032/health، health checks را برای API مشاهده کنید.
4.    و می‌توانید با مرور به آدرس https://localhost:7274/health، health checks را برای MyWeatherHub مشاهده کنید.
5.    لاگ‌ها را در ترمینال بررسی کنید تا health checks و دیگر داده‌های telemetry مانند resiliency با استفاده از Polly را ببینید:
Polly: Information: Execution attempt. Source: '-standard//Standard-Retry', Operation Key: '', Result: '200', Handled: 'False', Attempt: '0', Execution Time: '13.0649'
6.    روی ۵ شهر مختلف کلیک کنید و یک خطای "تصادفی" ایجاد خواهد شد. خواهید دید که Polly retry policy در عمل اجرا می‌شود.

Polly: Warning: Execution attempt. Source: '-standard//Standard-Retry', Operation Key: '', Result: '500', Handled: 'True', Attempt: '0', Execution Time: '9732.8258'
Polly: Warning: Resilience event occurred. EventName: 'OnRetry', Source: '-standard//Standard-Retry', Operation Key: '', Result: '500'
System.Net.Http.HttpClient.NwsManager.ClientHandler: Information: Sending HTTP request GET http://localhost:5271/forecast/AKZ318

همه این‌ها به درستی کار می‌کنند... خروجی هر اپلیکیشن در یک پنجره کنسول جداگانه ظاهر می‌شود و ما می‌توانیم health checks و لاگ‌ها را در ترمینال مشاهده کنیم. بنابراین، عالی است که همه این ویژگی‌ها فعال شده‌اند، اما مدیریت همه این URLها، تب‌های مرورگر و پنجره‌های کنسول کمی دشوار است. شما مجبورید بین آن‌ها با alt-tab جا‌به‌جا شوید و این تجربه واقعاً پراکنده و گیج‌کننده است.
 

Service Defaults در سطح پروژه‌های منفرد بسیار خوب عمل می‌کند، اما در مدیریت چندین پروژه در یک سولوشن به ما کمکی نمی‌کند. اینجاست که AppHost وارد می‌شود.

گام ۲: ساده‌سازی راه‌اندازی و اضافه کردن یک داشبورد جذاب با AppHost

خب، این خیلی عالی بود! ما یک پروژه به سولوشن خود اضافه کردیم و با دو خط کد، توانستیم health checks، logging، resiliency و موارد دیگر را به دست آوریم.
اما می‌توانیم با اضافه کردن AppHost این وضعیت را حتی بهتر کنیم. پیکربندی چندین پروژه (multiple-project configuration) خوب عمل می‌کند، اما وقتی پروژه‌های دیگری را به سولوشن اضافه می‌کنیم، تنظیم و به‌روزرسانی آن کمی آزاردهنده است. وقتی پروژه‌ها را اجرا می‌کنیم، باید به چندین URL با پورت‌های مختلف سر بزنیم و هر پروژه را به‌صورت جداگانه مدیریت کنیم. برای مثال، اگر بخواهیم لاگ‌ها یا خروجی‌ها را ببینیم، باید هر پنجره کنسول مربوط به پروژه‌ها را جداگانه بررسی کنیم. این وضعیت وقتی بدتر می‌شود که APIها و سرویس‌های بیشتری به سولوشن اضافه کنیم – URLهای بیشتری برای مدیریت، پنجره‌های کنسول بیشتری برای بررسی و غیره. شاید در محیط production داشبوردها و ابزارهای نظارتی پیشرفته‌ای داشته باشیم، اما این‌ها به هنگام توسعه به من کمکی نمی‌کنند.
AppHost دارای ویژگی‌های زیادی است، اما دو مورد از بهترین ویژگی‌های آن راه‌حل‌هایی برای مشکلات بالا هستند: این ابزار راه‌اندازی پروژه را ساده می‌کند و یک داشبورد فوق‌العاده برای نظارت و مدیریت اپلیکیشن در محیط توسعه فراهم می‌آورد. بهترین راه برای درک کاری که AppHost انجام می‌دهد این است که آن را به سولوشن خود اضافه کنیم.

اضافه کردن یک پروژه AppHost 

این مراحل استاندارد "اضافه کردن پروژه" است که قبلاً با ServiceDefaults انجام دادیم، اما این بار قصد داریم قالب پروژه .NET Aspire App Host را انتخاب کنیم. در Visual Studio 2022 یا Visual Studio Code با C# DevKit نصب شده:
1.    روی سولوشن راست‌کلیک کرده و Add > New Project را انتخاب کنید.
2.    قالب پروژه .NET Aspire App Host را انتخاب کنید.
3.    پروژه را AppHost نام‌گذاری کنید (هر نام دیگری هم می‌تواند استفاده شود).
4.    روی Next و سپس Create کلیک کنید.

و از طریق خط فرمان، می‌توانید این کار را با دستور زیر انجام دهید:

dotnet new aspire-apphost -n AppHost

همان‌طور که هنگام اضافه کردن Service Defaults انجام دادیم، باید referenceهای پروژه و چند خط کد اضافه کنیم تا AppHost به‌درستی کار کند.

اضافه کردن project references
 

یک reference به پروژه‌های Api و MyWeatherHub در پروژه جدید AppHost اضافه کنید:

1.    روی پروژه AppHost راست‌کلیک کرده و Add > Reference را انتخاب کنید.
2.    پروژه‌های Api و MyWeatherHub را انتخاب کرده و روی OK کلیک کنید.
توجه: امتیاز اضافی اگر به یاد داشته باشید که می‌توانید پروژه را بکشید و روی پروژه دیگری رها کنید تا یک reference اضافه شود.
وقتی این referenceها اضافه شدند، Source Generators به‌طور خودکار کد لازم برای ارجاع به پروژه‌ها در App Host را تولید می‌کنند.

هماهنگی اپلیکیشن

در پروژه AppHost، فایل Program.cs را به‌روزرسانی کنید و خط‌های زیر را بلافاصله بعد از خط var builder = DistributedApplication.CreateBuilder(args); اضافه کنید:

var api = builder.AddProject<Projects.Api>("api");
var web = builder.AddProject<Projects.MyWeatherHub>("myweatherhub");

اجرای اپلیکیشن… به روش آسان!

قبلاً، ما یک پروفایل راه‌اندازی چندپروژه‌ای تنظیم کرده بودیم. این هنوز هم کار می‌کند، اما از این به بعد نیازی به دغدغه این موضوع ندارید. به جای آن، پروژه AppHost را به عنوان پروژه شروع تنظیم کنید. AppHost از تمام پروژه‌های دیگر مطلع است و آن‌ها را به‌طور خودکار راه‌اندازی می‌کند. این بدان معناست که اگر یک AppHost را در ابتدا اضافه کنید (یا از قالب NET. Aspire Starter Application یا .NET Aspire Application استفاده کنید)، دیگر نیازی به تنظیم پروفایل راه‌اندازی چندپروژه‌ای ندارید. و حتی بهتر، اگر سرویس‌های بیشتری به سولوشن خود اضافه کنید، AppHost آن‌ها را به‌طور خودکار شناسایی خواهد کرد.
در Visual Studio، می‌توانید پروژه AppHost را به عنوان پروژه شروع تنظیم کنید؛ با راست‌کلیک بر روی AppHost و انتخاب Set Default Project و سپس کلیک بر روی Start.
اگر از Visual Studio Code استفاده می‌کنید، محتوای فایل launch.json خود را با موارد زیر جایگزین کنید و سپس در پنل Run and Debug روی Run کلیک کنید:
 

{
        "version": "0.2.0",
        "configurations": [
                    {
                "name": "Run AppHost",
                "type": "dotnet",
                "request": "launch",
                "projectPath": "${workspaceFolder}\\AppHost\\AppHost.csproj"
            }
        ]
    }

هی، ما یک داشبورد داریم!

یادته چگونه باید به چندین URL مختلف سر بزنیم تا اپلیکیشن و health checks آن را ببینیم؟ حالا، AppHost به‌طور خودکار یک داشبورد با تمام سرویس‌ها و وابستگی‌هایشان راه‌اندازی می‌کند. این داشبورد تمام health checks، traces، logs و اطلاعاتی مانند متغیرهای محیطی را در یک مکان جمع‌آوری می‌کند. و اگر سرویس‌های بیشتری به سولوشن اضافه کنیم، آن‌ها به‌طور خودکار در داشبورد نمایش داده می‌شوند. بیایید نگاهی بیندازیم.

ابتدا، بیایید نگاهی به منابع بیندازیم. این یک فهرست مفید از تمام منابع در سولوشن ما است. ما می‌توانیم پروژه‌های API و MyWeatherHub را ببینیم و وضعیت آن‌ها را در حین راه‌اندازی مشاهده کنیم. همچنین لینک‌های قابل کلیک به endpoints، logs و traces آن‌ها دریافت می‌کنیم.
پروژه ServiceDefaults که قبلاً اضافه کردیم، به‌طور خودکار tracing را برای تمام پروژه‌های ما پیکربندی می‌کند. ما می‌توانیم این موضوع را در تب Traces ببینیم. این یک راه عالی برای درک زمان‌بندی و وابستگی‌ها در اپلیکیشن ما است.

تب Metrics اطلاعات زیادی درباره اپلیکیشن ما نمایش می‌دهد، از جمله استفاده از CPU و حافظه، و تعداد درخواست‌ها و خطاها. باز هم، این همه توسط پروژه ServiceDefaults به‌طور خودکار تنظیم شده و در داشبورد AppHost نمایش داده می‌شود.

تب Structured تمام logs ساختاریافته از اپلیکیشن ما را نمایش می‌دهد. این یک راه عالی برای دیدن خطاها و اطلاعات مهم دیگر در اپلیکیشن ما است.

خلاصه

نکته اینجاست که .NET Aspire فقط برای اپلیکیشن‌های جدید یا راه‌حل‌های بزرگ سازمانی نیست. این ابزار برای شماست، همین حالا، تا اپلیکیشن‌های موجود خود را بهتر کنید. شما می‌توانید آن را به سولوشن‌های موجود خود اضافه کنید و با چند خط کد از مزایای زیادی بهره‌مند شوید. و اگر هنوز آماده استفاده از ویژگی‌های پیشرفته‌تر مانند service discovery یا containerized deployment نیستید، اشکالی ندارد. شما همچنان می‌توانید از سادگی و قابلیت اطمینانی که .NET Aspire به اپلیکیشن‌های شما می‌آورد، بهره‌مند شوید.

نظر تیم تحریریه باگتو دربارهٔ مقاله

مقاله‌ای که توسط Jon Galloway نوشته شده، به معرفی NET Aspire. می‌پردازد و توضیح می‌دهد که چگونه می‌توان این استک جدید و قدرتمند را به پروژه‌های NET. موجود اضافه کرد تا عملکرد و قابلیت‌های آن‌ها را بهبود بخشید. یکی از ویژگی‌های برجسته این مقاله، رویکرد گام‌به‌گام و ساده آن است که به توسعه‌دهندگان کمک می‌کند تا بدون پیچیدگی و با کمترین تغییرات در پروژه‌های خود، از امکانات پیشرفته NET Aspire. بهره‌مند شوند.
در واقع، NET Aspire. این امکان را فراهم می‌کند که با چند خط کد ساده، ویژگی‌های مهمی مانند health checks، logging، resiliency و داشبورد مدیریتی را به اپلیکیشن‌های فعلی خود اضافه کنید. نکته مثبت دیگر این است که حتی اگر آماده استفاده از ویژگی‌های پیشرفته‌تری مثل service discovery یا containerized deployment نیستید، می‌توانید از سادگی و قابلیت اطمینان این استک بهره‌مند شوید.
از دیدگاه تیم تحریریه باگتو، این مقاله می‌تواند برای توسعه‌دهندگانی که به دنبال بهبود و ارتقاء پروژه‌های فعلی خود هستند، بسیار مفید و کاربردی باشد. توضیحات شفاف و مثال‌های عملی ارائه‌شده، به خوانندگان این امکان را می‌دهد که به‌راحتی NET Aspire. را در پروژه‌های خود پیاده‌سازی کنند و از مزایای آن بهره‌مند شوند. به طور کلی، این مقاله یک منبع ارزشمند برای توسعه‌دهندگان NET. است که قصد دارند پروژه‌های خود را به سطح بالاتری از کارایی و مدیریت ارتقاء دهند.