استفاده از multiple environmentsدر ASP.NET Core
ASP.NET Core رفتار برنامه را بر اساس محیط زمان اجرا با استفاده از یک متغیر محیطی (environment variable) پیکربندی می کند.
Environments
برای تعیین محیط زمان اجرا، ASP.NET Core از متغیرهای محیطی زیر استفاده می کند:
1- DOTNET_ENVIRONMENT
2- ASPNETCORE_ENVIRONMENT ، هنگامی که متد WebApplication.CreateBuilder فراخوانی می شود. الگوهای پیش فرض ASP.NET Core web app، WebApplication.CreateBuilder را فراخوانی می کنند. مقدار ASPNETCORE_ENVIRONMENT ،DOTNET_ENVIRONMENT را override می کند.
IHostEnvironment.EnvironmentName را می توان روی هر مقداری تنظیم کرد، اما مقادیر زیر توسط فریم ورک ارائه شده است:
1- Development: فایل launchSettings.json ، ASPNETCORE_ENVIRONMENT را روی Development در ماشین محلی تنظیم می کند.
2- Staging
3- Production: این مقدار همان مقدار پیش فرض است البته اگر DOTNET_ENVIRONMENT و ASPNETCORE_ENVIRONMENT تنظیم نشده باشند.
کد زیر:
* مشابه کد تولید شده توسط قالب های ASP.NET Core است.
* هنگامی که ASPNETCORE_ENVIRONMENT روی Development تنظیم شده است، Developer Exception Page را فعال می کند. این کار به صورت خودکار توسط متد WebApplication.CreateBuilder انجام می شود.
* هنگامی که مقدار ASPNETCORE_ENVIRONMENT چیزی غیر از Development باشد، UseExceptionHandler را فرا می خواند.
* یک نمونه IWebHostEnvironment را در ویژگی Environment از WebApplication ایجاد می کند.
Helper Tag Environment از مقدار IHostEnvironment.EnvironmentName برای گنجاندن یا حذف نشانه گذاری (markup) در element استفاده می کند:
صفحه About از کد نمونه حاوی نشانه گذاری قبلی است و مقدار IWebHostEnvironment.EnvironmentName را نشان می دهد.
در Windows و macOS، متغیرها و مقادیر Environment به حروف بزرگ و کوچک حساس نیستند. متغیرها و مقادیر محیط لینوکس به طور پیش فرض به حروف بزرگ و کوچک حساس هستند.
ایجاد EnvironmentsSample
کد نمونه استفاده شده در این مقاله بر اساس پروژه Razor Pages به نام EnvironmentsSample است.
دستورات NET CLI زیر یک برنامه وب به نام EnvironmentsSample را ایجاد و اجرا می کند:
هنگامی که برنامه اجرا می شود، خروجی مشابه مثال زیر را نمایش می دهد:
Development and launchSettings.json
محیط توسعه می تواند ویژگی هایی را فعال کند که نباید در تولید در معرض دید قرار گیرند. به عنوان مثال، تمپلت های پروژه ASP.NET Core ، Developer Exception Page را در محیط توسعه فعال می کند.
محیط برای توسعه ماشین محلی را می توان در فایل Properties\launchSettings.json پروژه تنظیم کرد. مجموعه مقادیر محیطی در launchSettings.json، مجموعه مقادیر در محیط سیستم را override می کند.
فایل launchSettings.json:
* فقط در ماشین توسعه محلی استفاده می شود.
* مستقر نیست.
* شامل تنظیمات نمایه است.
JSON زیر فایل launchSettings.json را برای یک پروژه وب ASP.NET Core با نام EnvironmentsSample ایجاد شده با ویژوال استودیو یا dotnet new نشان می دهد:
JSON قبلی شامل دو نمایه است:
EnvironmentsSample : نام نمایه نام پروژه است. به عنوان اولین نمایه لیست شده، این نمایه به طور پیش فرض استفاده می شود. کلید "commandName" دارای مقدار "Project" است، بنابراین وب سرور Kestrel راه اندازی می شود.
IIS Express : کلید "commandName" دارای مقدار "IISExpress" است، بنابراین، IISexpress سرور وب است.
می توانید نمایه راه اندازی را روی پروژه یا هر نمایه دیگری که در launchSettings.json موجود است تنظیم کنید. برای مثال در تصویر زیر با انتخاب نام پروژه وب سرور Kestrel راه اندازی می شود.
مقدار commandName می تواند سرور وب را برای راه اندازی تعیین کند. commandName می تواند یکی از موارد زیر باشد:
ISExpress: IIS Express را راه اندازی می کند.
IIS : هیچ وب سروری راه اندازی نشده است. انتظار می رود IIS در دسترس باشد.
Project : Kestrel را راه اندازی می کند.
تب Debug / General ویژگی های پروژه Visual Studio 2022، لینک رابط کاربری (UI) نمایه های اشکال زدایی باز را ارائه می دهد. این لینک یک گفتگوی Launch Profiles را باز می کند که به شما امکان می دهد تنظیمات متغیر محیطی را در فایل launchSettings.json ویرایش کنید. همچنین می توانید با انتخاب <project name> Debug Properties، گفتگوی Launch Profiles را از منوی Debug باز کنید. تغییرات ایجاد شده در نمایه های پروژه ممکن است تا زمانی که وب سرور مجدداً راه اندازی نشود، اعمال نمی شود. . Kestrel باید قبل از اینکه بتواند تغییرات ایجاد شده در محیط خود را تشخیص دهد، دوباره راه اندازی شود.
فایل launchSettings.json زیر حاوی چندین نمایه است (در دو جدول JSON 1 و JSON 2 نشان داده شده است):
نمایه ها (profiles) را می توان از روش های زیر انتخاب کرد:
* از رابط کاربری ویژوال استودیو.
* با استفاده از دستور dotnet run CLI با گزینه --launch-profile که روی نام نمایه تنظیم شده است. این رویکرد فقط از نمایه های Kestrel پشتیبانی می کند.
launchSettings.json نباید اسرار را ذخیره کند. ابزار Secret Manager می تواند برای ذخیره اسرار برای توسعه محلی استفاده شود.
هنگام استفاده از کد ویژوال استودیو، متغیرهای محیطی را می توان در فایل .vscode/launch.json تنظیم کرد. مثال زیر چندین متغیر محیطی را برای مقادیر پیکربندی Host تنظیم می کند:
فایل .vscode/launch.json فقط با Visual Studio Code استفاده می شود.
Production
محیط تولید باید برای به حداکثر رساندن امنیت، عملکرد و استحکام برنامه پیکربندی شود. برخی از تنظیمات رایج که با توسعه متفاوت است عبارتند از:
* ذخیره سازی (Caching)
* منابع سمت مشتری دسته بندی شده، کوچک شده و به طور بالقوه خدمت گرفته از یک CDN
*صفحات خطای تشخیصی (Diagnostic error pages) غیرفعال شده.
* صفحات خطای دوستانه (Friendly error pages) فعال شده.
* ثبت و نظارت بر تولید فعال شده، به عنوان مثال، استفاده از Application Insights
تنظیم محیط با ست کردن یک متغیر محیطی
تنظیم یک محیط خاص برای آزمایش با یک متغیر محیطی یا تنظیمات پلت فرم اغلب مفید است. اگر محیط تنظیم نشده باشد، به طور پیش فرض روی Production قرار می گیرد که اکثر ویژگی های اشکال زدایی را غیرفعال می کند. روش تنظیم محیط به سیستم عامل بستگی دارد.
هنگامی که هاست ساخته می شود، آخرین تنظیمات محیطی که توسط برنامه خوانده می شود، محیط برنامه را تعیین می کند. وقتی برنامه در حال اجرا است، محیط برنامه قابل تغییر نیست.
صفحه About از کد نمونه، مقدار IWebHostEnvironment.EnvironmentName را نشان می دهد.
Azure App Service
اگر DOTNET_ENVIRONMENT و ASPNETCORE_ENVIRONMENT تنظیم نشده باشند، مقدار پیش فرض Production است. App های مستقر در Azure به طور پیش فرض Production هستند.
برای تنظیم محیط در برنامه Azure App Service با استفاده از پورتال:
1- app را از صفحه App Services انتخاب کنید.
2- در گروه Settings، Configuration را انتخاب کنید.
3- در تب تنظیمات برنامه (Application settings)، تنظیمات برنامه جدید را انتخاب کنید.
4 - در پنجره تنظیمات برنامه افزودن/ویرایش (Add/Edit application setting )، ASPNETCORE_ENVIRONMENT را برای Name ارائه کنید و برای Value، محیط را ارائه دهید (مثلاً Staging).
5- اگر می خواهید هنگام تعویض اسلات های استقرار، تنظیمات محیط با اسلات فعلی باقی بماند، چکباکس Deployment slot setting را انتخاب کنید. برای اطلاعات بیشتر، به Set up staging environments in Azure App Service در اسناد Azure مراجعه کنید.
6 - برای بستن کادر گفتگوی تنظیمات برنامه افزودن/ویرایش، OK را انتخاب کنید.
7 – گزینه Save را در بالای صفحه پیکربندی (Configuration ) انتخاب کنید.
پس از افزودن، تغییر یا حذف تنظیمات برنامه در پورتال Azure، Azure App Service به طور خودکار برنامه را مجدداً راه اندازی می کند.
Windows – تنظیم متغیر محیطی را برای یک process
مقادیر محیطی در launchSettings.json مجموعه مقادیر در محیط سیستم را override می کند.
برای تنظیم ASPNETCORE_ENVIRONMENT برای session جاری زمانی که برنامه با استفاده dotnet run شروع می شود، از دستورات زیر در خط فرمان یا در PowerShell استفاده کنید:
Windows – تنظیم متغیر محیطی globally
دستورات قبلی ASPNETCORE_ENVIRONMENT را فقط برای فرآیندهای راه اندازی شده از آن پنجره فرمان تنظیم می کند.
برای تنظیم مقدار به صورت globally در ویندوز، از یکی از روش های زیر استفاده کنید:
روش اول: بخش Control Panel > System > Advanced system setting را باز کنید و مقدار ASPNETCORE_ENVIRONMENT را اضافه یا ویرایش کنید:
روش دوم: یک خط فرمان administrative را باز کنید و از دستور setx استفاده کنید یا یک خط فرمان مدیریتی PowerShell را باز کنید و از [Environment]::SetEnvironmentVariable استفاده کنید:
سوئیچ /M متغیر محیطی را در سطح سیستم تنظیم می کند. اگر سوئیچ /M استفاده نشود، متغیر محیطی برای حساب کاربری تنظیم می شود.
گزینه Machine متغیر محیطی را در سطح سیستم تنظیم می کند. اگر مقدار گزینه به User تغییر یابد، متغیر محیطی برای حساب کاربری (user account) تنظیم می شود.
هنگامی که متغیر محیطی ASPNETCORE_ENVIRONMENT به صورت سراسری (globally) تنظیم می شود، برای اجرای dotnet در هر پنجره command که پس از تنظیم مقدار باز می شود، اعمال می شود. مقادیر محیطی در launchSettings.json مقادیر تنظیم شده در محیط سیستم را override می کند.
Windows - Use web.config
برای تنظیم متغیر محیطی ASPNETCORE_ENVIRONMENT با web.config، به بخش تنظیم متغیرهای محیطی فایل web.config مراجعه کنید.
Windows - IIS deployments
ویژگی <EnvironmentName> را در publish profile (.pubxml) یا فایل پروژه قرار دهید. این روش محیط را در web.config هنگام انتشار پروژه تنظیم می کند:
برای تنظیم متغیر محیطی ASPNETCORE_ENVIRONMENT برای برنامه ای که در یک Application Pool ایزوله اجرا می شود (پشتیبانی شده در IIS 10.0 یا جدیدتر)، به بخش فرمان AppCmd.exe در Environment Variables <environmentVariables> مراجعه کنید. هنگامی که متغیر محیطی ASPNETCORE_ENVIRONMENT برای یک مجموعه برنامه (app pool) تنظیم می شود، مقدار آن یک تنظیماتی را در سطح سیستم override می کند.
هنگام میزبانی یک برنامه در IIS و افزودن یا تغییر متغیر محیطی ASPNETCORE_ENVIRONMENT، از یکی از روش های زیر استفاده کنید تا مقدار جدید توسط برنامه ها دریافت شود:
1- اجرای net stop was /y و سپس net start w3svc از خط فرمان.
2-راه اندازی مجدد سرور.
macOS
تنظیم محیط فعلی برای macOS را می توان در هنگام اجرای برنامه به صورت in-line انجام داد:
از طرف دیگر، قبل از اجرای app، محیط را با export تنظیم کنید:
متغیرهای محیطی در سطح ماشین (Machine-level) در فایل bashrc. یا bash_profile. تنظیم می شوند. فایل را با استفاده از هر ویرایشگر متنی ویرایش کنید. عبارت زیر را اضافه کنید:
Linux
برای توزیع های لینوکس، از دستور export در خط فرمان برای تنظیمات متغیر مبتنی بر session و فایل bash_profile برای تنظیمات محیط در سطح ماشین (machine-level) استفاده کنید.
تنظیم environment در کد
برای تنظیم محیط در کد، هنگام ایجاد WebApplicationBuilder از WebApplicationOptions.EnvironmentName استفاده کنید، همانطور که در مثال زیر نشان داده شده است:
برای اطلاعات بیشتر، به .NET Generic Host در ASP.NET Core مراجعه کنید.
پیکربندی با محیط (Configuration by environment)
برای بارگزاری پیکربندی با environment، به Configuration در ASP.NET Core مراجعه کنید.
پیکربندی سرویس ها و middleware با environment
از WebApplicationBuilder.Environment یا WebApplication.Environment برای افزودن مشروط سرویس ها یا میان افزار با در نظر گرفتن محیط فعلی استفاده کنید. الگوی پروژه شامل نمونه ای از کد است که فقط زمانی که محیط فعلی توسعه نیافته است میان افزار (middleware) اضافه می کند:
کد هایلایت شده محیط فعلی را در حین ساخت request pipeline بررسی می کند. برای بررسی محیط فعلی در حین پیکربندی سرویس ها، به جای app.Environment از builder.Environment استفاده کنید.