فایل EntityFramework.BulkInsert.pdb را از پوشه‌ی bin برنامه حذف کنید. این فایل و اطلاعات موجود در آن، فقط بر روی سیستمی که اصل کتابخانه بر روی آن کامپایل شده معتبر است. برای مثال در این فایل ثبت شده فایل BulkInsertExtention.cs در مسیر c:\prog\lib\user12\bluk قرار دارد که فقط بر روی سیستم نویسنده‌ی اصلی این کتابخانه معتبر است. اگر شما هم نیاز به فایل pdb معتبری دارید، سورس این کتابخانه را دریافت کنید. دستی آنرا کامپایل کرده و سپس ارجاعی را به اسمبلی نهایی بدهید. اینبار به صورت خودکار فایل pdb معتبری در پوشه‌ی bin برنامه‌ی شما قرار خواهد گرفت.
در قسمت قبل، با نحوه‌ی رندر سمت سرور و روش فعالسازی قابلیت‌های تعاملی در این حالت، آشنا شدیم. از این نکات میتوان جهت ارتقاء ساختار پروژه‌های قدیمی Blazor Server به Blazor Server 8x استفاده کرد. البته همانطور که پیشتر نیز عنوان شد، در دات نت 8 دیگر خبری از قالب‌های قدیمی پروژه‌های blazor server و blazor wasm نیست و اگر دقیقا همین موارد مدنظر هستند، آنها را میتوان با تنظیم سطح رندر و میزان تعاملی که مدنظر است، شبیه سازی کرد و یا حتی هر دو را هم با هم در یک پروژه داشت.
1) به‌روز رسانی شماره نگارش دات‌نت
اولین قدم در جهت ارتقاء پروژه‌های قدیمی، تغییر شماره نگارش TargetFramework موجود در فایل csproj. به net8.0 است. پس از اینکار نیاز است تمام بسته‌های نیوگت موجود را نیز به نگارش‌های جدیدتر آنها ارتقاء دهید.
2) فعالسازی حالت SSR تعاملی سمت سرور
پایه‌ی تمام تغییرات انجام شده‌ی در Blazor 8x، قابلیت SSR است و تمام امکانات دیگر برفراز آن اجرا می‌شوند. به همین جهت پس از ارتقاء شماره نگارش دات‌نت، نیاز است SSR را فعال کنیم و برای اینکار باید به هاست ASP.NET Core بگوئیم که درخواست‌های رسیده را به کامپوننت‌های Razor هدایت کند. بنابراین، به فایل Program.cs مراجعه کرده و دو تغییر زیر را به آن اعمال کنید:
یک نمونه‌ی کامل از فایل Program.cs را در قسمت قبل مشاهده کردید و یا حتی میتوانید دستور dotnet new blazor --interactivity Server را جهت ساخت یک پروژه‌ی آزمایشی جدید بر اساس SDK دات نت 8 و ایده گیری از آن، اجرا کنید.
در اینجا ترکیب کامپوننت‌های تعاملی سمت سرور (AddInteractiveServerComponents) و رندر تعاملی سمت سرور (AddInteractiveServerRenderMode)، دقیقا همان Blazor Server قدیمی است که ما با آن آشنا هستیم.
یک نکته: اگر از قالب جدید dotnet new blazor --interactivity None استفاده کنیم، یعنی حالت تعاملی بودن آنرا به None تنظیم کنیم، کلیات ساختار پروژه‌ای را که مشاهده خواهیم کرد، با حالت تعاملی Server آن یکی است؛ فقط در تنظیمات Program.cs آن، گزینه‌های فوق را نداریم و به صورت زیر ساده شده‌است:
در این نوع برنامه‌ها نمی‌توان جزایر/قسمت‌های تعاملی Blazor Server را در صفحات و کامپوننت‌های SSR، تعریف کرد. در مورد جزایر تعاملی، در مطالب بعدی بیشتر بحث خواهیم کرد.
3) ایجاد فایل جدید App.razor
در دات نت 8، دیگر خبری از فایل آغازین Host.cshtml_ پروژه‌های Blazor Server قدیمی نیست و کدهای آن با تغییراتی، به فایل جدید App.razor منتقل شده‌اند. در این قسمت، کار هدایت درخواست‌های رسیده به کامپوننت‌های برنامه رخ می‌دهد و از این پس، صفحه‌ی ریشه‌ی برنامه خواهد بود.
در این تصویر، مقایسه‌ای را بین جریان پردازش یک درخواست رسیده در دات نت 8، با نگارش قبلی Blazor Server مشاهده میکنید. در دات نت 8، فایل Host.cshtml_ (یک Razor Page آغازین برنامه) با یک کامپوننت Razor به نام App.razor جایگزین شده‌است و فایل قدیمی App.razor این پروژه‌ها به Routes.razor، تغییر نام یافته‌است.
نمونه‌ای از فایل App.razor جدید را که در قسمت قبل نیز معرفی کردیم، در اینجا با جزئیات بیشتری بررسی میکنیم:
در این فایل جدید تغییرات زیر رخ داده‌اند:
- تمام دایرکتیوهای تعریف شده مانند page ،@addTagHelper@ و غیره حذف شده‌اند.
- base href تعریف شده اینبار فقط با یک / شروع میشود و نه با /~. این مورد خیلی مهم است! اگر به آن دقت نکنید، هیچکدام از فایل‌های استاتیک برنامه مانند فایل‌های css. و js.، بارگذاری نخواهند شد!
- پیشتر برای رندر HeadOutlet، از یک تگ‌هلپر استفاده می‌شد. این مورد در نگارش جدید با یک کامپوننت ساده جایگزین شده‌است.
- تمام component tag helperهای پیشین حذف شده‌اند و نیازی به آنها نیست.
- ارجاع پیشین فایل blazor.server.js با فایل جدید blazor.web.js جایگزین شده‌است.
یک نکته: همانطور که مشاهده میکنید، فایل App.razor یک کامپوننت است و اینبار به همراه تگ <script> نیز شده‌است. یعنی در این نگارش از Blazor میتوان اسکریپت‌ها را در کامپوننت‌ها نیز ذکر کرد؛ فقط با یک شرط! این کامپوننت حتما باید SSR باشد. اگر این تگ اسکریپتی را در یک کامپوننت تعاملی ذکر کنید، همانند قابل (و نگارش‌های پیشین Blazor) با خطا مواجه خواهید شد.
4) ایجاد فایل جدید Routes.razor و مدیریت سراسری خطاها و صفحات یافت نشده
همانطور که عنوان شد، فایل قدیمی App.razor این پروژه‌ها به Routes.razor تغییر نام یافته‌است که درج آنرا در قسمت body مشاهده میکنید. محتوای این فایل نیز به صورت زیر است:
این محتوای جدید، فاقد ذکر کامپوننت NotFound قبلی است؛ از این جهت که سیستم مسیریابی جدید Blazor 8x با ASP.NET Core 8x یکپارچه است و نیازی به این کامپوننت نیست. یعنی اگر قصد مدیریت آدرس‌های یافت نشده‌ی برنامه را دارید، باید همانند ASP.NET Core به صورت زیر در فایل Program.cs عمل کرده:
و سپس کامپوننت جدید StatusCode.razor را برای مدیریت آن به نحو زیر به برنامه اضافه کنید و بر اساس responseCode دریافتی، واکنش‌های متفاوتی را ارائه دهید:
یک نکته: اگر پروژه‌ای را بر اساس قالب dotnet new blazor --interactivity Server ایجاد کنیم، در فایل Program.cs آن، چنین تنظیمی اضافه شده‌است:
که دقیقا معادل رفتاری است که در برنامه‌های ASP.NET Core قابل مشاهده‌است. این مسیر Error/، به کامپوننت جدید Components\Pages\Error.razor نگاشت میشود. بنابراین اگر در برنامه‌های جدید Blazor Server، استثنائی رخ دهد، با استفاده از میان‌افزار ExceptionHandler فوق، کامپوننت Error.razor نمایش داده خواهد شد. باید دقت داشت که این کامپوننت ویژه، تحت هر شرایطی در حالت یک static server component رندر میشود.
سؤال: در اینجا (برنامه‌های Blazor Server) چه تفاوتی بین UseExceptionHandler و UseStatusCodePagesWithRedirects وجود دارد؟
میان‌افزار UseExceptionHandler برای مدیریت استثناءهای آغازین برنامه، پیش از تشکیل اتصال دائم SignalR وارد عمل میشود. پس از آن و تشکیل اتصال وب‌سوکت مورد نیاز، فقط از میان‌افزار UseStatusCodePagesWithRedirects استفاده میکند.
اگر علاقمند نیستید تا تمام خطاهای رسیده را همانند مثال فوق در یک صفحه مدیریت کنید، میتوانید حداقل سه فایل زیر را به برنامه اضافه کنید تا خطاهای متداول یافت نشدن آدرسی، بروز خطایی و یا عدم دسترسی را مدیریت کنند:
5) تعاملی کردن سراسری برنامه
پس از این تغییرات اگر برنامه را اجرا کنید، بر اساس روش جدید static server-side rendering کار میکند و تعاملی نیست. یعنی تمام کامپوننت‌های آن به صورت پیش‌فرض، یکبار بر روی سرور رندر شده و خروجی آنها به مرورگر کاربر ارسال می‌شوند و هیچ اتصال دائم SignalR ای برقرار نخواهد شد. برای فعالسازی سراسری قابلیت‌های تعاملی برنامه و بازگشت به حالت Blazor Server قبلی، به فایل App.razor مراجعه کرده و دو تغییر زیر را اعمال کنید تا به صورت خودکار به تمام زیرکامپوننت‌ها، یعنی کل برنامه، اعمال شود:
نکته 1: اجرای دستور زیر در دات‌نت 8، قالب پروژه‌ای را ایجاد میکند که رفتار آن همانند پروژه‌های Blazor Server نگارش‌های قبلی دات‌نت است (این مورد را در قسمت قبل بررسی کردیم)؛ یعنی همه‌جای آن به صورت پیش‌فرض، تعاملی است:
نکته 2: البته ... InteractiveServer، دقیقا همان حالت پیش‌فرض برنامه‌های Blazor Server قبلی نیست! این حالت رندر، به صورت پیش‌فرض به همراه پیش‌رندر (pre-rendering) هم هست. یعنی در این حالت، روال رویدادگردان OnInitializedAsync یک کامپوننت، دوبار فراخوانی میشود (که باید به آن دقت داشت و عدم توجه به آن می‌تواند سبب انجام دوباره‌ی کارهای سنگین آغازین یک کامپوننت شود)؛ یکبار برای پیش‌رندر صفحه به صورت یک HTML استاتیک (بدون فعال سازی هیچ قابلیت تعاملی) که برای موتورهای جستجو و بهبود SEO مفید است و بار دیگر برای فعالسازی قسمت‌های تعاملی آن، درست پس از زمانیکه اتصال SignalR صفحه، برقرار شد (البته امکان فعالسازی حالت پیش‌رندر در Blazor Server قبلی هم وجود داشت؛ ولی مانند Blazor 8x، به صورت پیش‌فرض فعال نبود). در صورت نیاز، برای سفارشی سازی و لغو آن میتوان به صورت زیر عمل کرد:
در مورد پیش‌رندر و روش مدیریت دوبار فراخوانی شدن روال رویدادگردان OnInitializedAsync یک کامپوننت در این حالت، در قسمت‌های بعدی این سری بیشتر بحث خواهد شد.
1) به‌روز رسانی شماره نگارش دات‌نت
اولین قدم در جهت ارتقاء پروژه‌های قدیمی، تغییر شماره نگارش TargetFramework موجود در فایل csproj. به net8.0 است. پس از اینکار نیاز است تمام بسته‌های نیوگت موجود را نیز به نگارش‌های جدیدتر آنها ارتقاء دهید.
2) فعالسازی حالت SSR تعاملی سمت سرور
پایه‌ی تمام تغییرات انجام شده‌ی در Blazor 8x، قابلیت SSR است و تمام امکانات دیگر برفراز آن اجرا می‌شوند. به همین جهت پس از ارتقاء شماره نگارش دات‌نت، نیاز است SSR را فعال کنیم و برای اینکار باید به هاست ASP.NET Core بگوئیم که درخواست‌های رسیده را به کامپوننت‌های Razor هدایت کند. بنابراین، به فایل Program.cs مراجعه کرده و دو تغییر زیر را به آن اعمال کنید:
// ... builder.Services.AddRazorComponents().AddInteractiveServerComponents(); // ... app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
در اینجا ترکیب کامپوننت‌های تعاملی سمت سرور (AddInteractiveServerComponents) و رندر تعاملی سمت سرور (AddInteractiveServerRenderMode)، دقیقا همان Blazor Server قدیمی است که ما با آن آشنا هستیم.
یک نکته: اگر از قالب جدید dotnet new blazor --interactivity None استفاده کنیم، یعنی حالت تعاملی بودن آنرا به None تنظیم کنیم، کلیات ساختار پروژه‌ای را که مشاهده خواهیم کرد، با حالت تعاملی Server آن یکی است؛ فقط در تنظیمات Program.cs آن، گزینه‌های فوق را نداریم و به صورت زیر ساده شده‌است:
// ... builder.Services.AddRazorComponents(); // ... app.MapRazorComponents<App>();
3) ایجاد فایل جدید App.razor
در دات نت 8، دیگر خبری از فایل آغازین Host.cshtml_ پروژه‌های Blazor Server قدیمی نیست و کدهای آن با تغییراتی، به فایل جدید App.razor منتقل شده‌اند. در این قسمت، کار هدایت درخواست‌های رسیده به کامپوننت‌های برنامه رخ می‌دهد و از این پس، صفحه‌ی ریشه‌ی برنامه خواهد بود.
در این تصویر، مقایسه‌ای را بین جریان پردازش یک درخواست رسیده در دات نت 8، با نگارش قبلی Blazor Server مشاهده میکنید. در دات نت 8، فایل Host.cshtml_ (یک Razor Page آغازین برنامه) با یک کامپوننت Razor به نام App.razor جایگزین شده‌است و فایل قدیمی App.razor این پروژه‌ها به Routes.razor، تغییر نام یافته‌است.
نمونه‌ای از فایل App.razor جدید را که در قسمت قبل نیز معرفی کردیم، در اینجا با جزئیات بیشتری بررسی میکنیم:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<base href="/" />
<link rel="stylesheet" href="bootstrap/bootstrap.min.css" />
<link rel="stylesheet" href="app.css" />
<link rel="stylesheet" href="MyApp.styles.css" />
<link rel="icon" type="image/png" href="favicon.png" />
<HeadOutlet />
</head>
<body>
<Routes />
<script src="_framework/blazor.web.js"></script>
</body>
</html> - تمام دایرکتیوهای تعریف شده مانند page ،@addTagHelper@ و غیره حذف شده‌اند.
- base href تعریف شده اینبار فقط با یک / شروع میشود و نه با /~. این مورد خیلی مهم است! اگر به آن دقت نکنید، هیچکدام از فایل‌های استاتیک برنامه مانند فایل‌های css. و js.، بارگذاری نخواهند شد!
- پیشتر برای رندر HeadOutlet، از یک تگ‌هلپر استفاده می‌شد. این مورد در نگارش جدید با یک کامپوننت ساده جایگزین شده‌است.
- تمام component tag helperهای پیشین حذف شده‌اند و نیازی به آنها نیست.
- ارجاع پیشین فایل blazor.server.js با فایل جدید blazor.web.js جایگزین شده‌است.
یک نکته: همانطور که مشاهده میکنید، فایل App.razor یک کامپوننت است و اینبار به همراه تگ <script> نیز شده‌است. یعنی در این نگارش از Blazor میتوان اسکریپت‌ها را در کامپوننت‌ها نیز ذکر کرد؛ فقط با یک شرط! این کامپوننت حتما باید SSR باشد. اگر این تگ اسکریپتی را در یک کامپوننت تعاملی ذکر کنید، همانند قابل (و نگارش‌های پیشین Blazor) با خطا مواجه خواهید شد.
4) ایجاد فایل جدید Routes.razor و مدیریت سراسری خطاها و صفحات یافت نشده
همانطور که عنوان شد، فایل قدیمی App.razor این پروژه‌ها به Routes.razor تغییر نام یافته‌است که درج آنرا در قسمت body مشاهده میکنید. محتوای این فایل نیز به صورت زیر است:
<Router AppAssembly="@typeof(Program).Assembly">
<Found Context="routeData">
<RouteView RouteData="@routeData" DefaultLayout="@typeof(Layout.MainLayout)" />
<FocusOnNavigate RouteData="@routeData" Selector="h1" />
</Found>
</Router> app.UseStatusCodePagesWithRedirects("/StatusCode/{0}"); @page "/StatusCode/{responseCode}"
<h3>StatusCode @ResponseCode</h3>
@code {
[Parameter] public string? ResponseCode { get; set; }
} یک نکته: اگر پروژه‌ای را بر اساس قالب dotnet new blazor --interactivity Server ایجاد کنیم، در فایل Program.cs آن، چنین تنظیمی اضافه شده‌است:
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error", createScopeForErrors: true);
} سؤال: در اینجا (برنامه‌های Blazor Server) چه تفاوتی بین UseExceptionHandler و UseStatusCodePagesWithRedirects وجود دارد؟
میان‌افزار UseExceptionHandler برای مدیریت استثناءهای آغازین برنامه، پیش از تشکیل اتصال دائم SignalR وارد عمل میشود. پس از آن و تشکیل اتصال وب‌سوکت مورد نیاز، فقط از میان‌افزار UseStatusCodePagesWithRedirects استفاده میکند.
اگر علاقمند نیستید تا تمام خطاهای رسیده را همانند مثال فوق در یک صفحه مدیریت کنید، میتوانید حداقل سه فایل زیر را به برنامه اضافه کنید تا خطاهای متداول یافت نشدن آدرسی، بروز خطایی و یا عدم دسترسی را مدیریت کنند:
404.razor
@page "/StatusCode/404" <PageTitle>Not found</PageTitle> <h1>Not found</h1> <p role="alert">Sorry, there's nothing at this address.</p>
500.razor
@page "/StatusCode/500" <PageTitle>Unexpected error</PageTitle> <h1>Unexpected error</h1> <p role="alert">There was an unexpected error.</p>
401.razor
@page "/StatusCode/401" <PageTitle>Not Authorized</PageTitle> <h1>Not Authorized</h1> <p role="alert">Sorry, you are not authorized to access this page.</p>
5) تعاملی کردن سراسری برنامه
پس از این تغییرات اگر برنامه را اجرا کنید، بر اساس روش جدید static server-side rendering کار میکند و تعاملی نیست. یعنی تمام کامپوننت‌های آن به صورت پیش‌فرض، یکبار بر روی سرور رندر شده و خروجی آنها به مرورگر کاربر ارسال می‌شوند و هیچ اتصال دائم SignalR ای برقرار نخواهد شد. برای فعالسازی سراسری قابلیت‌های تعاملی برنامه و بازگشت به حالت Blazor Server قبلی، به فایل App.razor مراجعه کرده و دو تغییر زیر را اعمال کنید تا به صورت خودکار به تمام زیرکامپوننت‌ها، یعنی کل برنامه، اعمال شود:
<HeadOutlet @rendermode="@InteractiveServer" /> ... <Routes @rendermode="@InteractiveServer" />
نکته 1: اجرای دستور زیر در دات‌نت 8، قالب پروژه‌ای را ایجاد میکند که رفتار آن همانند پروژه‌های Blazor Server نگارش‌های قبلی دات‌نت است (این مورد را در قسمت قبل بررسی کردیم)؛ یعنی همه‌جای آن به صورت پیش‌فرض، تعاملی است:
dotnet new blazor --interactivity Server --all-interactive
نکته 2: البته ... InteractiveServer، دقیقا همان حالت پیش‌فرض برنامه‌های Blazor Server قبلی نیست! این حالت رندر، به صورت پیش‌فرض به همراه پیش‌رندر (pre-rendering) هم هست. یعنی در این حالت، روال رویدادگردان OnInitializedAsync یک کامپوننت، دوبار فراخوانی میشود (که باید به آن دقت داشت و عدم توجه به آن می‌تواند سبب انجام دوباره‌ی کارهای سنگین آغازین یک کامپوننت شود)؛ یکبار برای پیش‌رندر صفحه به صورت یک HTML استاتیک (بدون فعال سازی هیچ قابلیت تعاملی) که برای موتورهای جستجو و بهبود SEO مفید است و بار دیگر برای فعالسازی قسمت‌های تعاملی آن، درست پس از زمانیکه اتصال SignalR صفحه، برقرار شد (البته امکان فعالسازی حالت پیش‌رندر در Blazor Server قبلی هم وجود داشت؛ ولی مانند Blazor 8x، به صورت پیش‌فرض فعال نبود). در صورت نیاز، برای سفارشی سازی و لغو آن میتوان به صورت زیر عمل کرد:
@rendermode InteractiveServerRenderModeWithoutPrerendering
@code{
static readonly IComponentRenderMode InteractiveServerRenderModeWithoutPrerendering =
new InteractiveServerRenderMode(false);
} در مورد پیش‌رندر و روش مدیریت دوبار فراخوانی شدن روال رویدادگردان OnInitializedAsync یک کامپوننت در این حالت، در قسمت‌های بعدی این سری بیشتر بحث خواهد شد.
فرض کنید میخواهیم اطلاعات یک وب سرویس را داخل یک متغیر در package ریخته و پس از مقدار دهی ، مقدار آن متغیر آن را مشاهده کنیم . (برای اطلاع از کار با وب سرویس به اینجا مراجعه کنید ) .
برای این کار روی کنترل کلیک سمت راست کرده و گزینه Edit Breakpoints را انتخاب میکنیم :
در پنجره Set Breakpoints گزینه هایی که میخواهیم در آنها break انجام شود را انتخاب میکنیم . لازم به ذکر است که این موارد بسته به کنترل‌های مختلف تا حدود کمی با هم فرق می‌کنند
پس از انتخاب گزینه یا گزینه‌های مورد نظر و بستن پنجره یک آیکون کنار کنترل نمایش داده میشود .
اکنون میتوانید با باز کردن پنجره watch پس از آغاز شدن debug به مشاهده مقادیر مورد نظر بپردازید . در پنجره watch میتوانید نام متغیر را وارد کنید تا برای شما نمایش داده شود.
برای این کار روی کنترل کلیک سمت راست کرده و گزینه Edit Breakpoints را انتخاب میکنیم :
در پنجره Set Breakpoints گزینه هایی که میخواهیم در آنها break انجام شود را انتخاب میکنیم . لازم به ذکر است که این موارد بسته به کنترل‌های مختلف تا حدود کمی با هم فرق می‌کنند
پس از انتخاب گزینه یا گزینه‌های مورد نظر و بستن پنجره یک آیکون کنار کنترل نمایش داده میشود .
اکنون میتوانید با باز کردن پنجره watch پس از آغاز شدن debug به مشاهده مقادیر مورد نظر بپردازید . در پنجره watch میتوانید نام متغیر را وارد کنید تا برای شما نمایش داده شود.
کلاس PersianDateTime جایگزینی است برای System.DateTime برای استفاده در پروژه‌هایی که احتیاج به تاریخ شمسی و ساعت رسمی ایران یا سایر کشورهای فارسی‌زبان، مستقل از Time Zone سیستم و در نظر گرفتن Daylight Saving Time، دارند. این کلاس شامل اکثر متدها، پراپرتی‌ها و عملگرهای متداول System.DateTime است.
برای استفاده از PersianDateTime میتوانید آنرا از NuGet دریافت کنید :
برای استفاده از PersianDateTime میتوانید آنرا از NuGet دریافت کنید :
PM> Install-Package PersianDateTime
PersianDatePicker یک DatePicker شمسی کم حجم (3.5 کیلوبایت) به زبان جاوا اسکریپت برای استفاده در صفحات وب است که از تاریخ سرور استفاده میکند.
برای استفاده از PersianDatePicker میتوانید آنرا از NuGet دریافت کنید :
PM> Install-Package PersianDatePicker
برای راهنمای استفاده هم میتوانید به مطلب زیر مراجعه کنید :
PersianDatePicker یک DatePicker شمسی به زبان JavaScript که از تاریخ سرور استفاده میکند
PersianDatePicker یک DatePicker شمسی به زبان JavaScript که از تاریخ سرور استفاده میکند
در مورد CPL :
- آیا به کار مشتق شده از پروژه اصلی، می‌توانم نامی دیگر بدهم؟
بله.
- آیا باید حتما کار مشتق شده سورس باز باقی بماند؟
بله. اگر کار جدیدی است و از کدهای پروژه اول تحت مجوز CPL استفاده کرده.
خیر. اگر همان کار اولیه است و فقط کامپایل شده (فقط باید ذکر کنید سورس اصلی را از کجا میشود تهیه کرد).
در هر دو حالت، حتما باید ذکر کنید که کار جدید از چه کاری مشتق شده (به عبارتی تشکر فراموش نشود!)
- آیا می‌توانم برای کار مشتق شده مجوزی جدید انتخاب کنم؟
خیر. مگر با دریافت مجوز از صاحب اصلی کار. (و زمانیکه این مورد خیر شد یعنی نمی‌تونید از اینکار در یک پروژه جدید مثلا GPL استفاده کنید، مگر با نویسنده اصلی توافق کنید)
- آیا می‌توانم کار مشتق شده را بفروشم و کسب درآمد کنم؟
بله. (این بله در تمام مجوزها با توجه به شرایط قبل باید تفسیر شود. یعنی اگر در این مورد اخیر گفته شده بله، یعنی بله اگر سورس خودت رو در اختیار بقیه هم قرار دادی، چون در این مورد خاص صراحتا این مورد خواسته شده، اما مثلا مجوز MIT چنین چیزی رو نمی‌خواد)
ماخذ: (+)
- آیا به کار مشتق شده از پروژه اصلی، می‌توانم نامی دیگر بدهم؟
بله.
- آیا باید حتما کار مشتق شده سورس باز باقی بماند؟
بله. اگر کار جدیدی است و از کدهای پروژه اول تحت مجوز CPL استفاده کرده.
خیر. اگر همان کار اولیه است و فقط کامپایل شده (فقط باید ذکر کنید سورس اصلی را از کجا میشود تهیه کرد).
در هر دو حالت، حتما باید ذکر کنید که کار جدید از چه کاری مشتق شده (به عبارتی تشکر فراموش نشود!)
- آیا می‌توانم برای کار مشتق شده مجوزی جدید انتخاب کنم؟
خیر. مگر با دریافت مجوز از صاحب اصلی کار. (و زمانیکه این مورد خیر شد یعنی نمی‌تونید از اینکار در یک پروژه جدید مثلا GPL استفاده کنید، مگر با نویسنده اصلی توافق کنید)
- آیا می‌توانم کار مشتق شده را بفروشم و کسب درآمد کنم؟
بله. (این بله در تمام مجوزها با توجه به شرایط قبل باید تفسیر شود. یعنی اگر در این مورد اخیر گفته شده بله، یعنی بله اگر سورس خودت رو در اختیار بقیه هم قرار دادی، چون در این مورد خاص صراحتا این مورد خواسته شده، اما مثلا مجوز MIT چنین چیزی رو نمی‌خواد)
ماخذ: (+)
پیشنیاز کار با C# 8.0
هرچند بسیاری از قابلیت‌های C# 8.0 در خود کامپایلر #C پیاده سازی شده‌اند، اما برای مثال قابلیتی مانند «پیاده سازی پیش‌فرض اینترفیس‌ها» نیاز به یک runtime جدید دارد که به همراه NET Core 3.0. ارائه میشود. بنابراین NET Full 4x. شاهد پیاده سازی C# 8.0 نخواهد بود. همچنین یک سری از قابلیت‌های C# 8.0 وابسته‌ی به NET Standard 2.1. و netcoreapp3.0 هستند؛ مانند نوع‌های جدید System.IAsyncDisposable و یا System.Range. به همین جهت است که برای کار با C# 8.0، حتما نیاز به نصب NET Core 3.0. نیز میباشد و به روز رسانی کامپایلر #C کافی نیست.
چه نگارش‌هایی از Visual Studio از NET Core 3.0. پشتیبانی می‌کنند؟
مطابق مستندات رسمی موجود، یک چنین جدولی در مورد نگارش‌های مختلف NET Core. و نگارش‌های ویژوال استودیوهایی از که از آنها پشتیبانی می‌کنند، وجود دارد:
بنابراین فقط VS 2019 است که قابلیت پشتیبانی از NET Core 3.0. را دارد. به همین جهت اگر قصد دارید با ویژوال استودیو کار کنید، نصب VS 2019 برای کار با C# 8.0 الزامی است.
فعالسازی C# 8.0 در ویژوال استودیو 2019
در زمان نگارش این مطلب، NET Core 3.0. در حالت پیش‌نمایش، ارائه شده‌است. به همین جهت جزء یکپارچه‌ی VS 2019 محسوب نشده و باید جداگانه نصب شود:
- برای این منظور ابتدا نیاز است آخرین نگارش NET Core 3.0 SDK. را دریافت و نصب کنید.
- سپس از منوی Tools | Options، گزینه‌ی Projects and Solutions را انتخاب و در ادامه گزینه‌ی Use previews of the .NET Core SDK را انتخاب کنید.
- پس از آن، این SDK جدید NET Core. به صورت زیر قابل انتخاب خواهد بود:
البته انتخاب شماره SDK صحیح به تنهایی برای کار با C# 8.0 کافی نیست؛ بلکه باید شماره‌ی زبان مورد استفاده را نیز صریحا انتخاب کرد:
برای اینکار بر روی پروژه کلیک راست کرده و گزینه‌ی Properties آنرا انتخاب کنید. سپس در اینجا در برگه‌ی Build، بر روی دکمه‌ی Advanced کلیک کنید تا بتوان شماره نگارش زبان را مطابق تصویر فوق انتخاب کرد. در اینجا بجای C# 8.0 (beta)، گزینه‌ی unsupported preview را نیز میتوانید انتخاب کنید.
یک نکته: خلاصه‌ی تمام این مراحل، منوها و تصاویر، همان تنظیمات فایل csproj است که در ادامه بررسی میکنیم.
فعالسازی C# 8.0 در VSCode
مدت‌ها است که برای کار با NET Core. نیازی به استفاده‌ی از نگارش کامل ویژوال استودیو نیست. همینقدر که VSCode را به همراه افزونه‌ی #C آن نصب کرده باشید، میتوانید برنامه‌های مبتنی بر NET Core. را بر روی سیستم عامل‌های مختلفی که NET Core SDK. بر روی آنها نصب شده‌است، توسعه دهید.
پشتیبانی ابتدایی از C# 8.0، با نگارش v1.18.0 افزونه‌ی #C مخصوص VSCode ارائه شد. بنابراین هم اکنون اگر آخرین نگارش آنرا نصب کرده باشید، امکان کار با پروژه‌های NET Core 3.0 و C# 8.0 را نیز دارید.
بنابراین در اینجا به صورت خلاصه:
- ابتدا باید NET Core 3.0 SDK. را به صورت جداگانه‌ای دریافت و نصب کنید.
- سپس آخرین نگارش افزونه‌ی #C مخصوص VSCode را نیز نصب کنید.
- در آخر، یک پوشه‌ی جدید را ایجاد کرده و در خط فرمان دستور dotnet new console را صادر کنید. این دستور بر اساس آخرین شماره نگارش SDK نصب شده، یک پروژه‌ی جدید کنسول را ایجاد میکند که ساختار فایل csproj آن به صورت زیر است:
همانطور که مشاهده میکنید، TargetFramework را به آخرین SDK نصب شده، تنظیم کرده‌است (معادل دومین تصویر این مطلب). مرحله‌ی بعد، تنظیم شماره نگارش زبان آن است. برای این منظور یکی از دو حالت زیر را میتوان انتخاب کرد:
- یا معادل همان گزینه‌ی unsupported preview در تصویر سوم این مطلب:
- و یا تعیین صریح شماره نگارش C# 8.0 (beta) به صورت زیر:
یک نکته: در اینجا نمی‌توان LangVersion را به latest تنظیم کرد؛ چون C# 8.0 هنوز در مرحله‌ی بتا است. زمانیکه از مرحله‌ی بتا خارج شد، مقدار پیش‌فرض آن دقیقا latest خواهد بود و ذکر صریح آن غیر ضروری است. انتخاب latest در اینجا به latest minor version یا همان نگارش C# 7.3 فعلی (آخرین نگارش پایدار زبان #C در زمان نگارش این مطلب) اشاره میکند.
Rider و پشتیبانی از C# 8.0
Rider 2019.1 نیز به همراه پشتیبانی از C# 8.0 ارائه شده‌است و می‌تواند گزینه‌ی مطلوب دیگری برای توسعه‌ی برنامه‌های مبتنی بر NET Core. باشد.
نصب NET Core 3.0 SDK. و عدم اجرای برنامه‌های پیشین
یکی از مزایای کار با NET Core.، امکان نصب چندین نوع مختلف SDK آن، به موازت هم است؛ بدون اینکه بر روی یکدیگر تاثیری بگذارند. البته این نکته را باید درنظر داشت که برنامه‌های NET Core. بدون وجود فایل مخصوص global.json در پوشه‌ی ریشه‌ی آنها، همواره از آخرین نگارش SDK نصب شده، برای اجرا استفاده خواهند کرد. اگر این مورد بر روی کار شما تاثیرگذار است، میتوانید شماره SDK مورد استفاده‌ی برنامه‌ی خود را قفل کنید، تا SDKهای جدید نصب شده، به عنوان SDK پیش‌فرض برنامه‌های پیشین، انتخاب نشوند. بنابراین ابتدا لیست SDKهای نصب شده را با دستور زیر پیدا کنید:
سپس برای پروژه‌های قدیمی خود که فعلا قصد به روز رسانی آنها را ندارید، یک فایل global.json را به صورت زیر، در ریشه‌ی پروژه تولید کنید:
در اینجا 2.2.300 یکی از شماره‌هایی است که توسط دستور dotnet --list-sdks یافته‌اید و پروژه‌ی قبلی شما بر اساس آن کار میکند.
هرچند بسیاری از قابلیت‌های C# 8.0 در خود کامپایلر #C پیاده سازی شده‌اند، اما برای مثال قابلیتی مانند «پیاده سازی پیش‌فرض اینترفیس‌ها» نیاز به یک runtime جدید دارد که به همراه NET Core 3.0. ارائه میشود. بنابراین NET Full 4x. شاهد پیاده سازی C# 8.0 نخواهد بود. همچنین یک سری از قابلیت‌های C# 8.0 وابسته‌ی به NET Standard 2.1. و netcoreapp3.0 هستند؛ مانند نوع‌های جدید System.IAsyncDisposable و یا System.Range. به همین جهت است که برای کار با C# 8.0، حتما نیاز به نصب NET Core 3.0. نیز میباشد و به روز رسانی کامپایلر #C کافی نیست.
چه نگارش‌هایی از Visual Studio از NET Core 3.0. پشتیبانی می‌کنند؟
مطابق مستندات رسمی موجود، یک چنین جدولی در مورد نگارش‌های مختلف NET Core. و نگارش‌های ویژوال استودیوهایی از که از آنها پشتیبانی می‌کنند، وجود دارد:
| .NET Core SDK | .NET Core Runtime | Compatible Visual Studio | MSBuild | Notes |
|---|---|---|---|---|
| 2.1.5nn | 2.1 | 2017 | 15 | Installed as part of VS 2017 version 15.9 |
| 2.1.6nn | 2.1 | 2019 | 16 | Installed as part of VS 2019 |
| 2.2.1nn | 2.2 | 2017 | 15 | Installed manually |
| 2.2.2nn | 2.2 | 2019 | 16 | Installed as part of VS 2019 |
| 3.0.1nn | 3.0 (Preview) | 2019 | 16 | Installed manually |
بنابراین فقط VS 2019 است که قابلیت پشتیبانی از NET Core 3.0. را دارد. به همین جهت اگر قصد دارید با ویژوال استودیو کار کنید، نصب VS 2019 برای کار با C# 8.0 الزامی است.
فعالسازی C# 8.0 در ویژوال استودیو 2019
در زمان نگارش این مطلب، NET Core 3.0. در حالت پیش‌نمایش، ارائه شده‌است. به همین جهت جزء یکپارچه‌ی VS 2019 محسوب نشده و باید جداگانه نصب شود:
- برای این منظور ابتدا نیاز است آخرین نگارش NET Core 3.0 SDK. را دریافت و نصب کنید.
- سپس از منوی Tools | Options، گزینه‌ی Projects and Solutions را انتخاب و در ادامه گزینه‌ی Use previews of the .NET Core SDK را انتخاب کنید.
- پس از آن، این SDK جدید NET Core. به صورت زیر قابل انتخاب خواهد بود:
البته انتخاب شماره SDK صحیح به تنهایی برای کار با C# 8.0 کافی نیست؛ بلکه باید شماره‌ی زبان مورد استفاده را نیز صریحا انتخاب کرد:
برای اینکار بر روی پروژه کلیک راست کرده و گزینه‌ی Properties آنرا انتخاب کنید. سپس در اینجا در برگه‌ی Build، بر روی دکمه‌ی Advanced کلیک کنید تا بتوان شماره نگارش زبان را مطابق تصویر فوق انتخاب کرد. در اینجا بجای C# 8.0 (beta)، گزینه‌ی unsupported preview را نیز میتوانید انتخاب کنید.
یک نکته: خلاصه‌ی تمام این مراحل، منوها و تصاویر، همان تنظیمات فایل csproj است که در ادامه بررسی میکنیم.
فعالسازی C# 8.0 در VSCode
مدت‌ها است که برای کار با NET Core. نیازی به استفاده‌ی از نگارش کامل ویژوال استودیو نیست. همینقدر که VSCode را به همراه افزونه‌ی #C آن نصب کرده باشید، میتوانید برنامه‌های مبتنی بر NET Core. را بر روی سیستم عامل‌های مختلفی که NET Core SDK. بر روی آنها نصب شده‌است، توسعه دهید.
پشتیبانی ابتدایی از C# 8.0، با نگارش v1.18.0 افزونه‌ی #C مخصوص VSCode ارائه شد. بنابراین هم اکنون اگر آخرین نگارش آنرا نصب کرده باشید، امکان کار با پروژه‌های NET Core 3.0 و C# 8.0 را نیز دارید.
بنابراین در اینجا به صورت خلاصه:
- ابتدا باید NET Core 3.0 SDK. را به صورت جداگانه‌ای دریافت و نصب کنید.
- سپس آخرین نگارش افزونه‌ی #C مخصوص VSCode را نیز نصب کنید.
- در آخر، یک پوشه‌ی جدید را ایجاد کرده و در خط فرمان دستور dotnet new console را صادر کنید. این دستور بر اساس آخرین شماره نگارش SDK نصب شده، یک پروژه‌ی جدید کنسول را ایجاد میکند که ساختار فایل csproj آن به صورت زیر است:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp3.0</TargetFramework>
</PropertyGroup>
</Project> - یا معادل همان گزینه‌ی unsupported preview در تصویر سوم این مطلب:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp3.0</TargetFramework>
<LangVersion>preview</LangVersion>
</PropertyGroup>
</Project> <Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp3.0</TargetFramework>
<LangVersion>8.0</LangVersion>
</PropertyGroup>
</Project> یک نکته: در اینجا نمی‌توان LangVersion را به latest تنظیم کرد؛ چون C# 8.0 هنوز در مرحله‌ی بتا است. زمانیکه از مرحله‌ی بتا خارج شد، مقدار پیش‌فرض آن دقیقا latest خواهد بود و ذکر صریح آن غیر ضروری است. انتخاب latest در اینجا به latest minor version یا همان نگارش C# 7.3 فعلی (آخرین نگارش پایدار زبان #C در زمان نگارش این مطلب) اشاره میکند.
Rider و پشتیبانی از C# 8.0
Rider 2019.1 نیز به همراه پشتیبانی از C# 8.0 ارائه شده‌است و می‌تواند گزینه‌ی مطلوب دیگری برای توسعه‌ی برنامه‌های مبتنی بر NET Core. باشد.
نصب NET Core 3.0 SDK. و عدم اجرای برنامه‌های پیشین
یکی از مزایای کار با NET Core.، امکان نصب چندین نوع مختلف SDK آن، به موازت هم است؛ بدون اینکه بر روی یکدیگر تاثیری بگذارند. البته این نکته را باید درنظر داشت که برنامه‌های NET Core. بدون وجود فایل مخصوص global.json در پوشه‌ی ریشه‌ی آنها، همواره از آخرین نگارش SDK نصب شده، برای اجرا استفاده خواهند کرد. اگر این مورد بر روی کار شما تاثیرگذار است، میتوانید شماره SDK مورد استفاده‌ی برنامه‌ی خود را قفل کنید، تا SDKهای جدید نصب شده، به عنوان SDK پیش‌فرض برنامه‌های پیشین، انتخاب نشوند. بنابراین ابتدا لیست SDKهای نصب شده را با دستور زیر پیدا کنید:
> dotnet --list-sdks
> dotnet new globaljson --sdk-version 2.2.300 > type global.json
اگر علاقمند هستید از به روز رسانی‌های بسته‌های نیوگت مورد علاقه‌ی خود مطلع شوید، میتوانید از MyGet استفاده کنید. برای این منظور پس از ثبت نام در سایت MyGet، یک فید جدید را ایجاد کنید و بسته‌های مورد علاقه‌ی خود را به آن اضافه کنید. سپس در منوی سمت چپ صفحه‌ی فید ایجاد شده، گزینه‌ی Package Sources را انتخاب کرده و بر روی دکمه‌ی Edit آن کلیک کنید. در اینجا میتوان انتخاب کرد که به روز رسانی‌های انجام شده به شما ایمیل شوند.
توسط ماژول‌ها میتوانیم یک مجموعه از دستورات را گروه‌بندی کنیم و تحت عنوان یک پکیج ارائه دهیم که برای دیگران نیز قابل استفاده باشند. برای ایجاد یک ماژول کافی است اسکریپت‌های خود را درون یک فایل با پسوند psm1 قرار دهیم؛ به این فایل اصطلاحاً root module گفته میشود. در واقع میتوان گفت ماژول‌ها یک روش مناسب برای به اشتراک‌گذاری اسکریپت‌ها میباشند. تا اینجا با کمک پروفایل‌ها توانستیم امکان استفاده مجدد از توابع و اسکریپت‌ها را داشته باشیم؛ ماژول‌ها نیز یک روش دیگر برای بارگذاری اسکریپت‌ها درون شل هستند. زمانیکه شل را باز میکنیم PowerShell به صورت خودکار یکسری مسیر را برای بارگذاری ماژول‌ها اسکن میکند. توسط متغیر env:PSModulePath$ میتوانیم لیست این مسیرها را ببینیم:
همانطور که عنوان شد برای ایجاد یک ماژول کافی است اسکریپت‌های خود را داخل یک فایل با پسوند psm1 ذخیره کنیم. به عنوان مثال میتوانیم تابع Get-PingReply را درون یک فایل با نام PingModule.psm1 ذخیره و سپس توسط دستور Import-Module ماژول را ایمپورت کنیم:
سپس توسط دستور Get-Module PingModule میتوانیم جزئیات ماژول ایمپورت شده را مشاهده نمائیم:
به صورت پیش‌فرض تمام توابع درون اسکریپت export خواهند شد. اگر ExportedCommands خالی باشد به این معنا است که ماژول به درستی ایمپورت نشده‌است. به عنوان مثال اگر سعی کنید فایل قبل را با پسوند ps1 به عنوان ماژول ایمپورت کنید. خطایی هنگام ایمپورت کردن مشاهده نخواهید کرد و قسمت ExportedCommands خالی خواهد بود. در اینحالت نیز امکان استفاده از تابع درون اسکریپت را خواهیم داشت؛ اما هیچ تضمینی نیست که به صورت یک ماژول به درستی عمل کند. بنابراین بهتر است ماژول‌هایی که ایجاد میکنیم حتماً پسوند psm1 داشته باشند.
ممکن است بخواهیم یکسری توابع را به صورت private تعریف کنیم و فقط تعداد محدودی از توابع به صورت public باشند. در این حالت میتوانیم درون فایل psm1 با کمک دستور Export-ModuleMember اینکار را انجام دهیم:
تنها پراپرتی موردنیاز برای ایجاد module manifest پراپرتی Path میباشد. این پراپرتی به فایلی که متادیتا قرار است درون آن ایجاد شود اشاره دارد. همانطور که مشاهده میکنید یکسری پراپرتی دیگر نیز اضافه کرده‌ایم و توسط splatted hash table (با کمک @) به دستور New-ModuleManifest ارسال کرده‌ایم. به این معنا که کلیدها و مقادیر درون hash table به جای اینکه یکجا به عنوان یک آبجکت به دستور موردنظر ارسال شوند، به صورت جدا پاس داده شده‌اند. اما اگر از $ استفاده میکردیم:
با خطای زیر مواجه میشدیم:
در نهایت فایل manifest در مسیر تعیین شده ایجاد خواهد شد:
هر ماژول باید یک آی‌دی منحصر به فرد داشته باشد که به صورت Guid توسط یک پراپرتی با همین نام تعیین میشود. برای هر پراپرتی درون این فایل توضیحی به صورت کامنت نوشته شده است؛ اما برای دیدن جزئیات کامل میتوانید به اینجا مراجعه نمائید. در اینجا RootModule به PingModule.psm1 تنظیم شده است. تنظیم این پراپرتی نحوه نمایش module type را در خروجی Get-Module مشخص میکند. این مقدار اگر به فایل ماژول (psm1) اشاره کند، نوع ماژول script در نظر گرفته میشود، اگر به یک DLL اشاره کند به binary و در نهایت اگر به یک فایلی با پسوند دیگری اشاره کند manifest در نظر گرفته میشود. همچنین درون فایل فوق یکسری پراپرتی مانند CmdletsToExport, VariablesToExport, AliasesToExport به صورت خودکار تنظیم شده‌اند. در نهایت برای تست صحت فایل میتوانیم از دستور Test-ModuleManifest استفاده کنیم:
در کد فوق میتوانید مقدار متغیر RepoPath را به محل مدنظر روی سیستم‌تان تنظیم کنید. ساختار ماژولی که میخواهیم پابلیش کنیم نیز اینچنین خواهد بود:
در ادامه برای پابلیش ماژول فوق درون ProjectRoot دستور Publish-Module را اینگونه اجرا خواهیم کرد:
خروجی دستور فوق یک فایل با پسوند nupkg در مسیر مخزنی است که معرفی کردیم. همچنین با کمک دستور Find-Module میتوانیم ماژول موردنظر را لیست کنیم:
برای نصب ماژول روی یک سیستم دیگر نیز ابتدا باید مطمئن شوید که سیستم مقصد، مخزن لوکال را تعریف کرده باشد و در نهایت توسط دستور Install-Module میتوانیم ماژول موردنظر را نصب کنیم:
همچنین امکان پابلیش کردن ورژن‌های متفاوت را نیز خواهیم داشت:
برای پابلیش کردن هر کدام از ماژول‌های فوق باید به ازای هر کدام یکبار دستور Publish-Module را اجرا کنیم:
اکنون حین نصب ماژول میتوانیم ورژن را نیز تعیین کنیم؛ در غیراینصورت آخرین ورژن یعنی 1.0.1 نصب خواهد شد:
در اینحالت باید اسکریپت‌ها و فایل‌های موردنیاز را توسط dot sourcing درون فایل ماژول بارگذاری کنیم:
بنابراین ساختار پروژه را اینگونه ایجاد خواهیم کرد:
برای استفاده از پکیج ذکر شده نیاز خواهد بود که Dllهای موردنیاز را نیز به عنوان وابستگی به پروژه اضافه کنیم (محتویات پوشه dependencies) سپس درون فایل ماژول (SignPdf.psm1) همانطور که عنوان شد میبایست اسکریپت‌ها درون پوشه Public را بارگذاری کنیم و همچنین درون تابعی که قرار است Export شود را نیز تعیین کرده‌ایم (Set-PDFSingature)
در ادامه درون فایل Set-PDFSignature پیاده‌سازی را انجام خواهیم داد:
روال قرار دادن یک امضاء بر روی یک فایل PDF قبلاً در سایت توضیح داده شده است. کدهای فوق در واقع معادل PowerShell همان کدهای موجود در سایت هستند و نکته خاصی ندارند. در نهایت میتوانیم ماژول تهیه شده را روی مخزن موردنظر پابلیش کنیم:
برای نصب ماژول میتوانیم از دستور Install-Module استفاده کنیم:
در نهایت برای استفاده از ماژول ایجاد شده میتوانیم اینگونه عمل کنیم:
خروجی نیز فایل امضاء شده خواهد بود:
PS /> $env:PSModulePath -Split ":" /Users/sirwanafifi/.local/share/powershell/Modules /usr/local/share/powershell/Modules /usr/local/microsoft/powershell/7/Modules
PS /> Import-Module ./PingModule.psm1
PS /> Get-Module PingModule ModuleType Version PreRelease Name ExportedCommands ---------- ------- ---------- ---- ---------------- Script 0.0 PingModule Get-PingReply
PS /> Import-Module ./PingModule.ps1 PS /> Get-Module PingModule ModuleType Version PreRelease Name ExportedCommands ---------- ------- ---------- ---- ---------------- Script 0.0 PingModule
Function Get-PingReply {
// as before
}
Function Get-PrivateFunction {
Write-Debug 'This is a private function'
}
Export-ModuleMember -Function @(
'Get-PingReply'
) اضافه کردن متادیتا به ماژول‌ها
برای هر ماژول میتوانیم با کمک module manifest یکسری متادیتا به ماژول اضافه کنیم. این متادیتا درون یک فایل با پسوند psd1 که محتویات آن در واقع یک Hashtable است ذخیره میشود. برای ایجاد فایل manifest میتوانیم از دستور New-ModuleManifest استفاده کنیم. به عنوان مثال برای ایجاد فایل manifest برای ماژول PingModule.psm1 اینگونه عمل خواهیم کرد:
$moduleSettings = @{
Path = './PingModule.psd1'
Description = 'A module to ping a remote system'
RootModule = 'PingModule.psm1'
ModuleVersion = '1.0.0'
FunctionsToExport = @(
'Get-PingReply'
)
PowerShellVersion = '5.1'
CompatiblePSEditions = @(
'Core'
'Desktop'
)
}
New-ModuleManifest @moduleSettings $moduleSettings = @{
Author = 'John Doe'
Description = 'This is a sample module'
}
New-ModuleManifest $moduleSettings New-ModuleManifest : A parameter cannot be found that matches parameter name 'Author'.
#
# Module manifest for module 'PingModule'
#
# Generated by: sirwanafifi
#
# Generated on: 01/01/2023
#
@{
# Script module or binary module file associated with this manifest.
RootModule = './PingModule.psm1'
# Version number of this module.
ModuleVersion = '1.0.0'
# Supported PSEditions
CompatiblePSEditions = 'Core', 'Desktop'
# ID used to uniquely identify this module
GUID = '3f8561fc-c004-4c8e-b2fc-4a4191504131'
# Author of this module
Author = 'sirwanafifi'
# Company or vendor of this module
CompanyName = 'Unknown'
# Copyright statement for this module
Copyright = '(c) sirwanafifi. All rights reserved.'
# Description of the functionality provided by this module
Description = 'A module to ping a remote system'
# Minimum version of the PowerShell engine required by this module
PowerShellVersion = '5.1'
# Name of the PowerShell host required by this module
# PowerShellHostName = ''
# Minimum version of the PowerShell host required by this module
# PowerShellHostVersion = ''
# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# DotNetFrameworkVersion = ''
# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# ClrVersion = ''
# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''
# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()
# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()
# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()
# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()
# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = 'Get-PingReply'
# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = '*'
# Variables to export from this module
VariablesToExport = '*'
# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = '*'
# DSC resources to export from this module
# DscResourcesToExport = @()
# List of all modules packaged with this module
# ModuleList = @()
# List of all files packaged with this module
# FileList = @()
# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{
PSData = @{
# Tags applied to this module. These help with module discovery in online galleries.
# Tags = @()
# A URL to the license for this module.
# LicenseUri = ''
# A URL to the main website for this project.
# ProjectUri = ''
# A URL to an icon representing this module.
# IconUri = ''
# ReleaseNotes of this module
# ReleaseNotes = ''
# Prerelease string of this module
# Prerelease = ''
# Flag to indicate whether the module requires explicit user acceptance for install/update/save
# RequireLicenseAcceptance = $false
# External dependent modules of this module
# ExternalModuleDependencies = @()
} # End of PSData hashtable
} # End of PrivateData hashtable
# HelpInfo URI of this module
# HelpInfoURI = ''
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''
} PS /> Test-ModuleManifest ./PingModule.psd1 ModuleType Version PreRelease Name ExportedCommands ---------- ------- ---------- ---- ---------------- Script 1.0.0 PingModule Get-PingReply
پابلیش ماژول
در نهایت توسط Publish-Module میتوانیم ماژول موردنظرمان را درون یک مخزن PowerShell پابلیش کنیم. رایج‌ترین مخزن برای انتشار پکیج‌های PowerShell یک فید نیوگت (مانند PowerShell Gallery) است. همچنین میتوانیم یک مخزن لوکال نیز برای پابلیش پکیج‌ها نیز ایجاد کنیم و خروجی نهایی را به صورت یک فایل با پسوند nupkg با دیگران به اشتراک بگذاریم. برای اینکار ابتدا نیاز است یک مخزن لوکال را به PowerShell معرفی کنیم:
PS /> Register-PSRepository -Name 'PSLocal' ` >> -SourceLocation "$(Resolve-Path $RepoPath)" ` >> -PublishLocation "$(Resolve-Path $RepoPath)" ` >> -InstallationPolicy 'Trusted'
ProjectRoot
| -- PingModule
| -- PingModule.psd1
| -- PingModule.psm1 PS /> Publish-Module -Path ./PingModule/ -Repository PSLocal
PS /> Find-Module -Name PingModule -Repository PSLocal Version Name Repository Description ------- ---- ---------- ----------- 0.0.1 PingModule PSLocal Get-PingReply is a.
PS /> Install-Module -Name PingModule -Repository PSLocal -Scope CurrentUser
ProjectRoot
| -- PingModule
| -- 1.0.0
| -- PingModule.psd1
| -- PingModule.psm1
| -- 1.0.1
| -- PingModule.psd1
| -- PingModule.psm1 PS /> Publish-Module -Path ./PingModule/1.0.0 -Repository PSLocal PS /> Publish-Module -Path ./PingModule/1.0.1 -Repository PSLocal
PS /> Install-Module -Name PingModule -Repository PSLocal -Scope CurrentUser PS /> Get-InstalledModule -Name PingModule Version Name Repository Description ------- ---- ---------- ----------- 1.0.1 PingModule PSLocal Get-PingReply is a.
ساختار مناسب برای ایجاد ماژول‌ها
برای توسعه ماژول‌های PowerShell توصیه میشود که از ساختار Multi-file layout استفاده شود به این معنا که بخش‌های مختلف پروژه به قسمت‌های کوچک‌تر و قابل‌نگهداری تقسیم شوند:
ProjectRoot
| -- PingModule
| -- 1.0.0
| -- Public/
| -- Private/
| -- PingModule.psd1
| -- PingModule.psm1 $ScriptList = Get-ChildItem -Path $PSScriptRoot/Public/*.ps1 -Filter *.ps1
foreach ($Script in $ScriptList) {
. $Script.FullName
}
$ScriptList = Get-ChildItem -Path $PSScriptRoot/Private/*.ps1 -Filter *.ps1
foreach ($Script in $ScriptList) {
. $Script.FullName
} یک مثال عملی
در ادامه میخواهیم یک ماژول تهیه کنیم که قابلیت امضاء روی PDF را با کمک کتابخانه iTextSharp.LGPLv2.Core انجام دهیم و به شکل زیر برای کاربر قابل استفاده باشد:
PS /> Set-PDFSingature -PdfToSign "./sample_invoice.pdf" -SignatureImage "./sample_signature.jpg"
ProjectRoot
| -- SignPdf
| -- 1.0.0
| -- Public/
| -- dependencies/
| -- BouncyCastle.Crypto.dll
| -- System.Drawing.Common.dll
| -- Microsoft.Win32.SystemEvents.dll
| -- iTextSharp.LGPLv2.Core.dll
| -- Set-PDFSingature.ps1
| -- SignPdf.psd1
| -- SignPdf.psm1 $ScriptList = Get-ChildItem -Path $PSScriptRoot/Public/*.ps1 -Filter *.ps1
foreach ($Script in $ScriptList) {
. $Script.FullName
}
Export-ModuleMember -Function Set-PDFSingature using namespace iTextSharp.text
using namespace iTextSharp.text.pdf
using namespace System.IO
Function Set-PDFSingature {
[CmdletBinding()]
Param(
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateScript({
if (Test-Path ([Path]::Join($(Get-Location), $_))) {
return $true
}
else {
throw "Signature image not found"
}
if ($_.EndsWith('.pdf')) {
return $true
}
else {
throw "File extension must be .pdf"
}
})]
[string]$PdfToSign,
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateScript({
if (Test-Path ([Path]::Join($(Get-Location), $_))) {
return $true
}
else {
throw "Signature image not found"
}
if ($_.EndsWith('.png') -or $_.EndsWith('.jpg')) {
return $true
}
else {
throw "File extension must be .png or .jpg"
}
})]
[string]$SignatureImage,
[Parameter(Mandatory = $false, ValueFromPipeline = $true)]
[int]$XPos = 130,
[Parameter(Mandatory = $false, ValueFromPipeline = $true)]
[int]$YPos = 50
)
Try {
Add-Type -Path "$PSScriptRoot/dependencies/*.dll"
$pdf = [PdfReader]::new("$(Get-Location)/$PdfToSign")
$fs = [FileStream]::new("$(Get-Location)/$PdfToSign-signed.pdf",
[FileMode]::Create)
$stamper = [PdfStamper]::new($pdf, $fs)
$stamper.AcroFields.AddSubstitutionFont([BaseFont]::CreateFont())
$content = $stamper.GetOverContent(1)
$width = $pdf.GetPageSize(1).Width
$image = [Image]::GetInstance("$(Get-Location)/$SignatureImage")
$image.SetAbsolutePosition($width - $XPos, $YPos)
$image.ScaleAbsolute(100, 30)
$content.AddImage($image)
$stamper.Close()
$pdf.Close()
$fs.Dispose()
}
Catch {
Write-Host "Error: $($_.Exception.Message)"
}
} PS /> Publish-Module -Path ./SignPdf/1.0.0 -Repository PSLocal
PS /> Install-Module -Name SignPdf -Repository PSLocal -Scope CurrentUser
PS /> Set-PDFSingature -PdfToSign "./sample_invoice.pdf" -SignatureImage "./sample_signature.jpg"
کدهای ماژول را میتوانید از اینجا دانلود کنید.