.MainTableSummarySettings(summarySettings => { //... summarySettings.AllGroupsSummarySettings("جمع نهایی"); })
Column Store Index یکی از ویژگیهای جدید SQL Server 2012 می باشد، که کارایی Query های قایل اجرا روی دیتابیسهای با حجم داده ای بسیار بالا را (که اصطلاحا به آنها Data Warehouse یا انبار داده گویند)، چندین برابر بهبود بخشیده است.
قبل از توضیح در مورد Column Store مختصری در مورد نحوه ذخیره سازی دادهها در SQL Server می پردازیم. میتوان گفت در SQL Server دو روش ذخیره سازی وجود دارد،یکی بصورت ردیفی که اصطلاحا به آن Row Storeیا Row-Wise گویند، و دیگری بصورت ستونی که اصطلاحا به آن Column Store گویند.
در روش ذخیره سازی Row Store، مقادیر ستونها در یک سطر بصورت متوالی ذخیره میشوند، در این روش ذخیره سازی از ساختار B-Tree یا Heap استفاده میشود.
یادآوری: در ساختار B-Tree، یک گره Root وجود دارد، و گره بعد از Root گره ای است که آدرس گره راست بعدی و آدرس گره چپ بعدی را در خود نگه میدارد.
شکل زیر نمای یک درخت B-Tree میباشد:
جهت کسب اطلاعات بیشتر درمورد ساختار B-Tree
یادآوری: وقتی در یک جدول، ایندکسی از نوع Clustered ایجاد نماییم، SQL Server، در ابتدا یک کپی از جدول ایجاد و دادههای جدول را از نو مرتب مینماید، و ساختار صفحه ریشه و دیگر صفحات را ایجاد میکند و سپس جدول اصلی را حذف مینماید. به جدولی که Clustered Index ندارد، اصطلاحا Heap گویند.
برخلاف ذخیره سازی Row Store، در ذخیره سازی Column Store، دادهها بصورت ستونی ذخیره میشوند،در این روش داده ها، فشرده سازی میشوند و اینکار باعث میشود،در زمان درخواست یک Query، نیاز به Disk I/o به حداقل برسد، در نتیجه، زمان و سرعت پاسخگویی به پرس و جوها بسیار افزایش مییابد.
شکل زیر نحوه ذخیره سازی داده ها،بصورت Row Store را نمایش میدهد:
شکل بالا ذخیره سازی داده ها، در ساختار B-Tree یا Heap را نمایش میدهد، در شکل فوق یک جدول چهار ستونی با N سطر (Row) در نظر گرفته شده است.بطوریکه ستونهای هر Row بطور متوالی در یک صفحه (Page) یکسان ذخیره میشوند.
شکل زیر نحوه ذخیره سازی داده ها،بصورت Column Store را نمایش میدهد:
مطابق شکل،ستونهای مربوط به هر Row،همگی در یک صفحه (Page) یکسان ذخیره شده اند. به عنوان مثال ستون C1 که مربوط به سطر اول (Row1) میباشد، با ستون C1 که مربوط به سطر دوم (Row2) میباشد، در یک ستون و در یک صفحه (Page1) ذخیره شده اند، و الی آخر ...
سئوال: یکبار دیگر به هردو شکل با دقت نگاهی بیاندازید، عمده تفاوت آنها در چیست؟
جواب: درست حدس زدید، تفاوت بارز بین دو روش Column Store و Row Store در نحوه ذخیره سازی دادهها میباشد. بطور مثال، فرض کنید،در روش ذخیره سازی Row Store، به دنبال مقادیری از ستون C2 میباشید، SQL Server میبایست کل رکوردهای جدول (منظور همه Rowها در همه Page ها)را Scan نماید، تا مقادیر مربوط به ستون C2 را بدست آورد.درحالیکه در روش ذخیره سازی Column Store، جهت یافتن مقادیر ستون C2، نیازی به Scan نمودن کل جدول نیست،بلکه SQL Server فقط به Scan نمودن ستون دوم (C2) یا Page2 بسنده مینماید.همین امر باعث افزایش چندین برابری، زمان پاسخگویی به هر Query میشود.
سئوال: در روش ذخیره سازی Column Store، چگونه مصرف حافظه بهینه میشود؟
جواب: واضح است، که در روش SQL Server، Row Store مجبور است، برای بدست آوردن دادههای مورد نظرتان،کل اطلاعات جدول را وارد حافظه نماید(اطلاعات اضافه ای که به هیچ وجه بدرد، نتیجه پرس و جوی شما نمیخورد)، و شروع به Scan دادههای مد نظر شما مینماید.بطوریکه در روش SQL Server، Column Store، فقط ستون دادههای مورد پرس و جو را در حافظه قرار میدهد.(در واقع فقط داده هایی را در حافظه قرار میدهد، که شما به آن نیاز دارید)،بنابراین،طبیعی است که در روش Column Store مقدار حافظه کمتری نسبت به روش Row Store در هنگام اجرای Query استفاده میشود. به عبارت دیگر میتوان گفت که در روش Column Store به دلیل، به حداقل رساندن استفاده از Disk I/o سرعت و زمان پاسخگویی به پرس و جوها چندین برابر میشود.
برای درک بیشتر Row Store و Column Store مثالی میزنیم:
فرض کنید،قصد بدست آوردن ستونهای C1 و C2 از جدول A را داریم، بنابراین خواهیم داشت:
Select C1, C2 from A
روش Row Store:
در این روش همه صفحات دیسک (مربوط به جدول A) درون حافظه قرار داده میشود، یعنی علاوه بر ستونهای C1 و C2، اطلاعات مربوط به ستونهای C3 و C4 نیز درون حافظه قرار میگیرد،بطوریکه مقادیر ستونهای C3 و C4 به هیچ وجه مورد قبول ما نیست، و در خروجی پرس و جوی ما تاثیری ندارد، و فقط بی جهت حافظه اشغال مینماید.
روش Column Store:
در این روش فقط صفحات مروبط به ستون C1 و C2 در حافظه قرار میگیرد.(منظور Page1 و Page2 میباشد) بنابراین فقط اطلاعات مورد نیاز در خروجی، در حافظه قرار میگیرد.
- از دیگر مزایای استفاده از روش Column Store، فشرده سازی داده میباشد،برای درک بیشتر توضیح میدهم:
چه موقع میتوانیم از Column Store استفاده نماییم:
در تعریف Column Store گفته بودم، روش فوق، جهت بهبود بخشیدن به زمان و سرعت پاسخگویی به Queryهای اجرا شده روی دیتابیسهای با حجم داده ای بسیار بالا(Data Warehouse ) میباشد، به بیان سادهتر Column Store را روی دیتابیسهای offline یا دیتابیسهایی که صرفا جهت گزارش گیری مورد استفاده قرار میگیرند، تنظیم مینمایند.در واقع با تنظیم Column Store Index روی Databaseهای بزرگ مانند Databaseهای بانکها که حجم داده ای میلیونی در جداول آنها وجود دارد، سرعت پاسخگویی Query ها، چندین برابر افزایش مییابد.
- در یک جدول میتوانید، هم Column Store Index داشته باشید و هم یک Row Store Index (منظور یک Clustered Index می باشد)
- Syntax برای ایجاد Column Store Index به شرح ذیل میباشد:
CREATE [ NONCLUSTERED ] COLUMNSTORE INDEX index_name ON <object> ( column [ ,...n ] ) [ WITH ( <column_index_option> [ ,...n ] ) ] [ ON { { partition_scheme_name ( column_name ) } | filegroup_name | "default" } ] [ ; ] <object> ::= { [database_name. [schema_name ] . | schema_name . ] table_name { <column_index_option> ::= { DROP_EXISTING = { ON | OFF } | MAXDOP = max_degree_of_parallelism }
- یک Column Store Index میبایست از نوع NONCLUSTERED باشد.
CREATE NONCLUSTERED COLUMNSTORE INDEX [IX_MyFirstName_ColumnStore] ON [Test] (Firstname)
- زمانی که در یک جدول، یک Column Store Index ایجاد نماییم، جدول ما در حالت Read-only قرار میگیرد، بطوریکه از آن پس اختیار Delete،Update و Insert روی جدول فوق را نخواهیم داشت. برای اینکه بتوانید عملیات Insert، Update یا Delete را انجام دهید، میبایست Column Store Index جدول مربوطه را Disable نمایید، و برای فعال نمودن Column Store Index، میبایست آن را Rebuild نمایید، با کلیک راست روی ایندکس ایجاد شده در SQL Server2012 موارد Disable و Rebuild قابل مشاهده میباشد.
ALTER INDEX [IX_MyFirstName_ColumnStore] ON [Test] DISABLE ALTER INDEX [IX_MyFirstName_ColumnStore] ON [Test] Rebuild
- بیشتر از یک Column Store Index نمیتوانید روی یک جدول ایجاد نمایید.
- در صورتی که تمایل داشته باشید بوسیله Alter ، نوع فیلدی (Type)، را که Column Store Index روی آنها اعمال گردیده است، تغییر دهید، در ابتدا میبایست Column Store Index، خود را Drop یا حذف نمایید، سپس عملیات Alter را اعمال کنید، در غیر اینصورت با خطای SQL Server مواجه میشوید.
- یک Column Store Index میتواند روی 1024 ستون در یک جدول اعمال گردد.
- یک Column Store Index نمی توانند، Unique باشد و نمیتوان از آن به عنوان Primary Key یا Foreign Key استفاده نمود.
چک لیست تهیه یک برنامه ASP.NET MVC
گزارش خطا
مدیریت تغییرات گریدی از اطلاعات به کمک استفاده از الگوی واحد کار مشترک بین ViewModel و لایه سرویس
در این صفحه با کلیک بر روی دکمه به علاوه، یک ردیف به ردیفهای موجود اضافه شده و در اینجا میتوان اطلاعات کاربر جدیدی به همراه سطح دسترسی او را وارد و ذخیره کرد و یا حتی اطلاعات کاربران موجود را ویرایش نمود. اگر بخواهیم مانند مراحلی که در قسمت قبل در مورد تعریف یک صفحه جدید در برنامه توضیح داده شد، عمل کنیم، به صورت خلاصه به ترتیب ذیل عمل شده است:
1) ایجاد صفحه تغییر مشخصات کاربر
ابتدا صفحه Views\Admin\AddNewUser.xaml به پروژه ریشه که Viewهای برنامه در آن تعریف میشوند، اضافه شده است. به همراه دو دکمه و یک ListView که تطابق بهتری با قالب متروی مورد استفاده دارد.
2) تنظیم اعتبارسنجی صفحه اضافه شده
مرحله بعد تعریف هر صفحهای در سیستم، مشخص سازی وضعیت دسترسی به آن است:
/// <summary> /// افزودن و مدیریت کاربران سیستم /// </summary> [PageAuthorization(AuthorizationType.ApplyRequiredRoles, "IsAdmin, CanAddNewUser")]
3) تغییر منوی برنامه جهت اشاره به صفحه جدید
در ادامه در فایل منوی برنامه Views\MainMenu.xaml تعریف دسترسی به صفحه Views\Admin\AddNewUser.xaml قید شده است:
<Button Style="{DynamicResource MetroCircleButtonStyle}" Height="55" Width="55" Command="{Binding DoNavigate}" CommandParameter="\Views\Admin\AddNewUser.xaml" Margin="2"> <Rectangle Width="28" Height="17.25"> <Rectangle.Fill> <VisualBrush Stretch="Fill" Visual="{StaticResource appbar_user_add}" /> </Rectangle.Fill> </Rectangle> </Button>
4) ایجاد ViewModel متناظر با صفحه
مرحله نهایی تعریف صفحه AddNewUser، افزودن ViewModel متناظر با آن است که سورس کامل آنرا در فایل ViewModels\Admin\AddNewUserViewModel.cs پروژه Infrastructure میتوانید ملاحظه کنید.
نکته مهم این ViewModel، ارائه خاصیت لیست کاربران از نوع ObservableCollection به View و گرید برنامه است:
public ObservableCollection<User> UsersList { set; get; }
/// <summary> /// جهت مقاصد انقیاد دادهها در دبلیو پی اف طراحی شده است /// لیستی از کاربران سیستم را باز میگرداند /// </summary> /// <param name="count">تعداد کاربر مد نظر</param> /// <returns>لیستی از کاربران</returns> public ObservableCollection<User> GetSyncedUsersList(int count = 1000) { _users.OrderBy(x => x.FriendlyName).Take(count) .Load(); // For Databinding with WPF. // Before calling this method you need to fill the context by using `Load()` method. return _users.Local; }
در اینجا از قابلیت خاصیتی به نام Local که یک ObservableCollection تحت نظر EF را بازگشت میدهد، استفاده شده است. برای استفاده از این خاصیت، ابتدا باید کوئری خود را تهیه و سپس متد Load را بر روی آن فراخوانی کرد. سپس خاصیت Local بر اساس اطلاعات کوئری قبلی پر و مقدار دهی خواهد شد.
علت انتخاب نام Synced برای این متد، تحت نظر بودن اطلاعات خاصیت Local است تا زمانیکه Context تعریف شده زنده نگه داشته شود. به همین جهت در برنامه جاری از روش زنده نگه داشتن Context به ازای یک ViewModel استفاده شده است.
به Context، توسط اینترفیس IUnitOfWork تزریق شده در سازنده کلاس ViewModel میتوان دسترسی یافت. چون در اینجا از تزریق وابستگیها استفاده شده است، وهلهای که IUnitOfWork کلاس AddNewUserViewModel را تشکیل میدهد، دقیقا همان وهلهای است که در کلاس UsersService لایه سرویس استفاده شده است. در نتیجه، در گرید برنامه هر تغییری اعمال شود، تحت نظر IUnitOfWork خواهد بود و صرفا با فراخوانی متد uow.ApplyAllChanges آن، کلیه تغییرات تمام ردیفهای تحت نظر EF به صورت خودکار در بانک اطلاعاتی درج و یا به روز خواهند شد.
همچنین در مورد ViewModelContextHasChanges نیز در قسمت قبل بحث شد. در اینجا پیاده سازی کننده آن صرفا خاصیت uow.ContextHasChanges است. به این ترتیب اگر کاربر، تغییری را در صفحه داده باشد و بخواهد به صفحه دیگری رجوع کند، با پیام زیر مواجه خواهد شد:
از همین خاصیت برای فعال و غیرفعال کردن دکمه ذخیره سازی اطلاعات نیز استفاده شده است:
/// <summary> /// فعال و غیرفعال سازی خودکار دکمه ثبت /// این متد به صورت خودکار توسط RelayCommand کنترل میشود /// </summary> private bool canDoSave() { // آیا در حین نمایش صفحهای دیگر باید به کاربر پیغام داد که اطلاعات ذخیره نشدهای وجود دارد؟ return ViewModelContextHasChanges; }
/// <summary> /// رخداد ذخیره سازی اطلاعات را دریافت میکند /// </summary> public RelayCommand DoSave { set; get; }
DoSave = new RelayCommand(doSave, canDoSave);
این بررسی نیز بسیار سبک و سریع است. از این جهت که تغییرات Context در حافظه نگهداری میشوند و مراجعه به آن مساوی مراجعه به بانک اطلاعاتی نیست.
using System.Data.Entity; using System.Threading.Tasks; using Microsoft.AspNet.Identity.EntityFramework; using SmartMarket.Core.Domain.Members; using SmartMarket.Data; namespace SmartMarket.Services.Members { /// <summary> /// The ApplicationUserStore Class /// </summary> public class ApplicationUserStore : UserStore<User, Role, int, UserLogin, UserRole, UserClaim>, IApplicationUserStore { #region Fields (1) private readonly IDbSet<User> _userStore; #endregion Fields #region Constructors (2) /// <summary> /// Initializes a new instance of the <see cref="ApplicationUserStore" /> class. /// </summary> /// <param name="dbContext">The database context.</param> public ApplicationUserStore(DbContext dbContext) : base(dbContext) { } /// <summary> /// Initializes a new instance of the <see cref="ApplicationUserStore"/> class. /// </summary> /// <param name="context">The context.</param> public ApplicationUserStore(IdentityDbContext context) : base(context) { _userStore = context.Set<User>(); } #endregion Constructors #region Methods (2) // Public Methods (2) /// <summary> /// Adds to previous passwords asynchronous. /// </summary> /// <param name="user">The user.</param> /// <param name="password">The password.</param> /// <returns></returns> public Task AddToPreviousPasswordsAsync(User user, string password) { user.PreviousUserPasswords.Add(new PreviousPassword { UserId = user.Id, PasswordHash = password }); return UpdateAsync(user); } /// <summary> /// Finds the by identifier asynchronous. /// </summary> /// <param name="userId">The user identifier.</param> /// <returns></returns> public override Task<User> FindByIdAsync(int userId) { return Task.FromResult(_userStore.Find(userId)); } #endregion Methods /// <summary> /// Creates the asynchronous. /// </summary> /// <param name="user">The user.</param> /// <returns></returns> public override async Task CreateAsync(User user) { await base.CreateAsync(user); await AddToPreviousPasswordsAsync(user, user.PasswordHash); } } }
گزارش خطا
برای ایجاد «خواص الحاقی» قبلا در سایت مطلب ایجاد «خواص الحاقی» تهیه شدهاست. در این مطلب قصد داریم راه حل ارائه شدهی در مطلب مذکور را با یک TypeDescriptionProvider سفارشی ترکیب کرده تا به صورت یکدست، از طریق TypeDescriptor بتوان به آن خواص نیز دسترسی داشته باشیم.
فرض کنید در یک سیستم Modular Monolith، نیاز جدیدی به دست شما رسیده است که به شرح زیر میباشد:
نیاز داریم در گریدی از صفحهی X مربوط به «مؤلفه 1»، ستونی جدید را اضافه کنید و دیتای مربوط به این ستون، توسط «مؤلفه 2» مهیا خواهد شد.
- قبلا «مؤلفه 2» ارجاعی را به «مؤلفه 1» داده است؛ لذا امکان ارجاع معکوس را در این حالت، نداریم.
- «مؤلفه 1» باید بتواند مستقل از «مؤلفه 2» نیز توزیع شده و کار کند؛ لذا این نیاز برای زمانی است که «مؤلفه 2» برای توزیع در Component Model ما وجود داشته باشد.
- نمیخواهیم در آینده برای نیازهای مشابه در همان صفحهی X، تغییر جدیدی را در «مؤلفه 1» داشته باشیم (اضافه کردن خصوصیت مورد نظر به مدل نمایشی یا اصطلاحا ویو-مدل متناظر با گرید در در زمان طراحی، جواب مساله نمیباشد)
- میخواهیم به یک طراحی با Loose Coupling (اتصال سست و ضعیف، وابستگی ضعیف) دست پیدا کنیم.
در این حالت «مؤلفه 1» بدون آگاهی از سایر مؤلفهها، همهی پیاده سازیهای IExtraColumnConenvtion را در زمان اجرا یافته و از آنها برای ایجاد ستونهای جدید، استفاده خواهد کرد.
واسط مذکور به شکل زیر میباشد:
public interface IConvention { } public interface IExtraColumnConvention<T> : IConvention { string Name { get; } string Title { get; } void Populate(IEnumerable<T> list); }
البته این واسط میتواند جزئیات بیشتری را هم شامل شود.
گام اول: طراحی TypeDescriptionProvider
در .NET به دو طریق میتوان به متادیتای یک Type دسترسی داشت:
- استفاده از API Reflection موجود در فضای نام System.Reflection
- کلاس TypeDescriptor
به طور کلی هدف از این کلاس در دات نت، ارائه اطلاعاتی در خصوص یک وهله از جمله: Attributeها، Propertyها، Eventهای آن و غیره، میباشد. هنگام استفاده از Reflection، اطلاعات بدست آمده از Type، به دلیل اینکه بعد از کامپایل نمیتوانند تغییر کنند، لذا قابلیت توسعه پذیری را هم ندارند. در مقابل، با استفاده از کلاس TypeDescriptor این توسعه پذیری را برای وهلههای مختلف میتوانید داشته باشید.
برای مهیا کردن متادیتای سفارشی (در اینجا اطلاعات مرتبط با خصوصیات الحاقی) برای TypeDescriptor، نیاز است یک TypeDescriptionProvider سفارشی را طراحی کنیم.
/// <summary> /// Use this provider when you need access ExtraProperties with TypeDescriptor.GetProperties(instance) /// </summary> public class ExtraPropertyTypeDescriptionProvider<T> : TypeDescriptionProvider where T : class { private static readonly TypeDescriptionProvider Default = TypeDescriptor.GetProvider(typeof(T)); public ExtraPropertyTypeDescriptionProvider() : base(Default) { } public override ICustomTypeDescriptor GetTypeDescriptor(Type instanceType, object instance) { var descriptor = base.GetTypeDescriptor(instanceType, instance); return instance == null ? descriptor : new ExtraPropertyCustomTypeDescriptor(descriptor, instance); } private sealed class ExtraPropertyCustomTypeDescriptor : CustomTypeDescriptor { //... } }
در تکه کد بالا، ابتدا تامین کنندهی پیشفرض مرتبط با نوع جنریک مورد نظر را یافته و به عنوان تامین کنندهی پایه معرفی کردهایم. سپس برای معرفی CustomTypeDescritpr باید متد GetTypeDescriptor را بازنویسی کنیم. در اینجا لازم است برای معرفی متادیتا مرتبط با یک نوع، یک پیاده سازی از واسط ICustomTypeDescriptor را ارائه کنیم:
private sealed class ExtraPropertyCustomTypeDescriptor : CustomTypeDescriptor { private readonly IEnumerable<ExtraPropertyDescriptor<T>> _instanceExtraProperties; public ExtraPropertyCustomTypeDescriptor(ICustomTypeDescriptor defaultDescriptor, object instance) : base(defaultDescriptor) { _instanceExtraProperties = instance.ExtraPropertyList<T>(); } public override PropertyDescriptorCollection GetProperties(Attribute[] attributes) { var properties = new PropertyDescriptorCollection(null); foreach (PropertyDescriptor property in base.GetProperties(attributes)) { properties.Add(property); } foreach (var property in _instanceExtraProperties) { properties.Add(property); } return properties; } public override PropertyDescriptorCollection GetProperties() { return GetProperties(null); } }
public static class ExtraProperties { //... public static IEnumerable<ExtraPropertyDescriptor<T>> ExtraPropertyList<T>(this object instance) where T : class { if (!PropertyCache.TryGetValue(instance, out var properties)) throw new KeyNotFoundException($"key: {instance.GetType().Name} was not found in dictionary"); return properties.Select(p => new ExtraPropertyDescriptor<T>(p.PropertyName, p.PropertyValueFunc, p.SetPropertyValueFunc, p.PropertyType, p.Attributes)); } }
public sealed class ExtraPropertyDescriptor<T> : PropertyDescriptor where T : class { private readonly Func<object, object> _propertyValueFunc; private readonly Action<object, object> _setPropertyValueFunc; private readonly Type _propertyType; public ExtraPropertyDescriptor( string propertyName, Func<object, object> propertyValueFunc, Action<object, object> setPropertyValueFunc, Type propertyType, Attribute[] attributes) : base(propertyName, attributes) { _propertyValueFunc = propertyValueFunc; _setPropertyValueFunc = setPropertyValueFunc; _propertyType = propertyType; } public override void ResetValue(object component) { } public override bool CanResetValue(object component) => true; public override object GetValue(object component) => _propertyValueFunc(component); public override void SetValue(object component, object value) => _setPropertyValueFunc(component, value); public override bool ShouldSerializeValue(object component) => true; public override Type ComponentType => typeof(T); public override bool IsReadOnly => _setPropertyValueFunc == null; public override Type PropertyType => _propertyType; }
[TypeDescriptionProvider(typeof(ExtraPropertyTypeDescriptionProvider<Person>))] private class Person { public string Name { get; set; } public string Family { get; set; } }
[Test] public void Should_TypeDescriptor_GetProperties_Returns_ExtraProperties_And_PredefinedProperties() { //Arrange var rabbal = new Person {Name = "GholamReza", Family = "Rabbal"}; const string propertyName = "Title"; const string propertyValue = "Software Engineer"; //Act rabbal.ExtraProperty(propertyName, propertyValue); var title = TypeDescriptor.GetProperties(rabbal).Find(propertyName, true); //Assert rabbal.ExtraProperty<string>(propertyName).ShouldBe(propertyValue); title.ShouldNotBeNull(); title.GetValue(rabbal).ShouldBe(propertyValue); }
گام دوم: استفاده از IExtraColumnConvention برای نمایش ستونهای الحاقی
public class Column4Convention : IExtraColumnConvention<Product> { public string Name => "Column4"; public string Title => "Column 4" public void Populate(IEnumerable<Product> list) { //TODO: forEach on list and set ExtraProperty // item.ExtraProperty(Name,value) // item.ExtraProperty(Name,(obj)=> value) // item.ExtraProperty(Name,(obj)=> value, (obj,value)=>) } } public class Column2Convention : IExtraColumnConvention<Product> { public string Name => "Column2"; public string Title => "Column 2" public void Populate(IEnumerable<Product> list) { //TODO: forEach on list and set ExtraProperty } } public class Column3Convention : IExtraColumnConvention<Product> { public string Name => "Column3"; public string Title => "Column 3" public void Populate(IEnumerable<Product> list) { //TODO: forEach on list and set ExtraProperty } }
سپس این پیادهسازیها از طریق مکانیزمی مانند معرفی آنها به یک IoC Container، توسط میزبان (مؤلفه 1) قابل دسترسی خواهد بود. در نهایت میزبان، قبل از نمایش محصولات، به شکل زیر عمل خواهد کرد:
var products = _productService.PagedList(page:1, pageSize:10); var columns = _provider.GetServices<IExtraColumnConvention<Product>>(); foreach(var column in columns) { column.Populate(products); }
مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger - قسمت سوم - تکمیل مستندات یک API با کامنتها
استفاده از 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 را که در قسمت دوم به آن اشاره کردیم، بررسی خواهیم کرد.
دریافت اطلاعات به صورت ajax از یک فایل متنی
فرض کنید که اطلاعات در یک فایل txt به صورت اشیاء جاوا اسکریپتی ذخیره شده اند، و این فایل بر روی سرور قرار دارد. میخواهیم از این فایل به عنوان منبع داده استفاده کرده و اطلاعات درون آن را به صورت ajax دریافت کرده و در یک جدول html تزریق کنیم. خوشبختانه با استفاده از امکاناتی که این پلاگین تهیه کرده است این کار به سادگی امکان پذیر است.
همان طور که در اینجا بیان شده است ، فرض کنید که جدولی داشته باشیم و بخواهیم اطلاعات راجع به مرورگرهای مختلف را در آن نمایش دهیم. قصد داریم این جدول شامل قسمتهای header و footer و نیز body باشد، بدین صورت:
<table id="browsers-grid"> <thead> <tr> <th width="20%">موتور رندرگیری</th> <th width="25%">مرورگر</th> <th width="25%">پلتفرم (ها)</th> <th width="15%">نسخه موتور</th> <th width="15%">نمره css</th> </tr> </thead> <tbody> </tbody> <tfoot> <tr> <th>موتور رندرگیری</th> <th>مرورگر</th> <th>پلتفرم (ها)</th> <th>نسخه موتور</th> <th>نمره css</th> </tr> </tfoot> </table>
داده هایی که باید در بدنه جدول قرار بگیرند، در یک فایل متنی روی سرور قرار دارند. محتویات این فایل چیزی شبیه زیر است:
{ "aaData": [ {"engine":"Trident", "browser":"Internet Explorer 4.0", "platform":"Win95+", "version":"4", "grade":"X"}, {"engine":"Trident", "browser":"Internet Explorer 5.0", "platform":"Win95+", "version":"5", "grade":"C"}, {"engine":"Trident", "browser":"Internet Explorer 5.5", "platform":"Win95+", "version":"5.5", "grade":"A"} ] }
اسکریپتی که دادهها را از فایل متنی خوانده و آنها را در جدول قرار میدهد هم بدین صورت خواهد بود:
$(document).ready(function () { $('#browsers-grid').dataTable({ "sAjaxSource": "datasource/objects.txt", "bProcessing": true, "aoColumns": [ { "mDataProp": "engine" }, { "mDataProp": "browser" }, { "mDataProp": "platform" }, { "mDataProp": "version" }, { "mDataProp": "grade" } ] }); });
sAjaxSource : رشته
نوع داده ای که قبول میکند رشته ای و بیان کننده آدرسی است که دادهها باید از آنجا دریافت شوند. در اینجا دادهها در فایل متنی objects.txt در پوشه datasource قرار دارند.
bProcessing : بولین
نوع دادههای قابل قبول این خصوصیت true یا false هست و بیان کننده این است که یک پیغام loading تا زمانی که دادهها دریافت شوند و در جدول قرار بگیرند نمایش داده شوند یا خیر.
تنظیم کردن گزینههای اضافی دیگر
sAjaxDataProp : رشته
همان طور که گفتیم در فایل متنی که حاوی اشیاء json بود ، این اشیاء را به متغیری به اسم aaData منتسب کردیم. این نام را میتوان تغییر داد مثلا فرض کنید در فایل متنی دادهها به متغیری به اسم data منتسب شده اند:
{ "data": [ {"engine":"Trident", "browser":"Internet Explorer 4.0", "platform":"Win95+", "version":"4", "grade":"X"}, {"engine":"Trident", "browser":"Internet Explorer 5.0", "platform":"Win95+", "version":"5", "grade":"C"}, {"engine":"Trident", "browser":"Internet Explorer 5.5", "platform":"Win95+", "version":"5.5", "grade":"A"} ] }
"sAjaxDataProp": "data"
{ "data": { "inner": [...] } }
"sAjaxDataProp": "data.inner"
sPaginationType: رشته
نحوه صفحه بندی و حرکت بین صفحات مختلف را بیان میکند. اگر با two_buttonمقدار دهی شود (مقدار پیش فرض) حرکت بین صفحات مختلف به وسیله دکمههای Next و Previous امکان پذیر خواهد بود. اگر با full_numbersمقدار دهی شود حرکت بین صفحات با دکمههای Next و Previous ، و همچنین دکمههای First و Last و نیز شماره صفحه فعلی و دو صفحه بعدی و دو صفحه قبلی قابل انجام است.
bLengthChange: بولین
بیان میکند کاربر بتواند اندازه صفحه را تغییر دهید یا نه. به صورت پیش فرض این گزینه true است. اگر آن به false مقدار دهی شود لیست بازشونده مربوط به اندازه صفحه مخفی خواهد شد.
aLengthMenu : آرایه یک بعدی یا دو بعدی
به صورت پیش فرض در لیست باز شونده مربوط به تعداد رکوردهای قابل نمایش در هر صفحه اعداد 10 ، 25 ، 50 ، و 100 قرار دارند.
در صورتی که بخواهیم این گزینهها را تغییر دهیم باید خصوصیت aLengthMenu را مقدار دهی کنیم. اگر مقداری که به این خصوصیت میدهیم یک آرایه یک بعدی باشد، مثلا
"aLengthMenu": [25, 50, 100, -1],
"aLengthMenu": [[25, 50, 100, -1], ["همه", "صد", "پنجاه", "بیست و پنج"]],
iDisplayLength: عدد صحیح
تعداد رکوردهای قابل نمایش در هر صفحه هنگامی که دادهها در جدول ریخته میشوند را معین میکند. میتوانید این را مقداری بدهید که در خصوصیت aLengthMenu ذکر نشده است، مثلا 28 تا.
sDom : رشته
پلاگین DataTables به صورت پیش فرض لیست بازشونده اندازه صفحه و کادر متن مربوط به جستجو را در بالای جدول دادهها اضافه میکند، و نیز اطلاعات دیگر و همچنین امکانات مربوط به صفحه بندی را به قسمت پایین جدول اضافه میکند. شما میتوانید موقعیت این عناصر را با استفاده از پارامتر sDom تغییر دهید.
نحو (syntax) مقداری که پارامتر sDom قبول میکند مقداری عجیب و غریب است، مثلا:
'<"top"iflp<"clear">>rt<"bottom"iflp<"clear">>'
این خط بیان میکند که در قسمت بالای جدول یک تگ div با کلاس top قرار بگیرد. در این تگ قسمت اطلاعات (یعنی Showing x to xx from xxx entries) (با حرف i) ، کادر جستجو (با حرف f) ، لیست بازشونده مربوط به اندازه صفحه (با حرف l) ، و نیز قسمت صفحه بندی (با حرف p)قرار خواهند گرفت. در انتهای تگ div با کلاس top، یک تگ div با کلاس clear قرار خواهد گرفت. بعد قسمت مربوط به پیغام loading (با حرف r) و بعد با حرف t جدول حاوی دادهها قرار میگیرد. در نهایت یک تگ div با کلاس bottom قرار میگیرد و با حرفهای i ، و f ، و l و p درون آن قسمتهای اطلاعات ، کادرجستجو، لیست بازشونده اندازه صفحه و نیز قسمت صفحه بندی قرار خواهد گرفت و در نهایت یک تگ div با کلاس clear قرار خواهد گرفت.
حرفهایی که در sDom معنی خاصی میدهند :
- l سر حرف Length Changing برای لیست بازشونده مربوط به اندازه صفحه
- f سر حرف Filtering input برای قسمت کادر جستجو
- t سرحرف table برای جدول حاوی داده ها
- i سر حرف information برای قسمت Showing x to xx from xxx entries
- p سر حرف pagination برای قسمت صفحه بندی
- r حرف دوم pRocessing برای قسمت پیغام قبل از بار کردن دادههای جدول (قسمت loading)
- H و F که مربوط به themeهای jQuery UI میشوند که بعدا درباره آنها توضیح داده میشود.
همچنین بین علامتهای کوچکتر (>) و بزرگتر (<) یعنی اگر چیزی بیاید در یک تگ div قرار خواهد گرفت. اگر بخواهیم div ی بسازیم و به آن کلاس بدهیم از نحو زیر استفاده خواهیم کرد:
'<"class" and '>'
'<"#id" and '>'
کدهای نهایی این مثال را از DataTables-DoteNetTips-Tutorial-03.zip دریافت کنید.