از افزونه‌ی path.js در مطلب «پیاده سازی دکمه «بیشتر» یا «اسکرول نامحدود» به کمک jQuery در ASP.NET MVC» برای بهبود کاربری صفحه بندی ای‌جکسی هم استفاده شده‌است. این کتابخانه قابلیت افزودن صفحات مرور شده را به history مرورگر دارد؛ به همراه امکان ذخیره و بازیابی شماره صفحه‌ی ای‌جکسی (یک نمونه‌ی سبک وزن مباحث مسیریابی کتابخانه‌های SPA).
این پروژه یک فایل اسکریپت بیشتر نیست. بنابراین برای کار کردن نیاز به الحاق آن به صفحه هست (مثل تمام پروژه‌های جاوا اسکریپتی). ضمنا این مطلب رو برای سؤال پرسیدن باید رعایت کنی: آناتومی یک گزارش خطای خوب . کسی نمی‌دونه این ارور می‌ده یعنی چی؟ چه خطایی می‌ده؟ کسی مونیتورت رو نمی‌تونه از راه دور ببینه. باید توضیح بدی. تشریحش کنی با کمک این ابزار: نحوه استفاده از افزونه Firebug برای دیباگ برنامه‌های ASP.NET مبتنی بر jQuery
- .* نیست. داخل پرانتر نوشتم. درستش *. است.
- اگر از متدهای توکار خود ASP.NET MVC برای تولید لینک‌ها استفاده کنید، این لینک‌ها صرفا بر مبنای اطلاعات مسیریابی تعریف شده تولید می‌شوند.
- باید به application pool برنامه مراجعه کنید.
- روی 2003 خیر. پس از آن به صورت پیش فرض وجود دارد.
- مراجعه کنید به application pool برنامه. احتمالا روی دات نت 2 است؛ بجای 4.
توضیحات بیشتر در اینجا
- یک اکشن متد ساده برای صفحه‌ی Home طراحی کنید.
- اگر از متدهای توکار خود ASP.NET MVC برای تولید لینک‌ها استفاده کنید، این لینک‌ها صرفا بر مبنای اطلاعات مسیریابی تعریف شده تولید می‌شوند.
- باید به application pool برنامه مراجعه کنید.
- روی 2003 خیر. پس از آن به صورت پیش فرض وجود دارد.
- مراجعه کنید به application pool برنامه. احتمالا روی دات نت 2 است؛ بجای 4.
توضیحات بیشتر در اینجا
- یک اکشن متد ساده برای صفحه‌ی Home طراحی کنید.
یکی از مسائلی که در هنگام کار با کنترلهای داده‌ای نظیر ListView , GridView و .. با آن روبرو هستیم مسئله صفحه بندی میباشد و در بسیاری از موارد، کل اطلاعات در هر درخواست، بارگذاری میشود. در حالیکه روش بهینه به این صورت است که با توجه به PageSize و Index رکورد، میتوان تعداد رکورد مورد نظر در همان صفحه را بارگذاری کرد، نه کل رکوردها را.
در این مثال که از Ef Code First و الگوی Unit Of Work استفاده کرده ام ، قصد نمایش اطلاعات در یک ListView و صفحه بندی آن را بصورت chunk chunk دارم.
برای آشنایی بیشتر با الگوی Unit Of Work میتوانید به مقاله UOW در همین سایت مراجعه کنید.
ابتدا یک کنترل ListView روی صفحه ایجاد میکنیم. برای آشنایی بیشتر با این کنترل و بررسی قابلیتهای آن میتوان از این مقاله معرفی کنترلهای ListView و DataPager استفاده کنید.
سپس با توجه به الگوی Unit Of Work از یک مدل ساده استفاده میکنیم. همچنین برای بارگذاری اطلاعات به صورت صفحه به صفحه، نیاز به داشتن Index رکورد و PageSize، جهت محاسبه تعداد رکورد مورد نیاز داریم.
در کدهای بالا متد GetCustomerCount تعداد کل رکوردهایی که باید واکشی شوند را مشخص میکند. همچنین میتوان این تعداد را در cache یا viewState ذخیره کرد تا در دفعات بعدی در صورت خالی نبودن مقدار Cacheبا viewState ، نیاز به محاسبه مجدد count نداشته باشیم.
متد GetCustomer که کار اصلی را انجام میدهد از دو پارامتر استفاده میکند: StartIndex نقطه شروع و PageSize تعداد رکورد مورد نظر. در اینجا از دستورات Linq استفاده شده و دستور Skip مشخص میکند از کدام شماره رکورد به بعد شروع به واکشی نماید و دستور Take مشخص میکند که چه تعداد رکورد را واکشی نماید.
حالا به سراغ کدهای HTML می‌رویم. در آنجا علاوه بر ListView نیاز به DataPager جهت صفحه بندی و Object DataSource جهت کنترل بارگذاری اطلاعات به صورت chunk chunk داریم.
همانظور که مشاهده میکنید در DataPager ، مقدار PageSize مشخص شده است.اما Object DataSource
که فکر میکنم با توجه به متدهای تعریف شده در بالا ، تعریف Object DataSource کاملاٌ گویا میباشد.
نکته مهم:
اگر الان برنامه را اجرا کنید با خطای No parameterless constructor defined for this object ر وبرو خواهید شد که جهت حل این مشکل از کد زیر استفاده میکنیم.
در واقع نیاز است تا یک وهله از کلاس مورد نظر را به Object DataSource معرفی کنیم.
حال با اجرای برنامه و Trace آن متوجه خواهید شد که با کلیک بر روی شماره صفحه، تنها به تعداد رکوردهای همان صفحه، واکشی خواهیم داشت.
با تشکر از راهنمایی‌های آقای نصیری، امیدوارم این مقاله برای دوستان مفید باشه. منتظر نظرات دوستان هستم و اینکه چه جوری بتونیم اینکار رو با jquery ajax و به صورت سبکتر انجام بدیم.
در این مثال که از Ef Code First و الگوی Unit Of Work استفاده کرده ام ، قصد نمایش اطلاعات در یک ListView و صفحه بندی آن را بصورت chunk chunk دارم.
برای آشنایی بیشتر با الگوی Unit Of Work میتوانید به مقاله UOW در همین سایت مراجعه کنید.
ابتدا یک کنترل ListView روی صفحه ایجاد میکنیم. برای آشنایی بیشتر با این کنترل و بررسی قابلیتهای آن میتوان از این مقاله معرفی کنترلهای ListView و DataPager استفاده کنید.
سپس با توجه به الگوی Unit Of Work از یک مدل ساده استفاده میکنیم. همچنین برای بارگذاری اطلاعات به صورت صفحه به صفحه، نیاز به داشتن Index رکورد و PageSize، جهت محاسبه تعداد رکورد مورد نیاز داریم.
public class User
{
public Int64 UserId { get; set; }
public String UserName { get; set; }
}
public interface IUserService
{
int GetCustomerCount();
List<User> GetCustomers(int StartIndex, int PageSize);
}
public class ImplUserService : IUserService
{
IUnitOfWork _uow;
IDbSet<User> _user;
public ImplUserService(IUnitOfWork uow)
{
_uow = uow;
_user = uow.Set<User>();
}
public int GetCustomerCount()
{
int totalCount = _user.ToList().Count;
return totalCount;
}
public List<User> GetCustomers(int StartIndex, int PageSize)
{
return _user.OrderBy(i => i.UserId).Skip(StartIndex).Take(PageSize).ToList();
}
}
متد GetCustomer که کار اصلی را انجام میدهد از دو پارامتر استفاده میکند: StartIndex نقطه شروع و PageSize تعداد رکورد مورد نظر. در اینجا از دستورات Linq استفاده شده و دستور Skip مشخص میکند از کدام شماره رکورد به بعد شروع به واکشی نماید و دستور Take مشخص میکند که چه تعداد رکورد را واکشی نماید.
حالا به سراغ کدهای HTML می‌رویم. در آنجا علاوه بر ListView نیاز به DataPager جهت صفحه بندی و Object DataSource جهت کنترل بارگذاری اطلاعات به صورت chunk chunk داریم.
<asp:ListView ID="ListView1" runat="server" DataSourceID="ObjectDataSource1">
<ItemTemplate>
<tr style="background-color: #DCDCDC; color: #000000;">
<td>
<asp:Label ID="UserIdLabel" runat="server" Text='<%# Eval("UserId") %>' />
</td>
<td>
<asp:Label ID="UserNameLabel" runat="server" Text='<%# Eval("UserName") %>' />
</td>
</tr>
</ItemTemplate>
<LayoutTemplate>
<table runat="server">
<tr runat="server">
<td runat="server">
<table id="itemPlaceholderContainer" runat="server" border="1" style="background-color: #FFFFFF;
border-collapse: collapse; border-color: #999999; border-style: none; border-width: 1px;">
<tr runat="server" style="background-color: #DCDCDC; color: #000000;">
<th runat="server">
UserId
</th>
<th runat="server">
UserName
</th>
</tr>
<tr id="itemPlaceholder" runat="server">
</tr>
</table>
</td>
</tr>
<tr runat="server">
<td runat="server" style="text-align: center; background-color: #CCCCCC;
color: #000000;">
<asp:DataPager ID="DataPager1" runat="server" PageSize="2">
<Fields>
<asp:NextPreviousPagerField ButtonType="Button" ShowFirstPageButton="True" ShowNextPageButton="False"
ShowPreviousPageButton="False" />
<asp:NumericPagerField />
<asp:NextPreviousPagerField ButtonType="Button" ShowLastPageButton="True" ShowNextPageButton="False"
ShowPreviousPageButton="False" />
</Fields>
</asp:DataPager>
</td>
</tr>
</table>
</LayoutTemplate>
</asp:ListView>
<asp:ObjectDataSource ID="ObjectDataSource1" runat="server" EnablePaging="True" SelectCountMethod="GetCustomerCount"
SelectMethod="GetCustomers" TypeName="UserService.ImplUserService" EnableViewState="False"
MaximumRowsParameterName="PageSize" StartRowIndexParameterName="StartIndex">
نکته مهم:
اگر الان برنامه را اجرا کنید با خطای No parameterless constructor defined for this object ر وبرو خواهید شد که جهت حل این مشکل از کد زیر استفاده میکنیم.
protected void ObjectDataSource1_ObjectCreating(object sender, ObjectDataSourceEventArgs e)
{
e.ObjectInstance = ObjectFactory.GetInstance<IUserService>();
}
حال با اجرای برنامه و Trace آن متوجه خواهید شد که با کلیک بر روی شماره صفحه، تنها به تعداد رکوردهای همان صفحه، واکشی خواهیم داشت.
با تشکر از راهنمایی‌های آقای نصیری، امیدوارم این مقاله برای دوستان مفید باشه. منتظر نظرات دوستان هستم و اینکه چه جوری بتونیم اینکار رو با jquery ajax و به صورت سبکتر انجام بدیم.
این بخش مروری اجمالی بر الگوریتم‌های موجود در Analysis Services و پارامترهای قابل تنظیم و مقدار پیش فرض هر پارامتر میباشد، به منظور بررسی بیشتر هر یک به لینک‌های زیر مراجعه کنید:
(Data Mining Algorithms (Analysis Services - Data Mining
(Algorithm Parameters (SQL Server Data Mining Add-ins
1 - Microsoft Association Rules
به منظور ایجاد قوانینی که توصیف کننده این موضوع باشد که چه مواردی احتمالاً با یکدیگر در تراکنش‌ها ظاهر می‌شوند، استفاده میشود.
2 - Microsoft Clustering
به منظور شناسائی روابطی که در یک مجموعه داده ممکن است از طریق مشاهده منطقی به نظر نرسد، استفاده میشود. در واقع این الگوریتم با استفاده از تکنیک‌های تکرار شونده رکوردها را در خوشه هایی که حاوی ویژگی‌های مشابه هستند گروه بندی میکند.
3 - Microsoft Decision Trees
مبتنی بر روابط بین ستونهای یک مجموعه داده ای باعث پیش بینی روابط مدل‌ها میشود، که به صورت یک سری درختوار ویژگی‌ها در آن شکسته می‌شوند.
به منظور انجام پیش بینی از هر دو ویژگی پیوسته و گسسته پشتیبانی میشود.
4 - Microsoft Linear Regression
چنانچه یک وابستگی خطی میان متغیر هدف و متغیرهای مورد بررسی وجود داشته باشد، کارآمدترین رابطه میان متغیر هدف و ورودی‌ها را پیدا میکند.
به منظور انجام پیش بینی از ویژگی پیوسته پشتیبانی میکند.
5 - Microsoft Logistic Regression
به منظور تجزیه و تحلیل عواملی که در یک تصمیم گیری مشارکت دارند که پی آمد آن به وقوع یا عدم وقوع یک رویداد می‌انجامد از این الگوریتم استفاده میشود.
جهت انجام پیش بینی از هر دو ویژگی پیوسته و گسسته پشتیبانی میکند.
6 - Microsoft Naïve Bayes
احتمال ارتباط میان تمامی ستونهای ورودی و ستونهای قابل پیش بینی را پیدا میکند. همچنین این الگوریتم برای تولید سریع مدل کاوش به منظور کشف ارتباطات بسیار سودمند میباشد. تنها از ویژگی‌های گسسته یا گسسته شده پشتیبانی میکند و با تمامی ویژگی‌های ورودی به شکل مستقل رفتار میکند.
7 - Microsoft Neural Network
به منظور تجزیه و تحلیل داده‌های ورودی پیچیده یا مسائل بیزنسی که برای آنها مقدار قابل توجهی داده آموزشی در دسترس میباشد اما به آسانی نمی‌توان با استفاده از الگوریتم‌های دیگر این قوانین را بدست آورد، استفاده میشود. با استفاده از این الگوریتم میتوان چندین ویژگی را پیش بینی نمود. همچنین این الگوریتم می‌تواند به منظور طبقه بندی برای ویژگی‌های گسسته و ویژگی‌های پیوسته رگرسیون مورد استفاده قرار گیرد.
8 - Microsoft Sequence Clustering
به منظور شناسائی ترتیب رخدادهای مشابه در یک دنباله استفاده میشود. در واقع این الگوریتم ترکیبی از تجزیه تحلیل توالی و خوشه را فراهم میکند.
9 - Microsoft Time Series
به منظور تجزیه و تحلیل داده‌های زمانی (داده‌های مرتبط با زمان) در یک درخت تصمیم گیری خطی استفاده میشود. الگوهای کشف شده میتوانند به منظور پیش بینی مقادیر آینده در سری‌های زمانی استفاده شوند.
(Data Mining Algorithms (Analysis Services - Data Mining
(Algorithm Parameters (SQL Server Data Mining Add-ins
1 - Microsoft Association Rules
به منظور ایجاد قوانینی که توصیف کننده این موضوع باشد که چه مواردی احتمالاً با یکدیگر در تراکنش‌ها ظاهر می‌شوند، استفاده میشود.
| Range | Default | Parameter |
| (...,1] | 200000 | MAXIMUM_ITEMSET_COUNT |
| [0,500] | 3 | MAXIMUM_ITEMSET_SIZE |
| (...,0.0) | 1.0 | MAXIMUM SUPPORT |
| (...,...) | 999999999- | MINIMUM IMPORTANCE |
| [1,500] | 1 | MINIMUM_ITEMSET_SIZE |
| [0.0,1.0] | 0.4 | MINIMUM PROBABILITY |
| (...,0.0] | 0.0 | MINIMUM SUPPORT |
2 - Microsoft Clustering
به منظور شناسائی روابطی که در یک مجموعه داده ممکن است از طریق مشاهده منطقی به نظر نرسد، استفاده میشود. در واقع این الگوریتم با استفاده از تکنیک‌های تکرار شونده رکوردها را در خوشه هایی که حاوی ویژگی‌های مشابه هستند گروه بندی میکند.
| Range | Default | Parameter |
| (...,0] | 10 | CLUSTER COUNT |
| (...,0] | 0 | CLUSTER SEED |
| 1,2,3,4 | 1 | CLUSTERING METHOD |
| [0,65535] | 255 | MAXIMUM_INPUT_ATTRIBUTES |
| [2,65535],0 | 100 | MAXIMUM STATES |
| (...,0) | 1 | MINIMUM SUPPORT |
| [1,50] | 10 | MODELLING_CARDINALITY |
| (...,100],0 | 50000 | SAMPLE SIZE |
| (...,0) | 10 | STOPPING TOLERANCE |
3 - Microsoft Decision Trees
مبتنی بر روابط بین ستونهای یک مجموعه داده ای باعث پیش بینی روابط مدل‌ها میشود، که به صورت یک سری درختوار ویژگی‌ها در آن شکسته می‌شوند.
به منظور انجام پیش بینی از هر دو ویژگی پیوسته و گسسته پشتیبانی میشود.
| Range | Default | Parameter |
| (0.0,1.0) | COMPLEXITY_PENALTY | |
| FORCE REGRESSOR | ||
| [0,65535] | 255 | MAXIMUM_INPUT_ATTRIBUTES |
| [0,65535] | 255 | MAXIMUM_OUTPUT_ATTRIBUTES |
| (...,0.0) | 10.0 | MINIMUM SUPPORT |
| 1,3,4 | 4 | SCORE METHOD |
| [1,3] | 3 | SPLIT METHOD |
4 - Microsoft Linear Regression
چنانچه یک وابستگی خطی میان متغیر هدف و متغیرهای مورد بررسی وجود داشته باشد، کارآمدترین رابطه میان متغیر هدف و ورودی‌ها را پیدا میکند.
به منظور انجام پیش بینی از ویژگی پیوسته پشتیبانی میکند.
| Range | Default | Parameter |
| | FORCE REGRESSOR | |
| [0,65535] | 255 | MAXIMUM_INPUT_ATTRIBUTES |
| [0,65535] | 255 | MAXIMUM_OUTPUT_ATTRIBUTES |
5 - Microsoft Logistic Regression
به منظور تجزیه و تحلیل عواملی که در یک تصمیم گیری مشارکت دارند که پی آمد آن به وقوع یا عدم وقوع یک رویداد می‌انجامد از این الگوریتم استفاده میشود.
جهت انجام پیش بینی از هر دو ویژگی پیوسته و گسسته پشتیبانی میکند.
| Range | Default | Parameter |
| (0,100) | 30 | HOLDOUT_PERCENTAGE |
| (...,...) | 0 | HOLDOUT SEED |
| [0,65535] | 255 | MAXIMUM_INPUT_ATTRIBUTES |
| [0,65535] | 255 | MAXIMUM_OUTPUT_ATTRIBUTES |
| [2,65535],0 | 100 | MAXIMUM STATES |
| (...,0] | 10000 | SAMPLE SIZE |
6 - Microsoft Naïve Bayes
احتمال ارتباط میان تمامی ستونهای ورودی و ستونهای قابل پیش بینی را پیدا میکند. همچنین این الگوریتم برای تولید سریع مدل کاوش به منظور کشف ارتباطات بسیار سودمند میباشد. تنها از ویژگی‌های گسسته یا گسسته شده پشتیبانی میکند و با تمامی ویژگی‌های ورودی به شکل مستقل رفتار میکند.
| Range | Default | Parameter |
| [0,65535] | 255 | MAXIMUM_INPUT_ATTRIBUTES |
| [0,65535] | 255 | MAXIMUM_OUTPUT_ATTRIBUTES |
| [2,65535],0 | 100 | MAXIMUM STATES |
| (0,1) | 0.5 | MINIMUM_DEPENDENCY_PROBABILITY |
7 - Microsoft Neural Network
به منظور تجزیه و تحلیل داده‌های ورودی پیچیده یا مسائل بیزنسی که برای آنها مقدار قابل توجهی داده آموزشی در دسترس میباشد اما به آسانی نمی‌توان با استفاده از الگوریتم‌های دیگر این قوانین را بدست آورد، استفاده میشود. با استفاده از این الگوریتم میتوان چندین ویژگی را پیش بینی نمود. همچنین این الگوریتم می‌تواند به منظور طبقه بندی برای ویژگی‌های گسسته و ویژگی‌های پیوسته رگرسیون مورد استفاده قرار گیرد.
| Range | Default | Parameter |
| (...,0] | 4.0 | HIDDEN_NODE_RATIO |
| (0,100) | 30 | HOLDOUT PERCENTAGE |
| (...,...) | 0 | HOLDOUT SEED |
| [0,65535] | 255 | MAXIMUM_INPUT_ATTRIBUTES |
| [0,65535] | 255 | MAXIMUM_OUTPUT_ATTRIBUTES |
| [2,65535],0 | 100 | MAXIMUM STATES |
| (...,0] | 10000 | SAMPLE SIZE |
8 - Microsoft Sequence Clustering
به منظور شناسائی ترتیب رخدادهای مشابه در یک دنباله استفاده میشود. در واقع این الگوریتم ترکیبی از تجزیه تحلیل توالی و خوشه را فراهم میکند.
| Range | Default | Parameter |
| (...,0] | 10 | CLUSTER COUNT |
| [2,65535],0 | 64 | MAXIMUM_SEQUENCE_STATES |
| [2,65535],0 | 100 | MAXIMUM STATES |
| (...,0] | 10 | MINIMUM SUPPORT |
9 - Microsoft Time Series
به منظور تجزیه و تحلیل داده‌های زمانی (داده‌های مرتبط با زمان) در یک درخت تصمیم گیری خطی استفاده میشود. الگوهای کشف شده میتوانند به منظور پیش بینی مقادیر آینده در سری‌های زمانی استفاده شوند.
| Range | Default | Parameter |
| [0.0,1.0] | 0.6 | AUTO_DETECT_PERIODICITY |
| (1.0,...) | 0.1 | COMPLEXITY_PENALTY |
| ARIMA,ARTXP,MIXED | MIXED | FORECAST METHOD |
| [0,100] | 1 | HISTORIC_MODEL_COUNT |
| (...,1] | 10 | HISTORIC_MODEL_GAP |
| [0.0,1.0] | 1.0 | INSTABILITY_SENSITIVITY |
| [...,column maximum] | 1E308+ | MAXIMUM_SERIES_VALUE |
| [column minimum,...] | 1E308- | MINIMUM_SERIES_VALUE |
| (...,1] | 10 | MINIMUM SUPPORT |
| None,Previous,Mean | None | MISSING_VALUE_SUBSTITUTION |
| {...list of integers...} | {1} | PERIODICITY_HINT |
| [0.0,1.0] | 0.5 | PREDICTION SMOOTHING |
بررسی رفتار کدها و یافتن آسان‌تر باگ‌های احتمالی
فرض کنید در سرویس‌های خود، در حال استفاده از OData هستید. حال کافیست که metadata$ مربوط به سرویستان را برای استفاده‌ی کلاینت‌های دیگر، در اختیار آنها قرار دهید.
مشکلات این روش کاملا روشن و گویاست: پیچیدگی خیلی زیاد، دیباگ خیلی سخت و refactoring پیچیده و ...
اینبار همه چیز strongly typed و با همان intellisense معروف خواهد بود. فقط دقت کنید که اگر از Repository معرفی شده، برای سمت سرور خود استفاده میکنید، به دلیل اینکه از Namespace استفاده کرده‌ام، context شما، به نام namespace شما خواهد بود. در غیر اینصورت به صورت default و بدون namespace، باید از Default.Container استفاده شود.
وقتی از Odata استفاده میکنید، به صورت خودکار metadataی از سرویس‌ها و مدل‌های شما ساخته میشود و میتوان از آن به عنوان یک documentation کامل نام برد و حتی افرادی که استاندارد‌های Odata را نمیشناسند، به راحتی میتوانند آن را مطالعه و در صورت اجازه‌ی شما، از امکانات آن سرویس‌ها، در نرم افزار خودشان استفاده کنند.
بطور مثال میتوانید متادیتای برنامه‌ی خود را با استفاده از آدرس فرضی http://localhost:port/odata/$metadata مشاهده نمایید؛ که چیزی شبیه به محتوای زیر خواهد بود:
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0"> <edmx:DataServices> <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="OwinAspNetCore.Models"> <EntityType Name="Product"> <Key> <PropertyRef Name="Id"/> </Key> <Property Name="Id" Type="Edm.Int32" Nullable="false"/> <Property Name="Name" Type="Edm.String"/> <Property Name="Price" Type="Edm.Decimal" Nullable="false"/> </EntityType> </Schema> <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default"> <Function Name="TestFunction" IsBound="true"> <Parameter Name="bindingParameter" Type="Collection(OwinAspNetCore.Models.Product)"/> <Parameter Name="Val" Type="Edm.Int32" Nullable="false"/> <Parameter Name="Name" Type="Edm.String"/> <ReturnType Type="Edm.Int32" Nullable="false"/> </Function> <EntityContainer Name="Container"> <EntitySet Name="Products" EntityType="OwinAspNetCore.Models.Product"/> </EntityContainer> </Schema> </edmx:DataServices> </edmx:Edmx>
در اینجا میتوان EntityTypeها ، EntitySetها و همه‌ی Actionها و Functionهای خود را مشاهده نمایید.
به غیر از این، وجود metadata باعث شده به راحتی کلاینت‌های #JavaScript ،Java ،Objective-C ،C و ... بتوانند به راحتی ارتباط کاملی با سرویس‌های شما برقرار نمایند.
برای مثال به صورت معمول یک کلاینت #Cی برای ارتباط برقرار کردن با یک سرویس خارجی باید اینگونه عمل کند (یک درخواست از نوع POST):
string postUrl = "http://localhost:port/....";
HttpClient client = new HttpClient();
var response = client.PostAsync(postUrl, new StringContent(JsonConvert.SerializeObject(new { Rating = 5 }), Encoding.UTF8, "application/json")).Result; اگر مطالب قبلی را دنبال کرده باشید، به پیاده سازی سرویس‌های Odata پرداختیم. در این لینک یک repository کامل برای کار با odata در asp.net core آماده شده‌است و در این مقاله از آن استفاده نموده‌ام.
بعد از clone کردن آن، پروژه را run نمایید. به چیز بیشتری از آن نیازی نداریم.
حال کافیست یک پروژه‌ی Console Application را ساخته و بعد باید از طریق منوی Tools گزینه‌ی Extensions and Updates را انتخاب و odata v4 client code generator را جستجو نماییم:
آن را نصب نموده و بعد از تکمیل شدن، visual studio را restart کنید.
پروژه‌ی console خود را باز کرده و از طریق Add -> new item، آیتم OData client را جستجو کرده و با نام ProductClient.tt آن را تولید نمایید (نام آن اختیاری است):
فایل ProductClient.tt را که یک T4 code generator میباشد، باز کرده و مقدار ثابت MetadataDocumentUri را به آدرس سرویس odata خود تغییر دهید:
public const string MetadataDocumentUri = "http://localhost:port/odata/";
روی این آیتم کلیک راست و گزینه‌ی Run Custom tool را انتخاب نمایید. این تمام کاری است که نیاز به انجام دادن دارید.
حال فایل Program.cs را باز کرده و آنرا اینگونه تغییر دهید:
using ConsoleApplication1.OwinAspNetCore.Models;
using System;
using System.Linq;
namespace ConsoleApplication1
{
public class Program
{
static void Main(string[] args)
{
Uri uri = new Uri("http://localhost:24977/odata");
//var context = new Default.Container(uri);
var context = new TestNameSpace.TestNameSpace(uri);
//get
var products = context.Products.Where(pr => pr.Name.Contains("a"))
.Take(1).Select(pr => new { Firstname = pr.Name, PriceValue = pr.Price }).ToList();
//add
context.AddToProducts(new Product() { Name = "Name1", Price = 123 });
//update
Product p = context.Products.First();
p.Name = "changed";
context.UpdateObject(p);
//delete
context.DeleteObject(context.Products.Last());
//commit
context.SaveChanges();
}
}
} مشاهده میفرمایید که همه‌ی عملیات‌های لازم برای CRUD، به شرط اینکه در سمت سرور طراحی شده باشند، به راحتی از سمت کلاینت قابل فراخوانی خواهند بود.
از این ویژگی فوق العاده میتوان حتی در کلاینت‌ها جاوااسکریپتی نیز استفاده کرد. فرض کنید نرم افزار تحت وبی را با استفاده از jquery یا angularjs طراحی کرده‌اید. قاعدتا فراخوانی درخواست‌های شما به سمت سرور، چیزی شبیه به این خواهد بود:
//angularjs
$http.get("/products/get", {Name: "Test", Company: "Test"})
.then(function(response) {
console.log(response.data);
});
//jquery
$.get("/products/get", {Name: "Test", Company: "Test"}, function(data, status){
console.log("Data: " + data);
}); با استفاده از odata و typescript و یک library مربوط به odata client در سمت کلاینت، نرم افزار شما بجای موارد، بالا چیزی شبیه به مثال زیر خواهد بود (با همراه داشتن strongly typed و intellisense کامل)
let product1 = await context.products.filter(c => c.Name.contains("Ali")).toArray();
let product2 = await context.products.getSomeFunction(1, 'Test');
context.product.add({Name: 'Test'} as Product);
await context.saveChanges()
در مقاله‌های آتی به ویژگی‌های بیشتری از Odata خواهیم پرداخت.
نامگذاری (Naming) اشیا یک برنامه شاید در نگاه اول دارای اهمیت بالایی نباشه، اما تجربه نشون داده که در پروژه‌های بزرگ که با کمک چندین مجموعه به انجام میرسه نامگذاری صحیح و اصولی که از یکسری قواعد کلی و مناسب پیروی میکنه میتونه به پیشبرد اهداف و مدیریت راحتتر برنامه کمک بسیاری بکنه.
بیشتر موارد اشاره شده در این مطلب از کتاب جامع و مفید Framework Design Guidelines اقتباس شده که خوندن این کتاب مفید رو به خوانندگان توصیه میکنم.
برای کمک به نوشتن اصولی و راحتتر سورسهای برنامه‌ها در ویژوال استودیو نرم افزارهای متعددی وجود داره که با توجه به تجربه شخصی خودم نرم افزار Resharper محصول شرکت Jetbrains یکی از بهترین هاست که در مورد خاص مورد بحث در این مطلب نیز بسیار خوب عمل میکنه.
برخی از موارد موجود در مطلب جاری نیز از قراردادهای پیشفرض موجود در نرم افزار Resharper نسخه 6.0 برگرفته شده است و قسمتی نیز از تجربه شخصی خودم و سایر دوستان و همکاران بوده است.
اصل این مطلب حدود یکسال پیش تهیه شده و اگر نقایصی وجود داره لطفا اشاره کنین.
اصول و قراردادهای نامگذاری در دات‌نت
انواع نامگذاری
نامگذاری اشیا در حالت کلی را میتوان به سه روش زیر انجام داد:
1. Pascal Casing: در این روش حرف اول هر کلمه در نام شی به صورت بزرگ نوشته میشود.
FirstName
2. camel Casing: حرف اول در اولین کلمه نام هر شی به صورت کوچک و حرف اول بقیه کلمات به صورت بزرگ نوشته میشود.
firstName
3. Hungarian: در این روش برای هر نوع شی موجود یک پیشوند درنظر گرفته میشود تا از روی نام شی بتوان به نوع آن پی برد. در ادامه و پس از این پیشوندها سایر کلمات بر اساس روش Pascal Casing نوشته می‌شوند.
strFirstName lblFirstName
نکته: استفاده از این روش به جز در نامگذاری کنترلهای UI منسوخ شده است.
قراردادهای کلی
1. نباید نام اشیا تنها در بزرگ یا کوچک بودن حروف با هم فرق داشته باشند. به عنوان مثال نباید دو کلاس با نام‌های MyClass و myClass داشته باشیم. هرچند برخی از زبان‌ها case-sensitive هستند اما برخی دیگر نیز چنین قابلیتی ندارند (مثل VB.NET). بنابراین اگر بخواهیم کلاس‌های تولیدی ما در تمام محیط‌ها و زبان‌های برنامه نویسی قابل اجرا باشند باید از این قرارداد پیروی کنیم.
2. تا آنجا که امکان دارد باید از به‌کار بردن مخفف کلمات در نامگذاری اشیا دوری کنیم. مثلا به جای استفاده از GetChr باید از GetCharacter استفاده کرد.
البته در برخی موارد که مخفف واژه موردنظر کاربرد گسترده ای دارد میتوان از عبارت مخفف نیز استفاده کرد. مثل UI به جای UserInterface و یا IO به جای InputOutput.
آ. اصول نامگذاری فضای نام (namespace)
1. اساس نامگذاری فضای نام باید از قاعده زیر پیروی کند:
<Company>.<Technology|Produt|Project>[.<Feature>][.<SubNamespace>]
( < > : اجباری [ ] : اختیاری )
2. برای نامگذاری فضای نام باید از روش Pascal Casing استفاده شود.
3. در هنگام تعریف فضاهای نام به وابستگی آنها توجه داشته باشید. به عنوان مثال اشیای درون یک فضای نام پدر نباید به اشیای درون فضای نام یکی از فرزندانش وابسته باشد. مثلا در فضای نام System نباید اشیایی وجود داشته باشند که به اشیای درون فضای نام System.UI وابسته باشند.
4. سعی کنید از نام‌ها به صورت جمع برای عناوین فضای نام استفاده کنید. مثلا به جای استفاده از Kara.CSS.HQ.Manager.Entity از Kara.CSS.HQ.Manager.Entities استفاده کنید. البته برای مورادی که از عناوین مخفف و یا برندهای خاص استفاده کرده‌اید از این قرارداد پیروی نکنید. مثلا نباید از عنوانی شبیه به Kara.CSS.Manager.IOs استفاده کنید.
5. از عنوانی پایدار و مستقل از نسخه محصول برای بخش دوم عنوان فضای نام استفاده کنید. بدین معنی که این عناوین با گذر زمان و تغییر و تحولات در محتوای محصول و یا تولیدکننده نباید تغییر کنند. مثال:
Microsoft.Reporting.WebForms Kara.Support.Manager.Enums Kara.CSS.HQ.WebUI.Configuration
6. از عناوین یکسان برای فضای نام و اشیای درون آن استفاده نکنید. مثلا نباید کلاسی با عنوان Manager در فضای نام Kara.CSS.Manager وجود داشته باشد.
7. از عناوین یکسان برای اشیای درون فضاهای نام یک برنامه استفاده نکنید. مثلا نباید دو کلاس با نام Package در فضاهای نام Kara.CSS.Manger و Kara.CSS.Manger.Entities داشته باشید.
ب. اصول نامگذاری کلاس‌ها و Structها
1. عنوان کلاس باید اسم یا موصوف باشد.
2. در نامگذاری کلاس‌ها باید از روش Pascal Casing استفاده شود.
3. نباید از عناوین مخففی که رایج نیستند استفاده کرد.
4. از پیشوندهای زائد مثل C یا Cls نباید استفاده شود.
5. نباید از کاراکترهایی به غیر از حروف (و یا در برخی موارد خیلی خاص، شماره نسخه) در نامگذاری کلاس‌ها استفاده شود.
مثال:
درست:
PackageManager , PacakgeConfigGenerator Circle , Utility , Package
نادرست:
CreateConfig , classdata CManager , ClsPackage , Config_Creator , Config1389
6. در نامگذاری اشیای Generic از استفاده از عناوینی چون Element, Node, Log و یا Message پرهیز کنید. این کار موجب به‌وجودآمدن کانفلیکت در عناوین اشیا میشود. در این موارد بهتر است از عناوینی چون FormElement, XmlNode, EventLog و SoapMessage استفاده شود. درواقع بهتر است نام اشیای جنریک، برای موارد موردنیاز، کاملا اختصاصی و درعین حال مشخص‌کننده محتوا و کاربرد باشند.
7. از عناوینی مشابه عناوین کتابخانه‌های پایه دات‌نت برای اشیای خود استفاده نکنید. مثلا نباید کلاسی با عنوان Console, Parameter, Action و یا Data را توسعه دهید. همچنین از کابرد عناوینی مشابه اشیای موجود در فضاهای نام غیرپایه دات‌نت و یا غیردات‌نتی اما مورداستفاده در پروژه خود که محتوا و کاربردی مختص همان فضای نام دارند پرهیز کنید. مثلا نباید کلاسی با عنوان Page در صورت استفاده از فضای نام System.Web.UI تولید کنید.
8. سعی کنید در مواردی که مناسب به‌نظر می‌رسد از عنوان کلاس پایه در انتهای نام کلاس‌های مشتق‌شده استفاده کنید. مثل FileStream که از کلاس Stream مشتق شده است. البته این قاعده در تمام موارد نتیجه مطلوب ندارد. مثلا کلاس Button که از کلاس Control مشتق شده است. بنابراین در به‌کاربردن این مورد بهتر است تمام جوانب و قواعد را درنظر بگیرید.
پ. اصول نامگذاری مجموعه‌ها (Collections)
یک مجموعه در واقع یک نوع کلاس خاص است که حاوی مجموعه‌ای از داده‌هاست و از همان قوانین کلاس‌ها برای نامگذاری آنها استفاده میشود.
1. بهتر است در انتهای عنوان مجموعه از کلمه Collection استفاده شود. مثال:
CenterCollection , PackageCollection
2. البته درصورتی‌که کلاس مورد نظر ما رابط IDictionary را پیاده‌سازی کرده باشد بهتر است از پسوند Dictionary استفاده شود.
ت. اصول نامگذاری Delegateها
1. عنوان یک delegate باید اسم یا موصوف باشد.
2. در نامگذاری delegateها باید از روش Pascal Casing استفاده شود.
3. نباید از عناوین مخففی که رایج نیستند استفاده کرد.
4. از پیشوندهای زائد مثل D یا del نباید استفاده شود.
5. نباید از کاراکترهایی به غیر از حروف در نامگذاری delegateها استفاده شود.
6. نباید در انتهای نام یک delegate از عبارت Delegate استفاده شود.
7. بهتر است که درصورت امکان در انتهای نام یک delegate که برای Event Handler استفاده نمی‌شود از عبارت Callback استفاده شود. البته تنها درصورتی‌که معنی و مفهوم مناسب را داشته باشد.
مثال:
نحوه تعریف یک delegate
public delegate void Logger (string log); public delegate void LoggingCallback (object sender, string reason);
ث. اصول نامگذاری رویدادها (Events)
1. عنوان یک رویداد باید فعل یا مصدر باشد.
2. در نامگذاری کلاس‌ها باید از روش Pascal Casing استفاده شود.
3. نباید از عناوین مخففی که رایج نیستند استفاده کرد.
4. از پیشوندهای زائد نباید استفاده شود.
5. نباید از کاراکترهایی به غیر از حروف در نامگذاری رویدادها استفاده شود.
6. بهتر است از پسوند EventHandler در عنوان هندلر رویداد استفاده شود.
7. از به کاربردن عباراتی چون AfterXXX و یا BeforeXXX برای نمایش رویدادهای قبل و یا بعد از رخداد خاصی خودداری شود. به جای آن باید از اسم مصدر (شکل ingدار فعل) برای نامگذاری رویداد قبل از رخداد و همچنین شکل گذشته فعل برای نامگذاری رویداد بعد از رخداد خاص استفاده کرد.
مثلا اگر کلاسی دارای رویداد Open باشد باید از عنوان Openning برای رویداد قبل از Open و از عنوان Opened برای رویداد بعد از Open استفاده کرد.
8. نباید از پیشوند On برای نامگذاری رویداد استفاده شود.
9. همیشه پارامتر e و sender را برای آرگومانهای رویداد پیاده سازی کنید. sender که از نوع object است نمایش دهنده شیی است که رویداد مربوطه را به وجود آورده است و e درواقع آرگومانهای رویداد مربوطه است.
10. عنوان کلاس‌آرگومان‌های رویداد باید دارای پسوند EventArgs باشد.
مثال:
عنوان کلاس‌آرگومان:
AddEventArgs , EditEventArgs , DeleteEventArgs
عنوان رویداد:
Adding , Add , Added
تعریف یک EventHandler:
public delegate void <EventName>EventHandler (object sender, <EventName>EventArgs e);
نکته: نیاز به تولید یک EventHandler مختص توسعه یک برنامه به‌ندرت ایجاد میشود. در اکثر موارد میتوان با استفاده از کلاس جنریک <EventHandler<TEventArgs تمام احتیاجات خود را برطرف کرد.
تعریف یک رویداد:
public event EventHandler <AddEventArgs> Adding;
ج. اصول نامگذاری Attributeها
1. عنوان یک attribute باید اسم یا موصوف باشد.
2. در نامگذاری attributeها باید از روش Pascal Casing استفاده شود.
3. نباید از عناوین مخففی که رایج نیستند استفاده کرد.
4. از پیشوندهای زائد مثل A یا atr نباید استفاده شود.
5. نباید از کاراکترهایی به غیر از حروف در نامگذاری attributeها استفاده شود.
6. بهتر است در انتهای نام یک attribute از عبارت Attribute استفاده شود.
مثال:
DisplayNameAttribute , MessageTypeAttribute
چ. اصول نامگذاری Interfaceها
1. در ابتدای عنوان interface باید از حرف I استفاده شود.
2. نام باید اسم، موصوف یا صفتی باشد که interface را توصیف میکند.
به عنوان مثال:
IComponent (اسم) IConnectionProvider (موصوف) ICloneable (صفت)
3. از روش Pascal Casing استفاده شود.
4. خودداری از بکاربردن عبارات مخفف غیررایج.
5. باید تنها از کاراکترهای حرفی در نام interface استفاده شود.
ح. اصول نامگذاری Enumerationها
1. استفاده از روش Pascal Casing
2. خودداری از کاربرد عبارات مخفف غیررایج
3. تنها از کاراکترهای حرفی در نام Enumretionها استفاده شود.
4. نباید از پسوند یا پیشوند Enum یا Flag استفاده شود.
5. اعضای یک Enum نیز باید با روش Pascal Casing نامگذاری شوند.
مثال:
public enum FileMode {
Append,
Read, …
}
6. درصورتی‌که enum موردنظر از نوع flag نیست باید عنوان آن مفرد باشد.
7. درصورتی‌که enum موردنظر برای کاربرد flag طراحی شده باشد نام آن باید جمع باشد. مثال:
[Flag]
public enum KeyModifiers {
Alt = 1,
Control = 2,
Shift = 4
}
8. از به‌کاربردن پسوند و یا پیشوندهای اضافه در نامگذاری اعضای یک enum نیز پرهیز کنید. مثلا نامگذاری زیر نادرست است:
public enum OperationState {
DoneState,
FaultState,
RollbackState
}
خ. اصول نامگذاری متدها
1. نام متد باید فعل یا ترکیبی از فعل و اسم یا موصوف باشد.
2. باید از روش Pascal Casing استفاده شود.
3. خودداری از بکاربردن عبارات مخفف غیررایج و یا استفاده زیاد از اختصار
4. تنها از کاراکترهای حرفی برای نام متد استفاده شود.
مثال:
AddDays , Save , DeleteRow , BindData , Close , Open
د. اصول نامگذاری Propertyها
1. نام باید اسم، صفت یا موصوف باشد.
2. باید از روش Pascal Casing استفاده شود.
3. خودداری از بکاربردن عبارات مخفف غیررایج.
4. تنها از کاراکترهای حرفی برای نامگذاری پراپرتی استفاده شود.
مثال:
Radius , ReportType , DataSource , Mode , CurrentCenterId
5. از عبارت Get در ابتدای هیچ Propertyای استفاده نکنید.
6. نام خاصیت‌هایی که یک مجموعه برمی‌گرداند باید به صورت جمع باشد. عنوان این Propertyها نباید به‌صورت مفرد به همراه پسوند Collection یا List باشد. مثال:
public CenterCollection Centers { get; set; }
7. خواص Boolean را با عناوینی مثبت پیاده‌سازی کنید. مثلا به‌جای استفاده از CantRead از CanRead استفاده کنید. بهتر است این Propertyها پیشوندهایی چون Is, Can یا Has داشته باشند، البته تنها درصورتی‌که استفاده از چنین پیشوندهایی ارزش افزوده داشته و مفهوم آن را بهتر برساند. مثلا عنوان CanSeek مفهوم روشن‌تری نسبت به Seekable دارد. اما استفاده از Created خیلی بهتر از IsCreated است یا Enabled کاربرد به مراتب راحت‌تری از IsEnabled دارد.
برای تشخیص بهتر این موارد بهتر است از روش ifسنجی استفاده شود. به عنوان مثال
if (list.Contains(item)) if (regularExpression.Matches(text)) if (stream.CanSeek) if (context.Created) if (form.Enabled)
مفهوم درست‌تری نسبت به موارد زیر دارند:
if (list.IsContains(item)) if (regularExpression.Match(text)) if (stream.Seekable) if (context.IsCreated) if (form.IsEnabled)
8. بهتر است در موارد مناسب عنوان Property با نام نوعش برابر باشد. مثلا
public Color Color { get; set; }
ذ. اصول نامگذاری پارامترها
پارامتر درحالت کلی به آرگومان وروی تعریف شده برای یک متد گفته میشود.
1. حتما از یک نام توصیفی استفاده شود. از نامگذاری پارامترها براساس نوعشان به‌شدت پرهیز کنید.
2. از روش camel Casing استفاده شود.
3. تنها از کاراکترهای حرفی برای نامگذاری پارامترها استفاده شود.
مثال:
firstName , e , id , packageId , centerName , name
4. نکاتی برای نامگذاری پارامترهای Operator Oveloading:
- برای operatorهای دو پارامتری (binary operators) از عناوین left و right برای پارامترهای آن استفاده کنید:
public static MyType operator +(MyType left, MyType right) public static bool operator ==(MyType left, MyType right)
- برای operatorهای تک‌پارامتری (unary operators) اگر برای پارامتر مورد استفاده هیچ عنوان توصیفی مناسبی پیدا نکردید حتما از عبارت value استفاده کنید:
public static MyType operator ++(MyType value)
- درصورتی‌که استفاده از عناوین توصیفی دارای ارزش افزوده بوده و خوانایی کد را بهتر میکند حتما از این نوع عناوین استفاده کنید:
public static MyType operator /(MyType dividend, MyType divisor)
- نباید از عبارات مخفف یا عناوینی با اندیس‌های عددی استفاده کنید:
public static MyType operator -(MyType d1, MyType d2) // incorrect!
ر. اصول نامگذاری متغیر (Variable)ها
- نام متغیر باید اسم، صفت یا موصوف باشد.
نامگذاری متغیرها باید با توجه به نوع آن انجام شود.
1. متغیرهای عمومی (public) و protected و Constantها
- استفاده از روش Pascal Casing
- تنها از کاراکترهای حرفی برای نام متغیر عمومی استفاده شود.
مثال:
Area , DataBinder , PublicCacheName
2. متغیرهای private (در سطح کلاس یا همان field)
- نام این نوع متغیر باید با یک "_" شروع شود.
- از روش camel Casing استفاده شود.
مثال:
_centersList _firstName _currentCenter
3. متغیرهای محلی در سطح متد
- باید از روش camel Casing استفاده شود.
- تنها از کاراکترهای حرفی استفاده شود.
مثال:
parameterType , packageOperationTypeId
ز. اصول نامگذاری کنترلهای UI
1. نام باید اسم یا موصوف باشد.
2. استفاده از روش Hungarian !
3. عبارت مخفف معرفی‌کننده کنترل، باید به اندازه کافی برای تشخیص نوع آن مناسب باشد.
مثال:
lblName (Label) txtHeader (TextBox) btnSave (Button)
ژ. اصول نامگذاری Exceptionها
تمام موارد مربوط به نامگذاری کلاس‌ها باید در این مورد رعایت شود.
1. باید از پسوند Exception در انتهای عنوان استفاده شود.
مثال:
ArgumentNullException , InvalidOperaionException
س. نامگذاری اسمبلی‌ها و DLLها
1. عناوینی که برای نامگذاری اسمبلی‌ها استفاده می‌شوند، باید نمایش‌دهنده محتوای کلی آن باشند. مثل:
System.Data
2. از روش زیر برای نامگذاری اسمبلی‌ها استفاده شود:
<Company>.<Component>.dll <Company>.<Project|Product|Technology>.<Component>.dll
مثل:
Microsoft.CSharp.dll , Kara.CSS.Manager.dll
ش. نامگذاری پارامترهای نوع (Generic (type parameter
1. از حرف T برای پارامترهای تک‌حرفی استفاده کنید. مثل:
public int IComparer<T> {…}
public delegate bool Predicate<T> (T item)
2. تمامی پارامترهای جنریک را با عناوینی توصیفی و مناسب که مفهوم و کاربرد آنرا برساند نامگذاری کنید، مگر آنکه یافتن چنین عباراتی ارزش افزوده‌ای در روشن‌تر کردن کد نداشته باشد. مثال:
public int ISessionChannel<TSession> {…}
public delegate TOutput Converter<TInput, TOutput> (TInput from)
public class Nullable<T> {…}
public class List<T> {…}
3. در ابتدای عناوین توصیفی حتما از حرف T استفاده کنید.
4. بهتر است تا به‌صورتی روشن نوع قید قرار داده شده بر روی پارامتری خاص را در نام آن پارامتر نمایش دهید. مثلا اگر قید ISession را برای پارامتری قرار دادید بهتر است نام آن پارامتر را TSession درنظر بگیرید.
ص. نامگذاری کلید Resourceها
به دلیل شباهت ساختاری که میان کلیدهای resource و propertyها وجود دارد قواعد نامگذاری propertyها در اینجا نیز معتبر هستند.
1. از روش نامگذاری Pascal Casing برای کلیدهای resource استفاده کنید.
2. از عناوین توصیفی برای این کلیدها استفاده کنید. سعی کنید تا حد امکان به هیچ وجه از عناوین کوتاه و یا مخففی که مفهوم را به‌صورت ناکامل می‌رساند استفاده نکنید. درواقع سعی کنید که خوانایی بیشتر کد را فدای فضای بیشتر نکنید.
3. از کلیدواژه‌های CLR و یا زبان مورداستفاده برای برنامه‌نویسی در نامگذاری این کلیدها استفاده نکنید.
4. تنها از حروف و اعداد و _ در نامگذاری این کلیدها استفاده کنید.
5. سعی کنید از عناوین توصیفی همانند زیر برای پیام‌های مناسب خطاها جهت نمایش به کاربر برای کلیدهای مربوطه استفاده کنید. درواقع نام کلید باید ترکیبی از نام نوع خطا و یک آی‌دی مشخص‌کننده پیغام مربوطه باشد:
ArgumentExceptionIllegalCharacters ArgumentExceptionInvalidName ArgumentExceptionFileNotFound
نکاتی درمورد کلمات مرکب
کلمات مرکب به کلماتی گفته میشود که در آن از بیش از یک کلمه با مفهوم مستقل استفاده شده باشد. مثل Callback یا FileName.
باید توجه داشت که با تمام کلمات موجود در یک کلمه مرکب نباید همانند یک کلمه مستقل رفتار کرد و حرف اول آن را در روش‌های نامگذاری موجود به‌صورت بزرگ نوشت. کلمات مرکبی وجود دارند که به آنها closed-form گفته میشود. این کلمات مرکب با اینکه از 2 یا چند کلمه دارای مفهوم مستقل تشکیل شده‌اند اما به‌خودی‌خود دارای مفهوم جداگانه و مستقلی هستند. برای تشخیص این کلمات میتوان به فرهنگ لغت مراجعه کرد (و یا به‌سادگی از نرم‌افزار Microsoft Word استفاده کرد) و دریافت که آیا کلمه مرکب موردنظر آیا مفهوم مستقلی برای خود دارد، یعنی درواقع آیا عبارتی closed-form است. با کلمات مرکب از نوع closed-form همانند یک کلمه ساده برخورد میشود!
در جدول زیر مثال‌هایی از عبارات رایج و نحوه درست و نادرست استفاده از هریک نشان داده شده است.
|
Pascal Casing |
camel Casing |
Wrong |
|
Callback |
callback |
CallBack |
|
BitFlag |
bitFlag |
Bitflag / bitflag |
|
Canceled |
canceled |
Cancelled |
|
DoNot |
doNot |
Donot / Don’t |
|
|
|
|
|
Endpoint |
endpoint |
EndPoint / endPoint |
|
FileName |
fileName |
Filename / filename |
|
Gridline |
gridline |
GridLine / gridLine |
|
Hashtable |
hashtable |
HashTable / hashTable |
|
Id |
id |
ID |
|
Indexes |
indexes |
Indices |
|
LogOff |
logOff |
Logoff / LogOut ! |
|
LogOn |
logOn |
Logon / LogIn ! |
|
SignOut |
signOut |
Signout / SignOff |
|
SignIn |
signIn |
Signin / SignOn |
|
Metadata |
metadata |
MetaData / metaData |
|
Multipanel |
multipanel |
MultiPanel / multiPanel |
|
Multiview |
multiview |
MultiView / multiView |
|
Namespace |
namespace |
NameSpace / nameSpace |
|
Ok |
ok |
OK |
|
Pi |
pi |
PI |
|
Placeholder |
placeholder |
PlaceHolder / placeHolder |
|
UserName |
username |
Username / username |
|
WhiteSpace |
whiteSpace |
Whitespace / whitespace |
|
Writable |
writable |
Writeable / writeable |
همان‌طور که در جدول بالا مشاهد میشود در استفاده از قوانین عبارات مخفف دو مورد استثنا وجود دارد که عبارتند از Id و Ok. این کلمات باید همان‌طور که در اینجا نشان داده شده‌اند استفاده شوند.
نکاتی درباره عبارات مخفف
1. عبارات مخفف (Acronym) با خلاصه‌سازی کلمات (Abbreviation) فرق دارند. یک عبارت مخفف شامل حروف اول یک عبارت طولانی یا معروف است، درصورتی‌که خلاصه‌سازی یک عبارت یا کلمه از حذف بخشی از آن به‌دست می‌آید. تا آنجاکه امکان دارد از خلاصه‌سازی عبارات نباید استفاده شود. همچنین استفاده از عبارات مخفف غیررایج توصیه نمی‌شود.
مثال: IO و UI
2. براساس تعریف، یک مخفف حداقل باید 2 حرف داشته باشد. نحوه برخورد با مخفف‌های دارای بیشتر از 2 حرف با مخفف‌های دارای 2 حرف باهم متفاوت است. با مخفف‌های دارای 2 حرف همانند کلمه‌ای یک حرفی! برخورد میشود، درصورتی‌که با سایر مخفف‌ها همانند یک کلمه کامل چندحرفی برخورد میشود. به‌عنوان مثال IOStream برای روش PascalCasing و ioStream برای روش camelCasing استفاده میشود. همچنین از HtmlBody و htmlBody به‌ترتیب برای روش‌های Pascal و camel استفاده میشود.
3. هیچ‌کدام از حروف یک عبارت مخفف در ابتدای یک واژه نام‌گذاری‌شده به روش camelCasing به‌صورت بزرگ نوشته نمی‌شود!
نکته: موارد زیادی را میتوان یافت که در ابتدا به‌نظر می‌رسد برای پیاده‌سازی آنها باید قوانین فوق را نقض کرد. این موارد شامل استفاده از کتابخانه‌های سایر پلتفرم‌ها (مثل MFC, HTML و غیره)، جلوگیری از مشکلات جغرافیایی! (مثلا در مورد نام کشورها یا سایر موقعیت‌های جغرافیایی)، احترام به نام افراد درگذشته، و مواردی از این دست میشود. اما در بیشتر قریب به اتفاق این موارد هم میتوان بدون تقض قوانین فوق اقدام به نامگذاری اشیا کرد، بدون اینکه با تغییر عبارت اصلی (که موجب تطابق با این قوانین میشود) لطمه‌ای به مفهوم آن بزند. البته تنها موردی که به‌نظر می‌رسد می‌تواند قوانین فوق را نقض کند نام‌های تجاری هستند. البته استفاده از نام‌های تجاری توصیه نمی‌شود، چون این نام‌ها سریع‌تر از محتوای کتابخانه‌های برنامه‌نویسان تغییر می‌کنند!
نکته: برای درک بهتر قانون "عدم استفاده از عبارات مخففی که رایج نیستند" مثالی از زبان توسعه دهندگان دات‌نت‌فریمورک ذکر میشود. در کلاس Color متد زیر با Overloadهای مختلف در دسترس است:
public class Color {
…
public static Color FromArgb(…)
{ … }
}
همان‌طور که مشاهده میشود برای رعایت قوانین فوق به‌جای استفاده از ARGB از عبارت Argb استفاده شده است. اما این نحوه استفاده موجب شده تا این سوال به‌ظاهر خنده‌دار اما درست پیش‌آید:
"چطور میشود در این کلاس رنگی را از ARGB تبدل کرد؟ هرچه که من میبینم فقط تبدیل از طریق (Argb) آرگومان b است!"
حال در این نقطه به‌نظر می‌رسد که در اینجا باید قوانین فوق را نقض کرد و از عنوان FromARGB که مفهوم درست را می‌رساند استفاده کرد. اما با کمی دقت متوجه می‌شویم که این قوانین در ابتدا نیز با پیاده‌سازی نشان داده شده در قطعه کد بالا نقض شده‌اند! همه می‌دانیم که عبارت RGB مخفف معروفی برای عبارت Red Green Blue است. اما استفاده از ARGB برای افزودن کلمه Alpha به ابتدای عبارت مذکور چندان رایج نیست. پس استفاده از مخفف Argb از همان ابتدا اشتباه به‌نظر می‌رسد. بنابراین راه‌حل بهتر می‌تواند استفاده از عنوان FromAlphaRgb باشد که هم قوانین فوق را نقض نکرده و هم مفهوم را بهتر می‌رساند.
دیگر نکات
1. قراردادهای اشاره شده در این سند حاصل کار شبانه روزی تعداد بسیاری از برنامه نویسان در سرتاسر جهان در پروژه‌های بزرگ بوده است. این اصول کلی تنها برای توسعه آسان‌تر و سریع‌تر پروژه‌های بزرگ تعیین شده‌اند و همان‌طور که روشن است تنها ازطریق تجربه دست‌یافتنی هستند. بنابراین چه بهتر است که در این راه از تجارب بزرگان این عرصه بیشترین بهره برده شود.
2. همچنین توجه داشته باشید که بیشتر قراردادهای اشاره شده در این سند از راهنمای نامگذاری تیم توسعه BCL دات‌نت‌فریمورک گرفته شده است. این تیم طبق اعتراف خودشان زمان بسیار زیادی را برای نامگذاری اشیا صرف کرده‌اند و توصیه کرده‌اند که دیگران نیز برای نامگذاری، زمان مناسب و کافی را در توسعه پروژه‌ها درنظر بگیرند.
در Blazor میتوان مسیریابی‌های پارامتری را به صورت زیر نیز تعریف کرد:
@page "/post/edit/{EditId:int}"
که در اینجا EditId، یک پارامتر مسیریابی از نوع int تعریف شده و به صورت زیر در کدهای صفحه‌ی مرتبط، قابل دسترسی است:
[Parameter] public int? EditId { set; get; }
int تعریف شده‌ی در این مسیریابی، یک routing constraint و یا یک قید مسیریابی محسوب میشود و استفاده‌ی از آن، چنین مزایایی را به همراه دارد:
- در این حالت فقط EditId های عددی پردازش می‌شوند و اگر رشته‌ای دریافت شود، کاربر با خروجی از نوع 404 و یا «یافت نشد»، مواجه خواهد شد.
- امکان اعتبارسنجی مقادیر دریافتی، پیش از ارسال آنها به صفحه و پردازش صفحه.
قیود پیشفرض تعریف شده‌ی در Blazor
اگر به مستندات مسیریابی Blazor مراجعه کنیم، به‌نظر فقط این موارد را میتوان به‌عنوان قیود پارامترهای مسیریابی تعریف کرد:
bool, datetime, decimal, double, float, guid, int, long, nonfile
و ... توضیحاتی در مورد اینکه آیا امکان بسط آنها وجود دارند یا خیر، فعلا در مستندات رسمی آن، ذکر نشده‌اند.
در Blazor 8x میتوان از قیود مسیریابی سفارشی ASP.NET Core نیز استفاده کرد!
ASP.NET Core سمت سرور، به همراه امکان سفارشی سازی قیودمسیریابی خود نیز هست که آنرا میتوان به کمک اینترفیسIRouteConstraint پیاده سازی کرد:
namespace Microsoft.AspNetCore.Routing
{
public interface IRouteConstraint
{
bool Match(
HttpContext httpContext,
IRouter route,
string routeKey,
RouteValueDictionary values,
RouteDirection routeDirection);
}
}
جالب اینجا است که میتوان این نمونه‌های سفارشی را حداقل در نگارش جدید Blazor 8x SSR نیز استفاده کرد؛ هرچند در مستندات رسمی Blazor هنوز به آن اشاره‌ای نشده‌است.
در امضای متد Match فوق، دو پارامتر routeKey و values آن بیش از مابقی مهم هستند:
- routeKey مشخص میکند که الان کدام پارامتر مسیریابی (مانند EditId در این مطلب) در حال پردازش است.
- values، یک دیکشنری است که کلید هر عضو آن، پارامتر مسیریابی و مقدار آن، مقدار دریافتی از URL جاری است.
- اگر این متد مقدار true را برگرداند، یعنی مسیریابی وارد شده‌ی به آن، با موفقیت پردازش و اعتبارسنجی شده و میتوان صفحه‌ی مرتبط را نمایش داد؛ در غیراینصورت، کاربر پیام یافت نشدن آن صفحه و مسیر درخواستی را مشاهده میکند.
پیاده سازی یک قید سفارشی رمزگشایی پارامترهای مسیریابی
فرض کنید قصد ندارید که پارامترهای مسیریابی ویرایش رکوردهای خاصی را دقیقا بر اساس Id متناظر عددی آنها در بانک اطلاعاتی، نمایش دهید؛ برای مثال نمی‌خواهید دقیقا آدرس post/edit/1 را به کاربر نمایش دهید؛ چون نمایش این اعداد عموما ساده و ترتیبی، حدس زدن آنها را ساده کرده و ممکن است در آینده مشکلات امنیتی را به همراه داشته باشد.
می‌خواهیم از آدرس‌های متداول و ساده‌ی عددی زیر:
@page "/post/edit/{EditId:int}"
به آدرس رمزنگاری شده‌ی زیر برسیم:
@page "/post/edit/{EditId:encrypt}"
اگر به این آدرس جدید دقت کنید، در اینجا از نام قید جدیدی به نام encrypt استفاده شده‌است که جزو قیود پیشفرض سیستم مسیریابی Blazor نیست. روش تعریف آن به صورت زیر است:
using System.Globalization;
using DNTCommon.Web.Core;
namespace Blazor8xSsrComponents.Utils;
public class EncryptedRouteConstraint(IProtectionProviderService protectionProvider) : IRouteConstraint
{
public const string Name = "encrypt";
public bool Match(HttpContext? httpContext,
IRouter? route,
string routeKey,
RouteValueDictionary values,
RouteDirection routeDirection)
{
ArgumentNullException.ThrowIfNull(routeKey);
ArgumentNullException.ThrowIfNull(values);
if (!values.TryGetValue(routeKey, out var routeValue))
{
return false;
}
var valueString = Convert.ToString(routeValue, CultureInfo.InvariantCulture);
values[routeKey] = string.IsNullOrEmpty(valueString) ? null : protectionProvider.Decrypt(valueString);
return true;
}
}
توضیحات:
- در قیود سفارشی میتوان سرویس‌ها را به سازنده‌ی کلاس تزریق کرد و برای مثال از سرویس IProtectionProviderService که در کتابخانه‌ی DNTCommon.Web.Core تعریف شده، برای رمزگشایی اطلاعات رسیده، استفاده کرده‌ایم.
- یک نام را هم برای آن درنظر گرفته‌ایم که از این نام در فایل Program.cs به صورت زیر استفاده میشود:
builder.Services.Configure<RouteOptions>(opt =>
{
opt.ConstraintMap.Add(EncryptedRouteConstraint.Name, typeof(EncryptedRouteConstraint));
});
یعنی زمانیکه سیستم مسیریابی به قید جدیدی به نام encrypt می‌رسد:
@page "/post/edit/{EditId:encrypt}"
آنرا در لیست ConstraintMap ای که به نحو فوق به سیستم معرفی شده، جستجو میکند. اگر این نام یافت شد، سپس کلاس EncryptedRouteConstraint متناظر را نمونه سازی کرده و در جهت پردازش مسیر رسیده، مورد استفاده قرار میدهد.
- در کلاس EncryptedRouteConstraint و متد Match آن، مقدار رشته‌ای EditId دریافت شده‌ی از طریق آدرس جاری درخواستی، رمزگشایی شده و بجای مقدار فعلی رمزنگاری شده‌ی آن درج میشود. همین اندازه برای مقدار دهی خودکار پارامتر EditId ذیل در صفحات مرتبط، کفایت میکند:
[Parameter] public string? EditId { set; get; }
یعنی دیگر نیازی نیست تا در صفحات مرتبط، کار رمزگشایی EditId، به صورت دستی انجام شود.
کلا عرضم در باب asp.net بود.