اشتراکها
Github اخیرا یک ادیتور سورس باز را ارائه دادهاست که نگارش ویندوزی آن نیز قابل دسترسی است.
بله. اگر به همراه یکپارچگی مداوم (CI/CD) باشند، این امکان هست. نمونهاش GitHub Actions است که از این مورد پشتیبانی میکند؛ Azure هم به همین صورت.
راهنماهای پروژهها
انتقال به GitHub
Postman یک ابزار متکی به خود چند سکویی، رایگان و فوق العادهای است جهت توسعه و آزمایش Web APIها (HTTP Restful APIs). برای دریافت آن میتوانید به این آدرس مراجعه کنید. البته پیشتر افزونهای، مخصوص کروم را نیز ارائه کرده بودند که دیگر پشتیبانی نمیشود و اگر بر روی مرورگر شما نصب است، بهتر است آنرا حذف کنید.
شروع به کار با Postman
پس از نصب و اجرای Postman، در ابتدا درخواست میکند که اکانتی را در سایت آنها ایجاد کنید. البته این مورد اختیاری است و امکان ذخیره سازی بهتر کارها را فراهم میکند. همچنین در اولین بار اجرای برنامه، یک صفحهی دیالوگ انتخاب گزینههای مختلف را نمایش میدهد که میتوانید نمایش آتی آنرا با برداشتن تیک Show this window on launch، غیرفعال کنید.
رابط کاربری Postman، از چندین قسمت تشکیل میشود:
1) Request builder
در قسمت سمت راست و بالای رابط کاربری Postman میتوان انواع و اقسام درخواستها را جهت ارسال به یک Web API، ساخت و ایجاد کرد. توسط آن میتوان HTTP method، آدرس، بدنه، هدرها و کوکیهای یک درخواست را تنظیم کرد. برای مثال در اینجا httpbin.org را وارد کرده و بر روی دکمهی send کلیک کنید:
2) قسمت نمایش Response
پس از ارسال درخواست، بلافاصله، نتیجهی نهایی را در ذیل قسمت ساخت درخواست، میتوان مشاهده کرد:
در اینجا status code بازگشتی از سرور و همچنین response body را مشاهده میکنید. به علاوه نوع خروجی را نیز HTML تشخیص دادهاست و با توجه به اینکه این درخواست، به یک وب سایت معمولی بودهاست، طبیعی میباشد.
همچنین در این خروجی، سه برگهی pretty/raw/preview نیز قابل مشاهده هستند. حالت pretty آنرا که به همراه syntax highlighting است، مشاهده میکنید. اگر حالت نمایش raw را انتخاب کنید، حالت متنی و اصل خروجی بازگشتی از سمت سرور را مشاهده خواهید کرد. برگهی preview آن، این خروجی را شبیه به یک مرورگر نمایش میدهد.
3) قسمت History
با ارسال این درخواست، در سمت چپ صفحه، تاریخچهی این عملیات نیز درج میشود:
4) رابط کاربری چند برگهای
برای ارسال یک درخواست جدید، یا میتوان مجددا یکی از گزینههای History را انتخاب کرد و آنرا ارسال نمود و یا میتوان در همان قسمت سمت راست و بالای رابط کاربری، بر روی دکمهی + کلیک و برگهی جدیدی را جهت ایجاد درخواستی جدید، باز کرد:
در اینجا درخواستی را به endpoint جدید https://httpbin.org/get ارسال کردهایم که در آن نوع پروتکل HTTPS نیز صریحا ذکر شدهاست. اگر به خروجی دریافتی از سرور دقت کنید، اینبار نوع بازگشتی را JSON تشخیص دادهاست که خروجی متداول بسیاری از HTTP Restful APIs است. در این حالت، انتخاب نوع نمایش pretty/raw/preview آنچنان تفاوتی را ایجاد نمیکند و همان حالت pretty که syntax highlighting را نیز به همراه دارد، مناسب است.
ارسال کوئری استرینگها توسط Postman
برای ارسال درخواستی به همراه کوئری استرینگها مانند https://httpbin.org/get?param1=val1¶m2=val2، میتوان به صورت زیر عمل کرد:
یا میتوان مستقیما URL فوق را وارد کرد و سپس بر روی دکمهی send کلیک نمود و یا در ذیل این قسمت، در برگهی Params نیز این کوئری استرینگها به صورت key/valueهایی ظاهر میشوند که وارد کردن آنها به این نحو سادهتر است؛ خصوصا اگر تعداد این پارامترها زیاد باشد، تغییر پارامترها و آزمایش آنها توسط این رابط کاربری گرید مانند، به سهولت قابل انجام است. همچنین جائیکه علامت check-mark را مشاهده میکنید، میتوان اشارهگر ماوس را قرار داد تا آیکن تغییر ترتیب پارامترها نیز ظاهر شود. به این ترتیب توسط drag & drop میتوان ترتیب این ردیفها را تغییر داد:
اگر نیازی به پارامتری ندارید، میتوانید با عبور اشارهگر ماوس از روی یک ردیف، علامت ضربدر حذف کلی آن ردیف را نیز مشاهده کنید و یا با برداشتن تیک هر کدام میتوان به سادگی و بسیار سریع، بجای حذف یک پارامتر، آنرا غیرفعال و یک URL جدید را تولید و آزمایش کرد که برای آزمایش دستی حالتهای مختلف یک API، صرفهجویی زمانی قابل توجهی را فراهم میکند.
ذخیره سازی عملیات انجام شده
تا اینجا اگر به رابط کاربری تولید شده دقت کنید، بالای هر برگه، یک علامت دایرهای نارنجی رنگ، قابل مشاهدهاست که به معنای عدم ذخیره سازی آن برگهاست.
در همینجا بر روی دکمهی Save کنار دکمهی Send کلیک کنید. اگر دقت کنید، دکمهی Save دیالوگ ظاهر شده غیرفعال است:
علت اینجا است که در Postman نمیتوان یک تک درخواست را به صورت مستقل ذخیره کرد. Postman درخواستها را در مجموعههای خاص خودش (collections) مدیریت میکند؛ چیزی شبیه به پوشهی bookmarks، در یک مرورگر. بنابراین در همینجا بر روی لینک Create collection کلیک کرده و برای مثال نام گروه دلخواهی را مانند httpbin وارد کنید. سپس بر روی دکمهی check-mark کنار آن کلیک نمائید تا این مجموعه ایجاد شود.
اکنون پس از ایجاد این مجموعه و انتخاب آن، دکمهی Save to httpbin در پایین صفحه ظاهر میشود.
به صورت پیشفرض، نام فیلد درخواست، در این صفحهی دیالوگ، همان آدرس درخواست است که قابلیت ویرایش را نیز دارد. بنابراین برای مثال فیلد request name را به Get request تغییر داده و سپس بر روی دکمهی Save to httpbin کلیک کنید.
نتیجهی این عملیات را در برگهی Collections سمت چپ صفحه میتوان مشاهده کرد. در این حالت اگر درخواست مدنظری را انتخاب کنید و سپس جزئیات آنرا ویرایش کنید، مجددا همان علامت دایرهای نارنجی رنگ، بالای برگهی ساخت درخواست ظاهر میشود که بیانگر حالت ذخیره نشدهی این درخواست است. اکنون اگر بر روی دکمهی Save کنار Send کلیک کنید، در همان آیتم گروه جاری انتخابی، به صورت خودکار ذخیره و بازنویسی خواهد شد.
ارسال درخواستهایی از نوع POST
برای آزمایش ارسال یک درخواست از نوع Post، مجددا بر روی دکمهی + کنار آخرین برگهی باز شده کلیک میکنیم تا یک برگهی جدید باز شود. سپس در ابتدا، نوع درخواست را از Get پیشفرض، به Post تغییر میدهیم:
در این حالت آدرس https://httpbin.org/post را وارد کرده و سپس برگهی body را که پس از انتخاب حالت Post فعال شدهاست، انتخاب میکنیم:
در اینجا برای مثال گزینهی x-www-form-urlencoded، همان حالتی است که اطلاعات را از طریق یک فرم واقع در صفحات وب به سمت سرور ارسال میکنیم. اما اگر برای مثال نیاز باشد تا اطلاعات را با فرمت JSON، به سمت Web API ای ارسال کنیم، نیاز است گزینهی raw را انتخاب کرد و سپس قالب پیشفرض آنرا که text است به JSON تغییر داد:
در اینجا برای مثال یک payload ساده را ایجاد کرده و سپس بر روی دکمهی send کلیک کنید تا به عنوان بدنهی درخواست، به سمت Web API ارسال شود:
که نتیجهی آن چنین خروجی از سمت سرور خواهد بود:
در یک قسمت آن، raw data ما مشخص است و در قسمتی دیگر، اطلاعات با فرمت JSON، به درستی تشخیص دادهاست.
در ادامه بر روی دکمهی Save این برگه کلیک کنید. در صفحهی باز شده، نام پیشفرض آنرا که آدرس درخواست است، به Post request تغییر داده، گروه httpbin را انتخاب و سپس بر روی دکمهی Save to httpbin کلیک کنید:
اکنون مجموعهی httpbin به همراه دو درخواست است:
برای آزمایش آن، تمام برگههای باز را با کلیک بر روی دکمهی ضربدر آنها ببندید. در ادامه اگر بر روی هر کدام از آیتمهای این مجموعه کلیک کنید، جزئیات آن قابل بازیابی خواهد بود.
شروع به کار با Postman
پس از نصب و اجرای Postman، در ابتدا درخواست میکند که اکانتی را در سایت آنها ایجاد کنید. البته این مورد اختیاری است و امکان ذخیره سازی بهتر کارها را فراهم میکند. همچنین در اولین بار اجرای برنامه، یک صفحهی دیالوگ انتخاب گزینههای مختلف را نمایش میدهد که میتوانید نمایش آتی آنرا با برداشتن تیک Show this window on launch، غیرفعال کنید.
رابط کاربری Postman، از چندین قسمت تشکیل میشود:
1) Request builder
در قسمت سمت راست و بالای رابط کاربری Postman میتوان انواع و اقسام درخواستها را جهت ارسال به یک Web API، ساخت و ایجاد کرد. توسط آن میتوان HTTP method، آدرس، بدنه، هدرها و کوکیهای یک درخواست را تنظیم کرد. برای مثال در اینجا httpbin.org را وارد کرده و بر روی دکمهی send کلیک کنید:
2) قسمت نمایش Response
پس از ارسال درخواست، بلافاصله، نتیجهی نهایی را در ذیل قسمت ساخت درخواست، میتوان مشاهده کرد:
در اینجا status code بازگشتی از سرور و همچنین response body را مشاهده میکنید. به علاوه نوع خروجی را نیز HTML تشخیص دادهاست و با توجه به اینکه این درخواست، به یک وب سایت معمولی بودهاست، طبیعی میباشد.
همچنین در این خروجی، سه برگهی pretty/raw/preview نیز قابل مشاهده هستند. حالت pretty آنرا که به همراه syntax highlighting است، مشاهده میکنید. اگر حالت نمایش raw را انتخاب کنید، حالت متنی و اصل خروجی بازگشتی از سمت سرور را مشاهده خواهید کرد. برگهی preview آن، این خروجی را شبیه به یک مرورگر نمایش میدهد.
3) قسمت History
با ارسال این درخواست، در سمت چپ صفحه، تاریخچهی این عملیات نیز درج میشود:
4) رابط کاربری چند برگهای
برای ارسال یک درخواست جدید، یا میتوان مجددا یکی از گزینههای History را انتخاب کرد و آنرا ارسال نمود و یا میتوان در همان قسمت سمت راست و بالای رابط کاربری، بر روی دکمهی + کلیک و برگهی جدیدی را جهت ایجاد درخواستی جدید، باز کرد:
در اینجا درخواستی را به endpoint جدید https://httpbin.org/get ارسال کردهایم که در آن نوع پروتکل HTTPS نیز صریحا ذکر شدهاست. اگر به خروجی دریافتی از سرور دقت کنید، اینبار نوع بازگشتی را JSON تشخیص دادهاست که خروجی متداول بسیاری از HTTP Restful APIs است. در این حالت، انتخاب نوع نمایش pretty/raw/preview آنچنان تفاوتی را ایجاد نمیکند و همان حالت pretty که syntax highlighting را نیز به همراه دارد، مناسب است.
ارسال کوئری استرینگها توسط Postman
برای ارسال درخواستی به همراه کوئری استرینگها مانند https://httpbin.org/get?param1=val1¶m2=val2، میتوان به صورت زیر عمل کرد:
یا میتوان مستقیما URL فوق را وارد کرد و سپس بر روی دکمهی send کلیک نمود و یا در ذیل این قسمت، در برگهی Params نیز این کوئری استرینگها به صورت key/valueهایی ظاهر میشوند که وارد کردن آنها به این نحو سادهتر است؛ خصوصا اگر تعداد این پارامترها زیاد باشد، تغییر پارامترها و آزمایش آنها توسط این رابط کاربری گرید مانند، به سهولت قابل انجام است. همچنین جائیکه علامت check-mark را مشاهده میکنید، میتوان اشارهگر ماوس را قرار داد تا آیکن تغییر ترتیب پارامترها نیز ظاهر شود. به این ترتیب توسط drag & drop میتوان ترتیب این ردیفها را تغییر داد:
اگر نیازی به پارامتری ندارید، میتوانید با عبور اشارهگر ماوس از روی یک ردیف، علامت ضربدر حذف کلی آن ردیف را نیز مشاهده کنید و یا با برداشتن تیک هر کدام میتوان به سادگی و بسیار سریع، بجای حذف یک پارامتر، آنرا غیرفعال و یک URL جدید را تولید و آزمایش کرد که برای آزمایش دستی حالتهای مختلف یک API، صرفهجویی زمانی قابل توجهی را فراهم میکند.
ذخیره سازی عملیات انجام شده
تا اینجا اگر به رابط کاربری تولید شده دقت کنید، بالای هر برگه، یک علامت دایرهای نارنجی رنگ، قابل مشاهدهاست که به معنای عدم ذخیره سازی آن برگهاست.
در همینجا بر روی دکمهی Save کنار دکمهی Send کلیک کنید. اگر دقت کنید، دکمهی Save دیالوگ ظاهر شده غیرفعال است:
علت اینجا است که در Postman نمیتوان یک تک درخواست را به صورت مستقل ذخیره کرد. Postman درخواستها را در مجموعههای خاص خودش (collections) مدیریت میکند؛ چیزی شبیه به پوشهی bookmarks، در یک مرورگر. بنابراین در همینجا بر روی لینک Create collection کلیک کرده و برای مثال نام گروه دلخواهی را مانند httpbin وارد کنید. سپس بر روی دکمهی check-mark کنار آن کلیک نمائید تا این مجموعه ایجاد شود.
اکنون پس از ایجاد این مجموعه و انتخاب آن، دکمهی Save to httpbin در پایین صفحه ظاهر میشود.
به صورت پیشفرض، نام فیلد درخواست، در این صفحهی دیالوگ، همان آدرس درخواست است که قابلیت ویرایش را نیز دارد. بنابراین برای مثال فیلد request name را به Get request تغییر داده و سپس بر روی دکمهی Save to httpbin کلیک کنید.
نتیجهی این عملیات را در برگهی Collections سمت چپ صفحه میتوان مشاهده کرد. در این حالت اگر درخواست مدنظری را انتخاب کنید و سپس جزئیات آنرا ویرایش کنید، مجددا همان علامت دایرهای نارنجی رنگ، بالای برگهی ساخت درخواست ظاهر میشود که بیانگر حالت ذخیره نشدهی این درخواست است. اکنون اگر بر روی دکمهی Save کنار Send کلیک کنید، در همان آیتم گروه جاری انتخابی، به صورت خودکار ذخیره و بازنویسی خواهد شد.
ارسال درخواستهایی از نوع POST
برای آزمایش ارسال یک درخواست از نوع Post، مجددا بر روی دکمهی + کنار آخرین برگهی باز شده کلیک میکنیم تا یک برگهی جدید باز شود. سپس در ابتدا، نوع درخواست را از Get پیشفرض، به Post تغییر میدهیم:
در این حالت آدرس https://httpbin.org/post را وارد کرده و سپس برگهی body را که پس از انتخاب حالت Post فعال شدهاست، انتخاب میکنیم:
در اینجا برای مثال گزینهی x-www-form-urlencoded، همان حالتی است که اطلاعات را از طریق یک فرم واقع در صفحات وب به سمت سرور ارسال میکنیم. اما اگر برای مثال نیاز باشد تا اطلاعات را با فرمت JSON، به سمت Web API ای ارسال کنیم، نیاز است گزینهی raw را انتخاب کرد و سپس قالب پیشفرض آنرا که text است به JSON تغییر داد:
در اینجا برای مثال یک payload ساده را ایجاد کرده و سپس بر روی دکمهی send کلیک کنید تا به عنوان بدنهی درخواست، به سمت Web API ارسال شود:
که نتیجهی آن چنین خروجی از سمت سرور خواهد بود:
در یک قسمت آن، raw data ما مشخص است و در قسمتی دیگر، اطلاعات با فرمت JSON، به درستی تشخیص دادهاست.
در ادامه بر روی دکمهی Save این برگه کلیک کنید. در صفحهی باز شده، نام پیشفرض آنرا که آدرس درخواست است، به Post request تغییر داده، گروه httpbin را انتخاب و سپس بر روی دکمهی Save to httpbin کلیک کنید:
اکنون مجموعهی httpbin به همراه دو درخواست است:
برای آزمایش آن، تمام برگههای باز را با کلیک بر روی دکمهی ضربدر آنها ببندید. در ادامه اگر بر روی هر کدام از آیتمهای این مجموعه کلیک کنید، جزئیات آن قابل بازیابی خواهد بود.
WPF allows you to build modern desktop applications for Windows, and part of building an application is debugging code and optimizing performance. In Alessandro Del Sole’s WPF Debugging and Performance Succinctly, you will learn how to debug a WPF application by leveraging all the powerful tools in Visual Studio, including the most recent additions that allow you to investigate the behavior of the UI at runtime. Also, you will learn how to analyze and improve an application’s performance in order to provide your customers with the best possible experience and thereby make them happy.
Table of Contents
- Debugging WPF Applications
- Stepping Through Code
- Working with Debug Windows
- Debugger Visualizers and Trace Listeners
- XAML Debugging
- Analyzing the UI Performances
- Analyzing the Application Performances
ممنون از اطلاع رسانی. در واقع متن Message اینجا صحیح نیست و باید برای مثال چیزی معادل "درخواست با موفقیت ارسال شد" باشه.
نوع درخواست رو دقت کنید. از نوع Request هست. یعنی شما الان فقط به بانک درخواست پرداخت رو ارسال کردید. بانک در جواب به شما یک شماره رجوع (ReferenceId) ارسال کرده که با این شماره بتونیم به درگاه بریم و پرداخت رو انجام بدیم.
در نتیجه طبق کامنت قبلی که دادم، شماره تراکنش (TransactionID) فقط در صورت یک پرداخت موفق به شما اختصاص داده میشه.
بازخوردهای پروژهها
عدم ارسال ایمیل در هاست
با سلام وتشکر از پروژه خوب شما
به نظرتون چرا در هاست از ارسال ایمیل جلوگیری میکنه؟
من از کدهای ایمیل شما استفاده کردم در لوکال هاست به درستی کار میکند و ایمیل ارسال میشود ولی در هاست ایمیل ارسال نمیشود و(البته پیغام ارسال شدن کد رو نیز میدهد) من از جیمیل برای ارسال ایمیل استفاده کردم و گوگل ایمیل زیر رو برام ارسال کرد
Someone recently used your password to try to sign in to your Google Account MyEmail@gmail.com. This person was using an application such as an email client or mobile device. We prevented the sign-in attempt in case this was a hijacker trying to access your account. Please review the details of the sign-in attempt: if you do not recognize this sign-in attempt, someone else might be trying to access your account. You should sign in to your account and reset your password immediately.
آیا باید در هاست تنظیمات دیگری رو نیز اعمال کنیم؟
با تشکر
بازخوردهای دوره
ارزیابی و تفسیر مدل در داده کاوی
با سلام و احترام، ضمن تشکر از Feedback ای که ارسال نمودید، حقیقتاً در ابتدای امر چنین قصدی داشتم ولی با مشورت دوستانم بر آن شدم، که مشخصاً به بیان مباحث تئوری موضوع بپردازم. از آنجا که به نظر میرسد بر خلاف رویه ماکروسافت که معمولاً مفاهیم را در مجموعههای آموزشی از مباحث پایه و مقدماتی شروع میکند و تا سطح پیشرفته؛ با جزئیات کامل به بیان موضوع میپردازد. متاسفانه در بحث داده کاوی چنین رویه ای را در پیش نگرفته و فرض را بر آن گذاشته است که خواننده با مفاهیم کلی علم داده کاوی آشناست و با این پیش فرض به بررسی الگوریتمها و نحوه استفاده از آنها میپردازد. از این رو تصمیم گرفتم بیشتر خلاصه مباحث تئوری را بیان کنم و از آنجایی که به منظور انجام عملیات داده کاوی در گام نخستین شخص داده کاو میبایست از دادههای مورد کاوش، شناخت و آگاهی کافی داشته باشد و همانطور که میدانیم، جهت اهداف آموزشی بانک اطلاعاتی Adventure Works (که حاوی اطلاعات حوزههای متفاوت در یک کمپانی میباشد) و بانک Adventure Works DW (که در واقع انبار داده حوزه فروش بانک Adventure Works است)، موجود میباشد. کلیه مثالهای موجود در Books Online که برای هر الگوریتم و زمینه کاری متناظر با آن ارائه شده است روی این بانکهای اطلاعاتی انجام میگیرد.
لینک زیر دانلود مجموعه آموزش SQL Server 2012 Tutorials - Analysis Services Data Mining میباشد. که شامل موارد زیر است:
از آنجا که با سونامی «تحصیلات تکمیلی» در کشور مواجه هستیم و بسیاری از پایان نامهها پیرامون موضوع Data Mining میباشد و همچنین مشابه بسیاری از موضوعات دیگر؛ بدون در نظر گرفتن زیر ساختها و فلسفه پیدایش موضوع و دستاوردهای آن و ... پروژههای داده کاوی نیز به صورت وارداتی به کشور و به طبع سازمانها تحمیل میشود و ... امیدوارم توانسته باشم، هم زبانان نا آشنا را تا حدی که در توان داشتم با موضوع آشنا کرده باشم. برای مطالعه منابع غیر از SQL Server کتابهای « داده کاوی کاربردی - RapidMiner » انتشارات نیاز دانش و همچنین کتاب « داده کاوی با کلمنتاین » انتشارات جهاد دانشگاهی واحد صنعتی امیر کبیر نیز به بیان موضوع میپردازد. موفق و سلامت باشید.
لینک زیر دانلود مجموعه آموزش SQL Server 2012 Tutorials - Analysis Services Data Mining میباشد. که شامل موارد زیر است:
Basic Data Mining Tutorial
Lesson 1: Preparing the Analysis Services Database
Lesson 2: Building a Targeted Mailing Structure
Lesson 3: Adding and Processing Models
Lesson 4: Exploring the Targeted Mailing Models
Lesson 5: Testing Models
Lesson 6: Creating and Working with Predictions
Intermediate Data Mining Tutorial
Lesson 1: Creating the Intermediate Data Mining Solution
Lesson 2: Building a Forecasting Scenario
Lesson 3: Building a Market Basket Scenario
Lesson 4: Building a Sequence Clustering Scenario
Lesson 5: Building Neural Network and Logistic Regression Models
Creating and Querying Data Mining Models with DMX: Tutorials
Lesson 1: Bike Buyer
Lesson 2: Market Basket
Lesson 3: Time Series Prediction
بدین ترتیب برای مخاطبان این دوره که ممکن است آشنائی با مفاهیم تئوری علم داده کاوی نداشته باشند، سعی شده است مطالب به گونه ای بیان شود که با مطالعه این مجموعه، سر نخ هایی از موضوع بدست آورند و طبیعتاً در صورت علاقه مندی به موضوع به مطالعه عمیق هر الگوریتم بپردازند.Lesson 1: Preparing the Analysis Services Database
Lesson 2: Building a Targeted Mailing Structure
Lesson 3: Adding and Processing Models
Lesson 4: Exploring the Targeted Mailing Models
Lesson 5: Testing Models
Lesson 6: Creating and Working with Predictions
Intermediate Data Mining Tutorial
Lesson 1: Creating the Intermediate Data Mining Solution
Lesson 2: Building a Forecasting Scenario
Lesson 3: Building a Market Basket Scenario
Lesson 4: Building a Sequence Clustering Scenario
Lesson 5: Building Neural Network and Logistic Regression Models
Creating and Querying Data Mining Models with DMX: Tutorials
Lesson 1: Bike Buyer
Lesson 2: Market Basket
Lesson 3: Time Series Prediction
از آنجا که با سونامی «تحصیلات تکمیلی» در کشور مواجه هستیم و بسیاری از پایان نامهها پیرامون موضوع Data Mining میباشد و همچنین مشابه بسیاری از موضوعات دیگر؛ بدون در نظر گرفتن زیر ساختها و فلسفه پیدایش موضوع و دستاوردهای آن و ... پروژههای داده کاوی نیز به صورت وارداتی به کشور و به طبع سازمانها تحمیل میشود و ... امیدوارم توانسته باشم، هم زبانان نا آشنا را تا حدی که در توان داشتم با موضوع آشنا کرده باشم. برای مطالعه منابع غیر از SQL Server کتابهای « داده کاوی کاربردی - RapidMiner » انتشارات نیاز دانش و همچنین کتاب « داده کاوی با کلمنتاین » انتشارات جهاد دانشگاهی واحد صنعتی امیر کبیر نیز به بیان موضوع میپردازد. موفق و سلامت باشید.
مطالب
مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger - قسمت سوم - تکمیل مستندات یک API با کامنتها
در قسمت قبل موفق شدیم بر اساس OpenAPI specification endpoint تنظیم شده، رابط کاربری خودکاری را توسط ابزار Swagger-UI تولید کنیم. در ادامه میخواهیم این مستندات تولید شده را غنیتر کرده و کیفیت آنرا بهبود دهیم.
استفاده از XML Comments برای بهبود کیفیت مستندات API
نوشتن توضیحات XML ای برای متدها و پارامترها در پروژههای داتنتی، روشی استاندارد و شناخته شدهاست. برای نمونه در AuthorsController، میخواهیم توضیحاتی را به اکشن متد GetAuthor آن اضافه کنیم:
در این حالت اگر برنامه را اجرا کنیم، این توضیحات XMLای هیچ تاثیری را بر روی OpenAPI specification تولیدی و در نهایت Swagger-UI تولید شدهی بر اساس آن، نخواهد داشت. برای رفع این مشکل، باید به فایل OpenAPISwaggerDoc.Web.csproj مراجعه نمود و تولید فایل XML متناظر با این توضیحات را فعال کرد:
پس از تنظیم خاصیت GenerateDocumentationFile به true، با هر بار Build برنامه، فایل xml ای مطابق نام اسمبلی برنامه، در پوشهی bin آن تشکیل خواهد شد؛ مانند فایل bin\Debug\netcoreapp2.2\OpenAPISwaggerDoc.Web.xml در این مثال.
اکنون نیاز است وجود این فایل را به تنظیمات SwaggerDoc در کلاس Startup برنامه، اعلام کنیم:
در متد IncludeXmlComments، بجای ذکر صریح نام و مسیر فایل OpenAPISwaggerDoc.Web.xml، بر اساس نام اسمبلی جاری، نام فایل XML مستندات تعیین و مقدار دهی شدهاست.
پس از این تنظیمات اگر برنامه را اجرا کنیم، در Swagger-UI حاصل، این تغییرات قابل مشاهده هستند:
افزودن توضیحات به Response
تا اینجا توضیحات پارامترها و متدها را افزودیم؛ اما response از نوع 200 آن هنوز فاقد توضیحات است:
علت را نیز در تصویر فوق مشاهده میکنید. قسمت responses در OpenAPI specification، اطلاعات خودش را از اسکیمای مدلهای مرتبط دریافت میکند. بنابراین نیاز است کلاس DTO متناظر با Author را به نحو ذیل تکمیل کنیم:
مشکل! در این حالت اگر برنامه را اجرا کنیم، خروجی این توضیحات را در قسمت schemas مشاهده نخواهیم کرد. علت اینجا است که چون اسمبلی OpenAPISwaggerDoc.Models با اسمبلی OpenAPISwaggerDoc.Web یکی نیست و آنرا از پروژهی اصلی خارج کردهایم، به همین جهت نیاز است ابتدا به فایل OpenAPISwaggerDoc.Models.csproj مراجعه و GenerateDocumentationFile آنرا فعال کرد:
سپس باید فایل xml مستندات آنرا به صورت مجزایی به تنظیمات ابتدایی برنامه معرفی نمود:
با توجه به اینکه تمام فایلهای xml تولید شده در آخر به پوشهی bin\Debug\netcoreapp2.2 کپی میشوند، فقط کافی است حلقهای را تشکیل داده و تمام آنها را یکی یکی توسط متد IncludeXmlComments به تنظیمات AddSwaggerGen اضافه کرد.
در این حالت اگر مجددا برنامه را اجرا کنیم، خروجی ذیل را در قسمت schemas مشاهده خواهیم کرد:
بهبود مستندات به کمک Data Annotations
اگر به اکشن متد UpdateAuthor در کنترلر نویسندگان دقت کنیم، چنین امضایی را دارد:
جائیکه موجودیت Author را در پروژهی OpenAPISwaggerDoc.Entities تعریف کردهایم، نام و نام خانوادگی اجباری بوده و دارای حداکثر طول 150 حرف، هستند. قصد داریم همین ویژگیها را به DTO دریافتی این متد، یعنی AuthorForUpdate نیز اعمال کنیم:
پس از افزودن ویژگیهای Required و MaxLength به این DTO، خروجی Sawgger-UI به صورت زیر بهبود پیدا میکند:
بهبود مستندات متد HttpPatch با ارائهی یک مثال
دو نگارش از اکشن متد UpdateAuthor در این مثال موجود هستند:
یکی HttpPut است
و دیگری HttpPatch:
این مورد آرام آرام در حال تبدیل شدن به یک استاندارد است؛ چون امکان Partial updates را فراهم میکند. به همین جهت نسبت به HttpPut، کارآیی بهتری را ارائه میدهد. اما چون پارامتر دریافتی آن از نوع ویژهی JsonPatchDocument است و مثال پیشفرض مستندات آن، آنچنان مفهوم نیست:
بهتر است در این حالت مثالی را به استفاده کنندگان از آن ارائه دهیم تا در حین کار با آن، به مشکل برنخورند:
در اینجا در حین کامنت نویسی، میتوان از المان remarks، برای نوشتن توضیحات اضافی مانند ارائهی یک مثال، استفاده کرد که در آن op و path معادلهای بهتری را نسبت به مستندات پیشفرض آن پیدا کردهاند. در اینجا برای ذکر خطوط جدید باید از \ استفاده کرد؛ وگرنه خروجی نهایی، در یک سطر نمایش داده میشود:
روش کنترل warningهای کامنتهای تکمیل نشده
با فعالسازی GenerateDocumentationFile در فایل csproj برنامه، کامپایلر، بلافاصله برای تمام متدها و خواص عمومی که دارای کامنت نیستند، یک warning را صادر میکند. یک روش برطرف کردن این مشکل، افزودن کامنت به تمام قسمتهای برنامه است. روش دیگر آن، تکمیل خواص کامپایلر، جهت مواجه شدن با عدم وجود کامنتها در فایل csproj برنامه است:
توضیحات:
- اگر میخواهید خودتان را مجبور به کامنت نویسی کنید، میتوانید نبود کامنتها را تبدیل به error کنید. برای این منظور خاصیت TreatWarningsAsErrors را به true تنظیم کنید. در این حالت هر کامنت نوشته نشده، به صورت یک error توسط کامپایلر گوشزد شده و برنامه کامپایل نخواهد شد.
- اگر TreatWarningsAsErrors را خاموش کردید، هنوز هم میتوانید یکسری از warningهای انتخابی را تبدیل به error کنید. برای مثال NU1605 ذکر شدهی در خاصیت WarningsAsErrors، مربوط به package downgrade detection warning است.
- اگر به warning نبود کامنتها دقت کنیم به صورت عبارات warning CS1591: Missing XML comment for publicly visible type or member شروع میشود. یعنی CS1591 مربوط به کامنتهای نوشته نشدهاست. میتوان برای صرفنظر کردن از آن، شمارهی این خطا را بدون CS، توسط خاصیت NoWarn ذکر کرد.
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: OpenAPISwaggerDoc-03.zip
در قسمت بعد، مشکل خروجی تولید response از نوع 200 را که در قسمت دوم به آن اشاره کردیم، بررسی خواهیم کرد.
استفاده از XML Comments برای بهبود کیفیت مستندات API
نوشتن توضیحات XML ای برای متدها و پارامترها در پروژههای داتنتی، روشی استاندارد و شناخته شدهاست. برای نمونه در AuthorsController، میخواهیم توضیحاتی را به اکشن متد GetAuthor آن اضافه کنیم:
/// <summary> /// Get an author by his/her id /// </summary> /// <param name="authorId">The id of the author you want to get</param> /// <returns>An ActionResult of type Author</returns> [HttpGet("{authorId}")] public async Task<ActionResult<Author>> GetAuthor(Guid authorId)
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp2.2</TargetFramework> <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>
اکنون نیاز است وجود این فایل را به تنظیمات SwaggerDoc در کلاس Startup برنامه، اعلام کنیم:
namespace OpenAPISwaggerDoc.Web { public class Startup { public void ConfigureServices(IServiceCollection services) { services.AddSwaggerGen(setupAction => { setupAction.SwaggerDoc( // ... ); var xmlCommentsFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlCommentsFullPath = Path.Combine(AppContext.BaseDirectory, xmlCommentsFile); setupAction.IncludeXmlComments(xmlCommentsFullPath); }); }
پس از این تنظیمات اگر برنامه را اجرا کنیم، در Swagger-UI حاصل، این تغییرات قابل مشاهده هستند:
افزودن توضیحات به Response
تا اینجا توضیحات پارامترها و متدها را افزودیم؛ اما response از نوع 200 آن هنوز فاقد توضیحات است:
علت را نیز در تصویر فوق مشاهده میکنید. قسمت responses در OpenAPI specification، اطلاعات خودش را از اسکیمای مدلهای مرتبط دریافت میکند. بنابراین نیاز است کلاس DTO متناظر با Author را به نحو ذیل تکمیل کنیم:
using System; namespace OpenAPISwaggerDoc.Models { /// <summary> /// An author with Id, FirstName and LastName fields /// </summary> public class Author { /// <summary> /// The id of the author /// </summary> public Guid Id { get; set; } /// <summary> /// The first name of the author /// </summary> public string FirstName { get; set; } /// <summary> /// The last name of the author /// </summary> public string LastName { get; set; } } }
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup> </Project>
namespace OpenAPISwaggerDoc.Web { public class Startup { public void ConfigureServices(IServiceCollection services) { services.AddSwaggerGen(setupAction => { setupAction.SwaggerDoc( // ... ); var xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly).ToList(); xmlFiles.ForEach(xmlFile => setupAction.IncludeXmlComments(xmlFile)); }); }
در این حالت اگر مجددا برنامه را اجرا کنیم، خروجی ذیل را در قسمت schemas مشاهده خواهیم کرد:
بهبود مستندات به کمک Data Annotations
اگر به اکشن متد UpdateAuthor در کنترلر نویسندگان دقت کنیم، چنین امضایی را دارد:
[HttpPut("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor(Guid authorId, AuthorForUpdate authorForUpdate)
using System.ComponentModel.DataAnnotations; namespace OpenAPISwaggerDoc.Models { /// <summary> /// An author for update with FirstName and LastName fields /// </summary> public class AuthorForUpdate { /// <summary> /// The first name of the author /// </summary> [Required] [MaxLength(150)] public string FirstName { get; set; } /// <summary> /// The last name of the author /// </summary> [Required] [MaxLength(150)] public string LastName { get; set; } } }
بهبود مستندات متد HttpPatch با ارائهی یک مثال
دو نگارش از اکشن متد UpdateAuthor در این مثال موجود هستند:
یکی HttpPut است
[HttpPut("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor(Guid authorId, AuthorForUpdate authorForUpdate)
[HttpPatch("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor( Guid authorId, JsonPatchDocument<AuthorForUpdate> patchDocument)
بهتر است در این حالت مثالی را به استفاده کنندگان از آن ارائه دهیم تا در حین کار با آن، به مشکل برنخورند:
/// <summary> /// Partially update an author /// </summary> /// <param name="authorId">The id of the author you want to get</param> /// <param name="patchDocument">The set of operations to apply to the author</param> /// <returns>An ActionResult of type Author</returns> /// <remarks> /// Sample request (this request updates the author's first name) \ /// PATCH /authors/id \ /// [ \ /// { \ /// "op": "replace", \ /// "path": "/firstname", \ /// "value": "new first name" \ /// } \ /// ] \ /// </remarks> [HttpPatch("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor( Guid authorId, JsonPatchDocument<AuthorForUpdate> patchDocument)
روش کنترل warningهای کامنتهای تکمیل نشده
با فعالسازی GenerateDocumentationFile در فایل csproj برنامه، کامپایلر، بلافاصله برای تمام متدها و خواص عمومی که دارای کامنت نیستند، یک warning را صادر میکند. یک روش برطرف کردن این مشکل، افزودن کامنت به تمام قسمتهای برنامه است. روش دیگر آن، تکمیل خواص کامپایلر، جهت مواجه شدن با عدم وجود کامنتها در فایل csproj برنامه است:
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp2.2</TargetFramework> <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel> <GenerateDocumentationFile>true</GenerateDocumentationFile> <TreatWarningsAsErrors>false</TreatWarningsAsErrors> <WarningsAsErrors>NU1605;</WarningsAsErrors> <NoWarn>1701;1702;1591</NoWarn> </PropertyGroup>
- اگر میخواهید خودتان را مجبور به کامنت نویسی کنید، میتوانید نبود کامنتها را تبدیل به error کنید. برای این منظور خاصیت TreatWarningsAsErrors را به true تنظیم کنید. در این حالت هر کامنت نوشته نشده، به صورت یک error توسط کامپایلر گوشزد شده و برنامه کامپایل نخواهد شد.
- اگر TreatWarningsAsErrors را خاموش کردید، هنوز هم میتوانید یکسری از warningهای انتخابی را تبدیل به error کنید. برای مثال NU1605 ذکر شدهی در خاصیت WarningsAsErrors، مربوط به package downgrade detection warning است.
- اگر به warning نبود کامنتها دقت کنیم به صورت عبارات warning CS1591: Missing XML comment for publicly visible type or member شروع میشود. یعنی CS1591 مربوط به کامنتهای نوشته نشدهاست. میتوان برای صرفنظر کردن از آن، شمارهی این خطا را بدون CS، توسط خاصیت NoWarn ذکر کرد.
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: OpenAPISwaggerDoc-03.zip
در قسمت بعد، مشکل خروجی تولید response از نوع 200 را که در قسمت دوم به آن اشاره کردیم، بررسی خواهیم کرد.