نظرات مطالب
احراز هویت و اعتبارسنجی کاربران در برنامه‌های Angular - قسمت ششم - کار با منابع محافظت شده‌ی سمت سرور
یک نکته‌ی تکمیلی: روش دیگری برای بهبود کنترل نمایش و مخفی سازی قسمت‌های مختلف صفحه

کدهای یک دایرکتیو سفارشی نمایش و یا مخفی سازی قسمت‌های مختلف صفحه را بر اساس سطوح دسترسی کاربر جاری، در IsVisibleForAuthUserDirective مشاهده کردید. روش دیگر انجام اینکار، نوشتن یک دایرکتیو ساختاری شبیه به ngIf توکار خود Angular است. کاری که ngIf انجام می‌دهد، مخفی کردن یک المان در صفحه نیست؛ بلکه کل آن‌را از DOM حذف می‌کند.

نکته‌ی اصلی پیاده سازی یک دایرکتیو ساختاری

اگر به سازنده‌ی IsVisibleForAuthUserDirective دقت کنید، تزریق وابستگی ElementRef را داریم:
@Directive({
  selector: "[isVisibleForAuthUser]"
})
export class IsVisibleForAuthUserDirective implements OnInit, OnDestroy {
  constructor(private elem: ElementRef, private authService: AuthService) { }
به این ترتیب Angular به صورت خودکار امکان دسترسی به المان جاری را با تزریق آن در سازنده‌ی کلاس، میسر می‌کند.
برای ایجاد یک دایرکتیور ساختاری، نیاز است از تزریق TemplateRef و ViewContainerRef استفاده کرد:
@Directive({
selector: "[hasAuthUserViewPermission]"
})
export class HasAuthUserViewPermissionDirective implements OnInit, OnDestroy {

  constructor(
  private templateRef: TemplateRef<any>,
  private viewContainer: ViewContainerRef,
  private authService: AuthService
) { }
در این حالت Angular تنها زمانی این وابستگی‌ها را به سازنده‌ی کلاس تزریق می‌کند که پیش از نام این دایرکتیو، یک * قرار دهید (مانند ngIf توکار آن):
<div *hasAuthUserViewPermission="['Admin','User']">
    *hasAuthUserViewPermission="['Admin','User']"
</div>
پس از آن می‌توان از viewContainer، برای نمایش المان و یا قالب مدنظر:
 this.viewContainer.createEmbeddedView(this.templateRef);
و یا حذف کامل آن المان از DOM کمک گرفت:
 this.viewContainer.clear();

اگر این نکات را کنار هم قرار دهیم و کدهای IsVisibleForAuthUserDirective فوق را بر این اساس اصلاح کنیم، به قطعه کد زیر می‌رسیم:
import { Directive, Input, OnDestroy, OnInit, TemplateRef, ViewContainerRef } from "@angular/core";
import { Subscription } from "rxjs/Subscription";

import { AuthService } from "./../../core/services/auth.service";

@Directive({
  selector: "[hasAuthUserViewPermission]"
})
export class HasAuthUserViewPermissionDirective implements OnInit, OnDestroy {
  private isVisible = false;
  private requiredRoles: string[] | null = null;
  private subscription: Subscription | null = null;

  @Input()
  set hasAuthUserViewPermission(roles: string[] | null) {
    this.requiredRoles = roles;
  }

  // Note, if you don't place the * in front, you won't be able to inject the TemplateRef<any> or ViewContainerRef into your directive.
  constructor(
    private templateRef: TemplateRef<any>,
    private viewContainer: ViewContainerRef,
    private authService: AuthService
  ) { }

  ngOnInit() {
    this.subscription = this.authService.authStatus$.subscribe(status => this.changeVisibility(status));
    this.changeVisibility(this.authService.isAuthUserLoggedIn());
  }

  ngOnDestroy(): void {
    if (this.subscription) {
      this.subscription.unsubscribe();
    }
  }

  private changeVisibility(status: boolean) {
    const isInRoles = !this.requiredRoles ? true : this.authService.isAuthUserInRoles(this.requiredRoles);
    if (isInRoles && status) {
      if (!this.isVisible) {
        this.viewContainer.createEmbeddedView(this.templateRef);
        this.isVisible = true;
      }
    } else {
      this.isVisible = false;
      this.viewContainer.clear();
    }
  }
}

سپس تعریف آن‌را به قسمت‌های declarations و exports مربوط به SharedModule اضافه می‌کنیم:
import { HasAuthUserViewPermissionDirective } from "./directives/has-auth-user-view-permission.directive";

@NgModule({
  declarations: [
    HasAuthUserViewPermissionDirective
  ],
  exports: [
    HasAuthUserViewPermissionDirective
  ]
})
export class SharedModule {}

اکنون ماژول Dashboard برای استفاده‌ی از این امکانات تنها کافی است SharedModule را دریافت کند (یا هر ماژول دیگری نیز به همین ترتیب است):
import { SharedModule } from "../shared/shared.module";
@NgModule({
  imports: [
    SharedModule
  ]
})
export class DashboardModule { }

پس از آن برای مخفی سازی یک المان از دید کاربران وارد نشده‌ی به سیستم، فقط کافی است دایرکتیو ساختاری hasAuthUserViewPermission را به المان اعمال کنیم:
<div *hasAuthUserViewPermission="">
    *hasAuthUserViewPermission=""
</div>
و یا اگر نیاز به اعمال نقش‌ها نیز وجود داشت می‌توان به صورت زیر عمل کرد:
<div *hasAuthUserViewPermission="['Admin','User']">
    *hasAuthUserViewPermission="['Admin','User']"
</div>

خلاصه‌ی این تغییرات به کدهای نهایی این سری اعمال شده‌اند.
مطالب
آموزش (jQuery) جی کوئری 6#
در ادامه مطلب قبلی  آموزش (jQuery) جی کوئری 5#  به ادامه بحث  می‌پردازیم.
در پست‌های قبلی مروری بر jQuery داشته و در چند پست انواع روش‌های انتخاب عناصر صفحه وب را توسط jQuery بررسی کردیم. در پست‌های آینده با مباحث پیشرفته‌تری همچون انجام عملیاتی روی المانهای انتخاب شده، خواهیم پرداخت؛ امید است مفید واقع شود.


٢ -٢ - ایجاد  عناصر HTML جدید
گاهی اوقات نیاز می‌شود که یک یا چند عنصر جدید به صفحه‌ی در حال اجرا اضافه شوند. این حالت می‌تواند به سادگی قرار گرفتن یک متن در جایی از صفحه و یا به پیچیدگی ایجاد و نمایش یک جدول حاوی اطلاعات دریافت شده از بانک اطلاعاتی باشد.
ایجاد عناصر به صورت پویا در یک صفحه در حال اجرا کار ساده ای برای jQuery می‌باشد، زیرا همانطور که در پست آموزش (jQuery) جی کوئری 1#  مشاهده کردیم ()$ با دریافت دستور ساخت یک عنصر HTML آن را در هر زمان ایجاد می‌کند، دستور زیر :
$("<div>Hello</div>")
یک عنصر div ایجاد می‌کند و آماده افزودن آن به صفحه در هر زمان می‌باشد.تمامی توابع و متدهایی را که تاکنون بررسی کردیم قابل اعمال بروی اینگونه اشیا نیز می‌باشند. شاید در ابتدا ایجاد عناصر به این شکل خیلی مفید به نظر نرسد، اما زمانی که بخواهیم کارهای حرفه ای‌تری انجام دهیم؛ برای مثال کار با AJAX، خواهیم دید که تا چه اندازه ایجاد عناصر به این روش می‌تواند مفید باشد.
دقت کنید که یک راه کوتاهتر نیز برای ایجاد یک عنصر <div> خالی وجود دارد که به شکل زیر است:
$("<div>")
//  همه اینها معادل هستند 
$("<div></div>")
$("<div/>")
اما برای ایجاد عناصری که خود می‌توانند حاوی عناصر دیگر باشند استفاده از راههای کوتاه توصیه نمی‌شود مانند نوشتن تگ <script> .اما راههای زیادی برای انجام اینکار وجود دارد.
برای اینکه مزه اینکار را بچشید بد نیست نگاهی به مثال زیر بیندازید (نگران قسمت‌های نامفهوم نباشید به مرور با آنها آشنا خواهیم شد):
$("<div class='foo'>I have foo!</div><div>I don't</div>")
     .filter(".foo").click(function() {
          alert("I'm foo!");
      }).end().appendTo("#someParentDiv");
در این مثال ابتدا ما یک المان div ایجاد کردیم که دارای کلاس foo می‌باشد، و خود شامل یک div دیگر است. در ادامه div که دارای کلاس foo بوده را انتخاب کرده و رویداد کلیک را به آن بایند کردیم. و در انتها این div را با محتویاتش به المانی با Id=someParentDiv در سلسله مراتب DOM اضافه می‌کند.
برای اجرا این کد می‌توانید کد آن را دانلود کرده و فایل chapter2/new.divs.htmlرا اجرا کنید خروجی مانند تصویر زیر خواهد بود:

جهت تکمیل مطلب فعلی یک مثال کاملتر از این سایت جهت بررسی انتخاب کردم:
$( "<div/>", {
    "class": "test",
     text: "Click me!",
     click: function() {
           $( this ).toggleClass( "test" );
     }
   }).appendTo( "body" );
در این مثال کمی پیشرفته‌تر یک div ایجاد شده کلاس test را برای آن قرار داده و عنوان ان را برابر text قرار میدهد و یک رویداد کلیک برای آن تعریف می‌کند و در نهایت آن را به body سایت اضافه می‌کند.

با توجه به اینکه مطالب بعدی طولانی بوده و تقریبا مبحث جدایی است؛ در پست بعدی به بررسی توابع و متدهای مدیریت مجموعه انتخاب شده خواهیم پرداخت.

نظرات مطالب
امکان تعریف اعضای static abstract در اینترفیس‌های C# 11
پشتیبانی از ریاضیات جنریک در C# 11

در C# 11، امکان انجام عملیات ریاضی بر روی نوع‌های جنریک میسر شده‌است که قسمتی از آن‌را در مطلب جاری مطالعه کردید. این ویژگی به همراه دو مزیت زیر است:
- اکنون اعضای استاتیک اینترفیس‌ها می‌توانند abstract هم باشند؛ یعنی کلاس‌های پیاده ساز آن‌ها باید این اعضای استاتیک را پیاده سازی کنند.
-  امکان تعریف عملگرهای استاتیک ریاضی در اینترفیس‌ها ممکن شده‌است:
 static T Add<T>(T left, T right) where T : INumber<T> => left + right;
در این مثال، نوع T، تنها می‌تواند از نوع <INumber<T باشد که یکی از اینترفیس‌های جدید NET 7. است. این اینترفیس نیز پیاده سازی کننده‌ی IAdditionOperators است که در آن امکان دسترسی به عملگر + وجود دارد. متد فوق را می‌توان تقریبا توسط تمام نوع‌های ریاضی توکار دات نت مورد استفاده قرار داد؛ از این جهت که تعاریف آن‌ها نیز در دات نت 7 برای پشتیبانی از INumber به‌روز رسانی شده‌اند.
یکی از مهم‌ترین مزیت‌های چنین امکانی، کاهش تعداد overload هایی است که باید توسعه دهندگان کتابخانه‌ها برای پشتیبانی از انواع و اقسام نوع‌های ریاضی ارائه دهند.
 

تغییرات API دات نت 7 در جهت پشتیبانی از ریاضیات جنریک

در مطلب جاری با اینترفیس جدید INumber آشنا شدیم که توسط آن مفاهیمی مانند صفر و یک و همچنین سربارگذاری عملگرهای ریاضی میسر شده‌است. تعداد این اینترفیس‌های توکار در دات نت 7، فراتر از یک مورد فوق است. برای مثال اینترفیس جدید IMinMaxValue امکان دسترسی به T.MinValue و T.MaxValue را میسر می‌کند.
یک مثال: امضای نوع Int32 در دات نت 7 به صورت زیر در آمده‌است:
public readonly struct Int32 : 
  IComparable, 
  IComparable<int>, 
  IConvertible, 
  IEquatable<int>, 
  IFormattable, 
  IParsable<int>, 
  ISpanFormattable, 
  ISpanParsable<int>, 
  IAdditionOperators<int, int, int>, 
  IAdditiveIdentity<int, int>, 
  IBinaryInteger<int>, 
  IBinaryNumber<int>, 
  IBitwiseOperators<int, int, int>, 
  IComparisonOperators<int, int, bool>, 
  IEqualityOperators<int, int, bool>, 
  IDecrementOperators<int>, 
  IDivisionOperators<int, int, int>, 
  IIncrementOperators<int>, 
  IModulusOperators<int, int, int>, 
  IMultiplicativeIdentity<int, int>, 
  IMultiplyOperators<int, int, int>, 
  INumber<int>, 
  INumberBase<int>, 
  ISubtractionOperators<int, int, int>, 
  IUnaryNegationOperators<int, int>, 
  IUnaryPlusOperators<int, int>, 
  IShiftOperators<int, int, int>, 
  IMinMaxValue<int>, 
  ISignedNumber<int>
یعنی تمام نوع‌های ریاضی توکار دات نت 7 از ریاضیات جنریک پشتیبانی می‌کنند. البته نوع‌ها زیر هنوز از یک چنین پشتیبانی برخوردار نیستند:
- System.Half
- System.Numerics.BigInteger
- System.Numerics.Complex
- System.Runtime.InteropServices.NFloat
- System.Int128
- System.UInt128

نوع‌های Int128 و UIn128 جزو تازه‌های دات نت 7 هستند (128-bit signed integer و 128-bit unsigned integer).

البته عموم ما از همان اینترفیس INumber و IBinaryInteger استفاده خواهیم کرد که خود آن نیز به صورت زیر تعریف شده‌است:
public interface INumber<TSelf> : 
IComparable, 
IComparable<TSelf>, 
IEquatable<TSelf>, 
IFormattable, 
IParsable<TSelf>, 
ISpanFormattable, 
ISpanParsable<TSelf>, 
IAdditionOperators<TSelf, TSelf, TSelf>, 
IAdditiveIdentity<TSelf, TSelf>, 
IComparisonOperators<TSelf, TSelf, bool>, 
IEqualityOperators<TSelf, TSelf, bool>, 
IDecrementOperators<TSelf>, 
IDivisionOperators<TSelf, TSelf, TSelf>, 
IIncrementOperators<TSelf>, 
IModulusOperators<TSelf, TSelf, TSelf>, 
IMultiplicativeIdentity<TSelf, TSelf>, 
IMultiplyOperators<TSelf, TSelf, TSelf>, 
INumberBase<TSelf>, 
ISubtractionOperators<TSelf, TSelf, TSelf>, 
IUnaryNegationOperators<TSelf, TSelf>, 
IUnaryPlusOperators<TSelf, TSelf> where TSelf : INumber<TSelf>?
مطالب
امکان تعریف ساده‌تر کلاس‌های Immutable در C# 9.0 با معرفی نوع جدید record
در مطلب معرفی خواص init-only، با روش معرفی خواص immutable آشنا شدیم. نوع جدیدی که به C# 9.0 به نام record اضافه شده‌است، قسمتی از آن بر اساس همان خواص init-only کار می‌کند. به همین جهت مطالعه‌ی آن مطلب، پیش از ادامه‌ی بحث جاری، ضروری است.


چرا در C# 9.0 تا این اندازه بر روی سادگی ایجاد اشیاء Immutable تمرکز شده‌است؟

به شیءای Immutable گفته می‌شود که پس از وهله سازی ابتدایی آن، وضعیت آن دیگر قابل تغییر نباشد. همچنین به کلاسی Immutable گفته می‌شود که تمام وهله‌های ساخته شده‌ی از آن نیز Immutable باشند. نمونه‌ی یک چنین شیءای را از نگارش 1 دات نت در حال استفاده هستیم: رشته‌ها. رشته‌ها در دات نت غیرقابل تغییر هستند و هرگونه تغییری بر روی آن‌ها، سبب ایجاد یک رشته‌ی جدید (یک شیء جدید) می‌شود. نوع جدید record نیز به همین صورت عمل می‌کند.

مزایای وجود Immutability:

- اشیاء Immutable یا غیرقابل تغییر، thread-safe هستند که در نتیجه، برنامه نویسی همزمان و موازی را بسیار ساده می‌کنند؛ چون چندین thread می‌توانند با شیءای کار کنند که دسترسی به آن، تنها read-only است.
- اشیاء Immutable از اثرات جانبی، مانند تغییرات آن‌ها در متدهای مختلف در امان هستند. می‌توانید آن‌ها را به هر متدی ارسال کنید و مطمئن باشید که پس از پایان کار، این شیء تغییری نکرده‌است.
- کار با اشیاء Immutable، امکان بهینه سازی حافظه را میسر می‌کنند. برای مثال NET runtime.، هش رشته‌های تعریف شده‌ی در برنامه را در پشت صحنه نگهداری می‌کند تا مطمئن شود که تخصیص حافظه‌ی اضافی، برای رشته‌های تکراری صورت نمی‌گیرد. نمونه‌ی دیگر آن نمایش حرف "a" در یک ادیتور یا نمایشگر است. زمانیکه یک شیء Immutable حاوی اطلاعات حرف "a"، ایجاد شود، به سادگی می‌توان این تک وهله را جهت نمایش هزاران حرف "a" مورد استفاده‌ی مجدد قرار داد، بدون اینکه نگران مصرف حافظه‌ی بالای برنامه باشیم.
- کار با اشیاء Immutable به باگ‌های کمتری ختم می‌شود؛ چون همواره امکان تغییر حالت درونی یک شیء، توسط قسمت‌های مختلف برنامه، می‌تواند به باگ‌های ناخواسته‌ای منتهی شوند.
- Hash list‌ها که در جهت بهبود کارآیی برنامه‌ها بسیار مورد استفاده قرار می‌گیرند، بر اساس کلیدهایی Immutable قابل تشکیل هستند.


روش تعریف نوع‌های جدید record

کلاس ساده‌ی زیر را در نظر بگیرید:
public class User
{
   public string Name { set; get; }
}
برای تبدیل آن به یک نوع جدید record فقط کافی است واژه‌ی کلیدی class آن‌را با record جایگزین کنیم (به آن nominal record هم می‌گویند):
public record User
{
   public string Name { set; get; }
}
نحوه‌ی کار با آن و وهله سازی آن نیز دقیقا مانند کلاس‌ها است:
var user = new User();
user.Name = "User 1";
و ... در اینجا امکان انتساب مقداری به خاصیت Name وجود دارد؛ یعنی این خاصیت به صورت پیش‌فرض Immutable نیست.

روش تعریف دومی نیز در اینجا میسر است (به آن positional record هم می‌گویند):
public record User(string Name);
با این‌کار، به صورت خودکار یک record جدید تشکیل می‌شود که به همراه خاصیت Name است؛ چیزی شبیه به record قبلی که تعریف کردیم (به همین جهت نیاز است نام آن‌را شروع شده‌ی با حروف بزرگ درنظر بگیریم). با این تفاوت که این record، اینبار دارای سازنده است و همچنین خاصیت Name آن از نوع init-only است. در این حالت است که کل record به صورت immutable معرفی می‌شود؛ وگرنه روش تعریف یک خاصیت معمولی که از نوع init-only نیست (مانند مثال اول)، سبب بروز Immutability نخواهد شد.

برای کار با رکورد دومی که تعریف کردیم باید سازند‌ه‌ی این record را مقدار دهی کرد:
var user = new User("User 1");
// Error: Init-only property or indexer 'User.Name' can only be assigned
// in an object initializer, or on 'this' or 'base' in an instance constructor
// or an 'init' accessor. [CS9Features]csharp(CS8852)
user.Name = "User 1";
و همانطور که ملاحظه می‌کنید، چون خاصیت Name از نوع init-only است و در سازنده‌ی record تعریف شده مقدار دهی شده‌است، دیگر نمی‌توان آن‌را مقدار دهی مجدد کرد. همچنین در اینجا امکان استفاده‌ی از object initializers مانند new User { Name = "User 1" } نیز وجود ندارد؛ چون به همراه یک سازنده‌ی به صورت خودکار تولید شده‌است که خاصیتی init-only را مقدار دهی کرده‌است.


نوع جدید record چه اطلاعاتی را به صورت خودکار تولید می‌کند؟

روش دوم تعریف recordها اگر در نظر بگیریم:
public record User(string Name);
و در این حالت برنامه را کامپایل کنیم، به کدهای زیر که حاصل از دی‌کامپایل است، می‌رسیم:
using System;
using System.Collections.Generic;
using System.Runtime.CompilerServices;
using System.Text;
using CS9Features;

public class User : IEquatable<User>
{
 protected virtual Type EqualityContract
 {
  [System.Runtime.CompilerServices.NullableContext(1)]
  [CompilerGenerated]
  get
  {
   return typeof(User);
  }
 }

 public string Name
 {
  get;
  set/*init*/;
 }

 public User(string Name)
 {
  this.Name = Name;
  base..ctor();
 }

 public override string ToString()
 {
  StringBuilder stringBuilder = new StringBuilder();
  stringBuilder.Append("User");
  stringBuilder.Append(" { ");
  if (PrintMembers(stringBuilder))
  {
   stringBuilder.Append(" ");
  }
  stringBuilder.Append("}");
  return stringBuilder.ToString();
 }

 protected virtual bool PrintMembers(StringBuilder builder)
 {
  builder.Append("Name");
  builder.Append(" = ");
  builder.Append((object?)Name);
  return true;
 }

 [System.Runtime.CompilerServices.NullableContext(2)]
 public static bool operator !=(User? r1, User? r2)
 {
  return !(r1 == r2);
 }

 [System.Runtime.CompilerServices.NullableContext(2)]
 public static bool operator ==(User? r1, User? r2)
 {
  return (object)r1 == r2 || (r1?.Equals(r2) ?? false);
 }

 public override int GetHashCode()
 {
  return EqualityComparer<Type>.Default.GetHashCode(EqualityContract) * -1521134295 + EqualityComparer<string>.Default.GetHashCode(Name);
 }

 public override bool Equals(object? obj)
 {
  return Equals(obj as User);
 }

 public virtual bool Equals(User? other)
 {
  return (object)other != null && EqualityContract == other!.EqualityContract && EqualityComparer<string>.Default.Equals(Name, other!.Name);
 }

 public virtual User <Clone>$()
 {
  return new User(this);
 }

 protected User(User original)
 {
  Name = original.Name;
 }

 public void Deconstruct(out string Name)
 {
  Name = this.Name;
 }
}
این خروجی به صورت خودکار تولید شده‌ی توسط کامپایلر، چنین نکاتی را به همراه دارد:
- record‌ها هنوز هم در اصل همان class‌های استاندارد #C هستند (یعنی در اصل reference type هستند).
- این کلاس به همراه یک سازنده و یک خاصیت init-only است (بر اساس تعاریف ما).
- متد ToString آن بازنویسی شده‌است تا اگر آن‌را بر روی شیء حاصل، فراخوانی کردیم، به صورت خودکار نمایش زیبایی را از محتوای آن ارائه دهد.
- این کلاس از نوع  <IEquatable<User است که امکان مقایسه‌ی اشیاء record را به سادگی میسر می‌کند. برای این منظور متدهای GetHashCode و Equals آن به صورت خودکار بازنویسی و تکمیل شده‌اند (یعنی مقایسه‌ی آن شبیه به value-type است).
- این کلاس امکان clone کردن اطلاعات جاری را مهیا می‌کند.
- همچنین به همراه یک متد Deconstruct هم هست که جهت انتساب خواص تعریف شده‌ی در آن، به یک tuple مفید است.

بنابراین یک رکورد به همراه قابلیت‌هایی است که سال‌ها در زبان #C وجود داشته‌اند و شاید ما به سادگی حاضر به تشکیل و تکمیل آن‌ها نمی‌شدیم؛ اما اکنون کامپایلر زحمت کدنویسی خودکار آن‌ها را متقبل می‌شود!


ساخت یک وهله‌ی جدید از یک record با clone کردن آن

اگر به کدهای حاصل از دی‌کامپایل فوق دقت کنید، یک قسمت جدید clone هم با syntax خاصی در آن ظاهر شده‌است:
public virtual User <Clone>$()
{
  return new User(this);
}
زمانیکه یک شیء Immutable است، دیگر نمی‌توان مقادیر خواص آن‌را در ادامه تغییر داد. اما اگر نیاز به اینکار وجود داشت، باید چکار کنیم؟ در C# 9.0 برای ایجاد وهله‌ی جدید معادلی از یک record، واژه‌ی کلیدی جدیدی را به نام with، اضافه کرده‌اند. برای نمونه اگر record زیر را در نظر بگیریم که دارای دو خاصیت نام و سن است:
public record User(string Name, int Age);
وهله سازی متداول آن به صورت زیر خواهد بود:
var user1 = new User("User 1", 21);
اما اگر خواستیم خاصیت سن آن‌را تغییر دهیم، می‌توان با استفاده از واژه‌ی کلیدی with، به صورت زیر عمل کرد:
var user2 = user1 with { Age = 31 };
کاری که در اصل در اینجا انجام می‌شود، ابتدا clone کردن شیء user1 است (یعنی دقیقا یک وهله‌ی جدید از user1 را با تمام اطلاعات قبلی آن در اختیار ما قرار می‌دهد که این وهله، ارجاعی را به شیء قبلی ندارد و از آن منقطع است). بنابراین نام user2، دقیقا همان "User 1" است که پیشتر تنظیم کردیم؛ با این تفاوت که اینبار مقدار سن آن متفاوت است. با استفاده از cloning، هنوز شیء user1 که immutable است، دست نخورده باقی مانده‌است و توسط with می‌توان خواص آن‌را تغییر داد و حاصل کار، یک شیء کاملا جدید است که مکان آن در حافظه، با مکان شیء user1 در حافظه، یکی نیست.


مقایسه‌ی نوع‌های record

در کدهای حاصل از دی‌کامپایل فوق، قسمت عمده‌ای از آن به تکمیل اینترفیس <IEquatable<User پرداخته شده بود. به همین جهت اکنون دو رکورد با مقادیر خواص یکسانی را ایجاد می‌کنیم:
var user1 = new User("User 1", 21);
var user2 = new User("User 1", 21);
سپس یکبار آن‌ها را از طریق عملگر == و بار دیگر به کمک متد Equals، مقایسه می‌کنیم:
Console.WriteLine("user1.Equals(user2) -> {0}", user1.Equals(user2));
Console.WriteLine("user1 == user2 -> {0}", user1 == user2);
خروجی هر دو حالت، True است:
user1.Equals(user2) -> True
user1 == user2 -> True
این مورد، یکی از مهم‌ترین تفاوت‌های recordها با classها هستند.
- زمانیکه عملگر == را بر روی شیء user1 و user2 اعمال می‌کنیم، اگر User، از نوع کلاس معمولی باشد، حاصل آن false خواهد بود؛ چون این دو، به یک مکان از حافظه اشاره نمی‌کنند، حتی با اینکه مقادیر خواص هر دو شیء یکی است.
- اما اگر به قطعه کد دی‌کامپایل شده دقت کنید، در یک رکورد که هر چند در اصل یک کلاس است، حتی عملگر == نیز بازنویسی شده‌است تا در پشت صحنه همان متد Equals را فراخوانی کند و این متد با توجه به پیاده سازی اینترفیس <IEquatable<User، اینبار دقیقا مقادیر خواص رکورد را یک به یک مقایسه کرده و نتیجه‌ی حاصل را باز می‌گرداند:
public virtual bool Equals(User? other)
{
   return (object)other != null &&
 EqualityContract == other!.EqualityContract &&
 EqualityComparer<string>.Default.Equals(Name, other!.Name) && 
EqualityComparer<int>.Default.Equals(Age, other!.Age);
}
این متدی است که به صورت خودکار توسط کامپایلر جهت مقایسه‌ی مقادیر خواص رکورد جدید تعریف شده، تشکیل شده‌است. به عبارتی recordها از لحاظ مقایسه، شبیه به value objects عمل می‌کنند؛ هرچند در اصل یک کلاس هستند.

یک نکته: بازنویسی عملگر == در SDK نگارش rc2 فعلی رخ‌داده‌است و در نگارش‌های قبلی preview، اینگونه نبود.


امکان ارث‌بری در recordها

دو رکورد زیر را در نظر بگیرید که اولی به همراه Name است و نمونه‌ی مشتق شده‌ی از آن، خاصیت init-only سن را نیز به همراه دارد:
    public record User
    {
        public string Name { get; init; }

        public User(string name)
        {
            Name = name;
        }
    }

    public record UserWithAge : User
    {
        public int Age { get; init; }

        public UserWithAge(string name, int age) : base(name)
        {
            Age = age;
        }
    }
در اینجا روش دیگر تعریف recordها را ملاحظه می‌کنید که شبیه به کلاس‌ها است و خواص آن init-only هستند. در این حالت اگر مقایسه‌ی زیر را انجام دهیم:
var user1 = new User("User 1");
var user2 = new UserWithAge("User 1", 21);

Console.WriteLine("user1.Equals(user2) -> {0}", user1.Equals(user2));
Console.WriteLine("user1 == user2 -> {0}", user1 == user2);
به خروجی زیر خواهیم رسید:
user1.Equals(user2) -> False
user1 == user2 -> False
علت آن را هم پیشتر بررسی کردیم. تساوی رکوردها بر اساس مقایسه‌ی مقدار تک تک خواص آن‌ها صورت می‌گیرد و چون user1 به همراه سن نیست، مقایسه‌ی این دو، false را بر می‌گرداند.

امکان تعریف ارث‌بری رکوردها به صورت زیر نیز وجود دارد و الزاما نیازی به روش تعریف کلاس مانند آن‌ها، مانند مثال فوق نیست:
public abstract record Food(int Calories);
public record Milk(int C, double FatPercentage) : Food(C);


رکوردها متد ToString را بازنویسی می‌کنند

در مثال قبلی اگر یک ToString را بر روی اشیاء تشکیل شده فراخوانی کنیم:
Console.WriteLine(user1.ToString());
Console.WriteLine(user2.ToString());
به این خروجی‌ها می‌رسیم:
User { Name = User 1 }
UserWithAge { Name = User 1, Age = 21 }
که حاصل بازنویسی خودکار متد ToString در پشت صحنه است.


امکان استفاده‌ی از Deconstruct در رکوردها

دو روش برای تعریف رکوردها وجود دارند؛ یکی شبیه به تعریف کلاس‌ها است و دیگری تعریف یک سطری، که positional record نیز نامیده می‌شود:
public record Person(string Name, int Age);
 فقط در حالت تعریف یک سطری positional record فوق است که خروجی خودکار نهایی تولیدی، به همراه public void Deconstruct نیز خواهد بود:
public void Deconstruct(out string Name, out int Age)
{
  Name = this.Name;
  Age = this.Age;
}
در این حالت می‌توان از tuples نیز برای کار با آن استفاده کرد:
var (name, age) = new Person("User 1", 21);
واژه‌ی «positional» نیز دقیقا به همین قابلیت اشاره می‌کند که بر اساس موقعیت خواص تعریف شده‌ی در رکورد، امکان Deconstruct آن‌ها به متغیرهای یک tuple وجود دارد. حالت تعریف کلاس مانند رکوردها، nominal نام دارد.


امکان استفاده‌ی از نوع‌های record در ASP.NET Core 5x

سیستم model binding در ASP.NET Core 5x، از نوع‌های record نیز پشتیبانی می‌کند؛ یک مثال:
 public record Person([Required] string Name, [Range(0, 150)] int Age);

 public class PersonController
 {
   public IActionResult Index() => View();

   [HttpPost]
   public IActionResult Index(Person person)
   {
    // ...
   }
 }


پرسش و پاسخ

آیا نوع‌های record به صورت value type معرفی می‌شوند؟
پاسخ: خیر. رکوردها در اصل reference type هستند؛ اما از لحاظ مقایسه، شبیه به value types عمل می‌کنند.

آیا می‌توان در یک کلاس، خاصیتی از نوع رکورد را تعریف کرد؟
پاسخ: بله. از این لحاظ محدودیتی وجود ندارد.

آیا می‌توان در رکوردها، از struct و یا کلاس‌ها جهت تعریف خواص استفاده کرد؟
پاسخ: بله. از این لحاظ محدودیتی وجود ندارد.

آیا می‌توان از واژه‌ی کلیدی with با کلاس‌ها و یا structها استفاده کرد؟
پاسخ: خیر. این واژه‌ی کلیدی در C# 9.0 مختص به رکوردها است.

آیا رکوردها به صورت پیش‌فرض Immutable هستند؟
پاسخ: اگر آن‌ها را به صورت positional records تعریف کنید، بله. چون در این حالت خواص تشکیل شده‌ی توسط آن‌ها از نوع init-only هستند. در غیراینصورت، می‌توان خواص غیر init-only را نیز به تعریف رکوردها اضافه کرد.
مطالب
آشنایی با CLR: قسمت بیست و چهارم
آغاز فصل چهارم: بنیان و اساس نوع‌ها (Type Fundamentals)
در این فصل قرار است به بررسی اساس نوع داده‌ها بپردازیم؛ اینکه رفتارهایی که باید از هر نوع Type انتظار داشته باشیم، چه چیزهایی هستند. معانی فضای نام، اسمبلی‌ها، امن بودن نوع‌ها (Safety) و تبدیلات (Casts) را بهتر درک کنیم.
اولین نکته‌ای که باید بدانید این است که هر نوع داده‌ای که شما در دات نت دارید و تعریف می‌کنید، از والدی به نام System.Object مشتق می‌شود. برای مثال وقتی شما کلاسی را تعریف می‌کنید، چه ضمنی و چه صریح، کلاس شما از System.Object ارث بری خواهد کرد.
یعنی کد:
class DotnetTips
{
....
}
با کد زیر:
class DotnetTips:System.Object
{
...
}
برابر است.
برای همین، همه‌ی کلاس‌ها و انواع داده‌ها، شامل یک سری متدها و خصوصیات مشترک هستند. در لیست زیر تعدادی از متدهایی را که دسترسی public و Protected دارند، در جداول جداگانه‌ای بررسی می‌کنیم:
Public Methods
Equals
اگر هر دو شیء مقادیر یکسانی داشته باشند، True باز می‌گرداند. در فصل پنجم با این مورد بیشتر آشنا می‌شویم.
GetHashCode
 بر اساس مقادیر این شیء، یک کد هش شده می‌سازد. اگر شیء قرار است مقدار هش آن در جداول هش، مثل Dictionary یا HashSet به عنوان کلید به کار رود بهتر است این متد رونویسی شود. متاسفانه این متد در شیء Object تعریف شده است و از آنجا که بیشتر نوع‌ها هیچ وقت به عنوان یک کلید استفاده نمی‌شوند؛ بهتر بود در این رابطه به یک اینترفیس منتقل می‌شد. در فصل 5 بیشتر در این مورد بحث خواهد شد (مطالب مرتبط در اینباره +  + + ).
ToString
پیاده سازی پیش‌فرض آن اینست که این متد با اجرای کد
this.GetType().FullName
نام نوع را برمی‌گرداند. ولی برای بعضی نوع‌ها چون Boolean,int32 این متد، رونویسی شده و مقدار مربوطه را به طور رشته‌ای باز می‌گرداند. در بعضی موارد هم این متد برای استفاده‌هایی چون دیباگ برنامه هم رونویسی می‌شود. توجه داشته باشید که که نسبت به CultureInfo ترد مربوطه، واکنش نشان می‌دهد که در فصل 14 آن را بررسی می‌کنیم.
GetType
 یک نمونه از شیء مورد نظر را برمی‌گرداند که با استفاده از ریفلکشن می‌توان به اطلاعات متادیتای آن شیء دسترسی پیدا کرد. در مورد ریفلکشن در فصل 23 صحبت خواهد شد.


Protected Methods

MemberwiseClone
 این متد از شیء جاری یک Shallow copy (+ )گرفته و فیلدهای غیر ایستای آن را همانند شیء جاری پر می‌کند. اگر فیلدهای غیر ایستا از نوع Value باشند که کپی بیت به بیت صورت خواهد گرفت. ولی اگر فیلدی از نوع Reference باشد، از همان نوع Ref می‌باشند؛ ولی خود شیء اصلی، یک شیء جدید به حساب می‌آید و به شیء سازنده‌اش ارتباطی ندارد.
 Finalize یک متد Virtual است و زمانی صدا زده می‌شود که GC قصد نابودسازی آن شیء را داشته باشد. این متد برای زمانی نیاز است که شما قصد دارید قبل از نابودسازی، کاری را انجام دهید. در فصل 21 در این مورد بیشتر صحبت می‌کنیم.


همانطور که می‌دانید، همه‌ی اشیا نیاز دارند تا با استفاده از کلمه‌ی new، در حافظه تعریف شوند:

DotnetTips dotnettips=new DotnetTips("i am constructor");

اتفاقاتی که با استفاده از عملگر new رخ می‌دهد به شرح زیر است:

  1. اولین کاری که CLR انجام می‌دهد، محاسبه‌ی مقدار حافظه یا تعداد بایت‌های فیلدهای شیء مربوطه است و همچنین اشیایی که از آن‌ها مشتق شده است؛ مثل System.Object که همیشه وجود دارد. هر شیء‌ایی که بر روی حافظه‌ی Heap قرار می‌گیرد، به یک سری اعضای اضافه هم نیاز دارد که Type Object Pointer و Sync Block Index نامیده می‌شوند و CLR از آن‌ها برای مدیریت حافظه استفاده می‌کند. تعداد بایت‌های این اعضای اضافه هم با تعداد بایت‌های شیء مدنظر جمع می‌شوند.
  2. طبق تعداد بایت‌های به دست آمده، یک مقدار از حافظه‌ی Heap دریافت می‌شود.
  3. دو عضو اضافه که در بند شماره یک به آن اشاره کردیم، آماده سازی می‌شوند.
  4. سازنده‌ی شیء صدا زده می‌شود. سازنده بر اساس نوع ورودی شما انتخاب می‌شود و در صورت ارجاع به سازنده‌های والد، ابتدا سازنده‌های والد صدا زده می‌شوند و بعد از اینکه همه‌ی سازنده‌ها صدا زده شدند، سازنده‌ی System.Object صدا زده می‌شود که هیچ کدی ندارد؛ ولی به هر حال عمل Return آن انجام می‌شود.

بعد از انجام همه‌ی موارد بالا، یک اشاره گر به متغیر شما (در اینجا dotnettips) برگشت داده می‌شود.

مطالب
آموزش MDX Query - قسمت سیزدهم – برخی توابع برای کار روی ساختار های سلسله مراتبی (prevmember و nextmember)

کار با توابع  prevmember  و  nextmember

قبل از اجرای کوئری‌های زیر در ابتدا به ساختار سلسله مراتبی Customer دقت نمایید و ترتیب کشور‌ها را در این ساختار بررسی نمایید.

کوئری زیر را اجرا نمایید :

Select
{
[Measures].[Internet Sales Amount],
[Measures].[Internet Tax Amount]
}on columns,
{
[Customer].[Customer Geography].[Country].[Germany],
[Customer].[Customer Geography].[Country].[Germany].prevmember
}on rows
From [Adventure Works]

این تابع برادر قبلی را بدست میآ ورد

حال کوئری زیر را اجرا نمایید :

Select
{
[Measures].[Internet Sales Amount],
[Measures].[Internet Tax Amount]
} on columns,
{
[Customer].[Customer Geography].[Country].[Germany],
[Customer].[Customer Geography].[Country].[Germany].lag(1)
} on rows
From [Adventure Works]

در اینجا میزان فروش اینترنتی و همچنین میزان مالیات اینترنتی برای مشتریان آلمان و کشور قبلی بدست می‌آید.

با این تابع می توان برادر قبلی را با اعلام یک فاصله بدست آورد. مثلا 4 برادر قبلی یا .... را توسط این تابع بدست آورد .

کوئری زیر را اجرا نمایید :

Select
{
[Measures].[Internet Sales Amount],
[Measures].[Internet Tax Amount]
} on columns,
{
[Customer].[Customer Geography].[Country].[Germany],
[Customer].[Customer Geography].[Country].[Germany].prevmember.prevmember
} on rows
From [Adventure Works]

در این حالت مشابه تابع (2)Lag عمل کرده ایم. حال با استفاده از تابع  Nextmember  می توانیم برادر بعدی را بدست بیاوریم.

کوئری زیر را اجرا کنید :

select
{
[Measures].[Internet Sales Amount],
[Measures].[Internet Tax Amount]
} on columns,
{
[Customer].[Customer Geography].[Country].[Germany],
[Customer].[Customer Geography].[Country].[Germany].nextmember
} on rows
From [Adventure Works]

 و همچنین در کوئری زیر برادر بعد از برادر بعدی را بدست آورده ایم

Select
{
[Measures].[Internet Sales Amount],
[Measures].[Internet Tax Amount]
} on columns,
{
[Customer].[Customer Geography].[Country].[Germany],
[Customer].[Customer Geography].[Country].[Germany].nextmember.nextmember
} on rows
From [Adventure Works]

یک ترکیب از عملگر Range , NextMember در کوئری زیر نوشته شده است.

Select
{
[Measures].[Internet Sales Amount],
[Measures].[Internet Tax Amount]
} on columns,
[Customer].[Customer Geography].[Country].[Germany]
:
[Customer].[Customer Geography].[Country].[Germany].nextmember.nextmember
on rows
From [Adventure Works]

کاربرد تابع Lead برای به دست آوردن برادر بعدی بر اساس عددی می باشد که به آن داده ایم .

در اینجا ترکیبی از رنج و به دست  آوردن برادر برادر بعدی را داریم .

Select
{
[Measures].[Internet Sales Amount],
[Measures].[Internet Tax Amount]
} on columns,
[Customer].[Customer Geography].[Country].[Germany]
:
[Customer].[Customer Geography].[Country].[Germany].lead(2)
on rows
From [Adventure Works]

در قسمت بعدی تابع Order را بررسی می‌کنیم.

مطالب
قراردادهای کوئری نویسی در OData و WCF Data Service - قسمت اول
قبل از اینکه با کاربرد‌های OData بیشتر آشنا شوید می‌بایست قراردادهای کوئری نویسی با استفاده از آدرس وب سرویس را فراگیرید. در سمت گیرنده WCF Data Service زمانی که شما یک آدرس وب سرویس را به پروژه خود اضافه می‌نمایید مدل‌ها و روابط موجودیت‌ها بصورت خودکار تولید شده و دیگر لازم نیست از کوئری نویسی با آدرس وب سرویس استفاده نمایید و به جای آن از LINQ براحتی می‌توانید داده‌های خود را جستجو نمایید.اما اگر بخواهید وب سرویس را در بستر‌های دیگر یا در سمت گیرنده وب استفاده نمایید آشنایی با کوئری نویسی به شما امکان جستجو و دسترسی به داده‌های مدنظرتان را می‌دهد گرچه کتابخانه‌های OData موجود این امکان را آسان‌تر می‌سازد.

اجزای OData Url
OData Url شامل سه جزء می‌باشد که ترکیب این سه جرء امکان کوئری نویسی را فراهم می‌سازد
  1. Service Root Url یا ریشه آدرس سرویس که آدرس و نام وب سرویس را مشخص می‌سازد.
  2. Resource Path یا مسیر منابع که امکان دسترسی به منابع موجود وب سرویس را فراهم می‌سازد.
  3. Query Options یا گزینه‌های کوئری که امکان کوئری نویسی با استفاده از عملگرها و پارامترهای گرامر OData را فراهم می‌سازد.
در زیر این اجزا بهتر نشان داده شده است:
http://services.odata.org/OData/OData.svc/Category(1)/Products?$top=2&$orderby=name
\_______________________________________/ \__________________/ \__________________/
               |                                |                    |
         service root URL                  resource path        query options
مسیر منابع در OData
برای دسترسی به موجودیت‌های سرویس در قسمت مسیر منابع با نوشتن نام آن موجودیت این امکان فراهم می‌شود مثلا برای دسترسی به موجودیت Prodacts بعد از نام وب سرویس از یک /  استفاده می‌نامیم که Backslash برای جدا کردن موجودیت‌ها استفاده می‌شود
http://services.odata.org/OData/OData.svc/Products
بروزرسانی:حال اگر بخواهیم به Supplier‌های Product با استفاده از کلید موجودیت به یک product دسترسی یابیم. ( بعد Id و بعد ) برای product و دوباره / و Supplier را می‌نویسیم
http://services.odata.org/OData/OData.svc/Products(1)/Supplier
حتی امکان دسترسی در توابع موجودیت‌ها نیز میسر است 
http://services.odata.org/OData/OData.svc/Products/MostExpensive
اگر بخواهیم پارامتری را مقدار دهی نماییم بصورت زیر عمل می‌کنیم
http://services.odata.org/OData/OData.svc/GetProductsByCategoryId(categoryId=2)
برای دسترسی به property های موجودیت‌ها بصورت زیر عمل می‌کنیم 
http://services.odata.org/OData/OData.svc/Products(1)/Name
گزینه‌های کوئری
OData پنج عملگر دارد که امکان دستکاری موجودیت‌ها را فراهم می‌سازد
  1. filter$ عناصر برگشتی را محدود می‌سازد
  2. orderby$ امکان مرتب سازی عناصر برگشتی را فراهم می‌سازد
  3. skip$ امکان گذشت از تعدادی عناصر را از ابتدای عناصر فراهم می‌سازد
  4. top$ تعداد عناصر برگشتی را محدود می‌سازد
  5. expand$ امکان برگشت محتوای وابسته به عناصر برگشتی را فراهم می‌سازد
در زیر مثال‌های از این گزینه‌ها آورده شده است
//filter
http://services.odata.org/OData/OData.svc/Products?$filter=Name eq 'Milk'
//orderby
http://services.odata.org/OData/OData.svc/Products?$orderby=Name
//skip
http://services.odata.org/OData/OData.svc/Products?$skip=5
//top
http://services.odata.org/OData/OData.svc/Products?$top=10
//expand
http://services.odata.org/OData/OData.svc/Products?$expand=Category
ادامه دارد...
مطالب
Minimal API's در دات نت 6 - قسمت چهارم - تدارک مقدمات معماری بر اساس ویژگی‌ها
در معماری vertical slices با features سر و کار داریم؛ برای مثال برنامه‌ی ما دو ویژگی نویسنده‌ها و بلاگ‌ها را خواهد داشت و هر ویژگی، کاملا متکی به خود است. برای نمونه هر ویژگی می‌تواند به همراه یک ماژول باشد که به صورت مستقل، تمام سرویس‌ها، endpoints و میان‌افزارهای مورد نیاز خودش را ثبت می‌کند. در این معماری، تمام قسمت‌های مورد نیاز جهت کارکرد یک ویژگی، در کنار هم قرار می‌گیرند تا یافتن آن‌ها و درک ارتباطات بین آن‌ها ساده‌تر شود.


تعریف ساختار ماژول‌های ویژگی‌های معماری vertical slices

برای تعریف ساختار ماژولی که کار ثبت تمام نیازمندی‌های یک ویژگی را انجام می‌دهد، مانند ثبت سرویس‌ها، endpoints و میان‌افزارها، ابتدا پوشه‌ای به نام Contracts را به پروژه‌ی Api اضافه می‌کنیم؛ با این اینترفیس:
namespace MinimalBlog.Api.Contracts;

public interface IModule
{
    IEndpointRouteBuilder RegisterEndpoints(IEndpointRouteBuilder endpoints);
}


ثبت خودکار ماژول‌های برنامه در ابتدای اجرای آن

پس از تعریف این قرارداد، اکنون می‌خواهیم هر ماژولی که در برنامه، اینترفیس فوق را پیاده سازی می‌کند، در ابتدای اجرای برنامه به صورت خودکار، یافت شده و اطلاعات آن به سیستم اضافه شود. برای این منظور متدهای الحاقی زیر را تعریف می‌کنیم:
public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddApplicationServices(this IServiceCollection services,
        WebApplicationBuilder builder)
    {
        // ...

        builder.Services.AddAllModules(typeof(Program));

        return services;
    }

    private static void AddAllModules(this IServiceCollection services, params Type[] types)
    {
        // Using the `Scrutor` to add all of the application's modules at once.
        services.Scan(scan =>
            scan.FromAssembliesOf(types)
                .AddClasses(classes => classes.AssignableTo<IModule>())
                .AsImplementedInterfaces()
                .WithSingletonLifetime());
    }
}
این کلاس ساختار ساده‌ای دارد؛ ابتدا در متد AddAllModules، اسمبلی جاری جهت یافتن کلاس‌های پیاده سازی کننده‌ی اینترفیس IModule، اسکن می‌شود؛ با استفاده از کتابخانه‌ی Scrutor.
سپس کلاس‌های ثبت شده که هم اکنون جزئی از سیستم تزریق وابستگی‌های برنامه هستند، یافت شده و متد RegisterEndpoints آن‌ها فراخوانی می‌شوند تا دیگر نیازی نباشد به ازای هر ماژول، یکبار ثبت دستی این موارد در کلاس Program انجام شود.
using MinimalBlog.Api.Contracts;

namespace MinimalBlog.Api.Extensions;

public static class ModuleExtensions
{
    public static WebApplication RegisterEndpoints(this WebApplication app)
    {
        if (app == null)
        {
            throw new ArgumentNullException(nameof(app));
        }

        var modules = app.Services.GetServices<IModule>();
        foreach (var module in modules)
        {
            module.RegisterEndpoints(app);
        }

        return app;
    }
}
بنابراین در ادامه به کلاس Program مراجعه کرد و متد عمومی کلاس فوق را در آن به صورت app.RegisterEndpoints فراخوانی می‌کنیم:
using MinimalBlog.Api.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddApplicationServices(builder);

var app = builder.Build();
app.ConfigureApplication();
app.RegisterEndpoints();

app.Run();
این چند سطر، کل محتوای فایل Program.cs برنامه را تشکیل می‌دهند.


ایجاد اولین Feature برنامه؛ ویژگی نویسندگان

برای تعریف اولین ویژگی برنامه که مختص به نویسندگان است، پوشه‌های جدید Features\Authors را در برنامه‌ی Api ایجاد می‌کنیم.
- اولین کاری را که در ادامه انجام خواهیم داد، انتقال فایل AuthorDto.cs که در قسمت قبل ایجاد کردیم، به درون این پوشه‌ی جدید است.
- سپس ماژول نویسندگان را به صورت زیر به آن اضافه می‌کنیم:
namespace MinimalBlog.Api.Features.Authors;

public class AuthorModule : IModule
{
    public IEndpointRouteBuilder RegisterEndpoints(IEndpointRouteBuilder endpoints)
    {
        endpoints.MapGet("/api/authors", async (MinimalBlogDbContext ctx) =>
        {
            var authors = await ctx.Authors.ToListAsync();
            return authors;
        });

        endpoints.MapPost("/api/authors", async (MinimalBlogDbContext ctx, AuthorDto authorDto) =>
        {
            var author = new Author();
            author.FirstName = authorDto.FirstName;
            author.LastName = authorDto.LastName;
            author.Bio = authorDto.Bio;
            author.DateOfBirth = authorDto.DateOfBirth;

            ctx.Authors.Add(author);
            await ctx.SaveChangesAsync();

            return author;
        });

        return endpoints;
    }
}
در اینجا ماژول نویسندگان را که با پیاده سازی قرارداد IModule تشکیل شده‌است، مشاهده می‌کنید. در متد RegisterEndpoints آن، دو endpoints تعریف شده‌ی در کلاس Program برنامه را در قسمت قبل، Cut کرده و به اینجا منتقل کرده‌ایم. بنابراین اکنون کلاس Program، دیگر به همراه تعریف مستقیم هیچ endpoint ای نیست و خلوت شده‌است. هدف از Features هم دقیقا همین است تا هر ویژگی برنامه، متکی به خود بوده و مستقل باشد؛ به همراه تمام تعاریف مورد نیاز جهت کار با آن در یک محل مشخص (مانند انتقال فایل Dto مربوط به آن، به درون همین پوشه). مزیت این روش، درک ساده‌تر اجزای مرتبط و یافتن سریعتر ارتباطات قسمت‌های یک ویژگی خاص است. در آینده اگر مشکلی رخ داد و باگی بروز پیدا کرد، دقیقا می‌دانیم که محدوده‌ای که باید مورد بررسی قرار گیرد، کجاست و این محدوده، کوچک و متکی به خود است و در بین چندین پروژه‌ی مختلف، پراکنده نشده‌است.
کار نمونه سازی و اجرای متدهای این ماژول‌ها نیز توسط متدهای الحاقی کلاس ModuleExtensions، در ابتدای اجرای برنامه به صورت خودکار انجام می‌شود و نیازی به شلوغ کردن کلاس Program برای ثبت دستی آن‌ها نیست.


افزودن AutoMapper و MediatR به پروژه‌ی Api

در ادامه برای ساده سازی کار نگاشت‌های Dtoهای برنامه به مدل‌های دومین آن، از AutoMapper استفاده خواهیم کرد؛ همچنین از MediatR نیز برای پیاده سازی الگوی CQRS که در قسمت بعدی پیگیری خواهد شد. بنابراین در ابتدا بسته‌های نیوگت این دو را به پروژه‌ی Api اضافه می‌کنیم:
<Project Sdk="Microsoft.NET.Sdk.Web">
  <ItemGroup>
    <PackageReference Include="AutoMapper.Extensions.Microsoft.DependencyInjection" Version="11.0.0" />    
    <PackageReference Include="MediatR.Extensions.Microsoft.DependencyInjection" Version="10.0.1" />  
  </ItemGroup>
</Project>
سپس به کلاس ServiceCollectionExtensions مراجعه کرده و تعاریف ثبت سرویس‌های این دو را نیز اضافه می‌کنیم:
public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddApplicationServices(this IServiceCollection services,
        WebApplicationBuilder builder)
    {
        // ...

        builder.Services.AddMediatR(typeof(Program));
        builder.Services.AddAutoMapper(typeof(Program));

        return services;
    }
}
اکنون می‌توان اولین Profile مربوط به AutoMapper را که کار نگاشت AuthorDto به Author و برعکس را انجام می‌دهد، به صورت زیر تهیه کنیم:
using AutoMapper;
using MinimalBlog.Domain.Model;

namespace MinimalBlog.Api.Features.Authors;

public class AuthorProfile : Profile
{
    public AuthorProfile()
    {
        CreateMap<AuthorDto, Author>().ReverseMap();
    }
}
این فایل نیز درون پوشه‌ی Features\Authors قرار می‌گیرد.
مطالب
Blazor 5x - قسمت هفتم - مبانی Blazor - بخش 4 - انتقال اطلاعات از کامپوننت‌های فرزند به کامپوننت والد
در قسمت پنجم، روش انتقال اطلاعات را از کامپوننت‌های والد، به کامپوننت‌های فرزند توسط پارامترها، بررسی کردیم. در این قسمت، حالت عکس آن‌را بررسی خواهیم کرد. برای مثال فرض کنید که کاربری قصد انتخاب بیش از یک اتاق را دارد و checkbox انتخاب هر اتاق، درون کامپوننت مجزای آن اتاق تعریف شده و درون کامپوننت والد نمایش دهنده‌ی لیست اتاق‌ها نیست. اکنون می‌خواهیم با انتخاب اتاق‌ها توسط کاربر، جمع تعداد اتاق‌های انتخاب شده را در کامپوننت والد نمایش دهیم. بنابراین باید بتوان اطلاعاتی را از کامپوننت‌های فرزند، به کامپوننت والد انتقال داد.


در این تصویر، checkboxهای انتخاب شده، درون کامپوننت‌های مجزای فرزند و گزارش جمع نهایی ارائه شده، در کامپوننت والد قرار دارند.


معرفی Event Call Back

در این قسمت قصد داریم به کامپوننت Pages\LearnBlazor\LearnBlazor‍Components\IndividualRoom.razor که در مثال این سری تکمیل کردیم، یک checkbox انتخاب را نیز اضافه کنیم تا کاربرها بتوانند در زمان نمایش لیست اتاق‌ها در کامپوننت Pages\LearnBlazor\DemoHotel.razor، بیش از یک اتاق را انتخاب کنند.
برای این منظور در ابتدا به کامپوننت DemoHotel مراجعه کرده و فیلد SelectedRooms را در آن تعریف کرده و ذیل عنوان Hotel Rooms نمایش می‌دهیم:
@page "/demoHotel"

        <div class="col-12">
            <h4 class="text-info">Hotel Rooms</h4>
            <span>Rooms Selected - @SelectedRooms</span>
        </div>
        @foreach (var room in Rooms)
        {
            <IndividualRoom Room="room"></IndividualRoom>
        }

@code{

    int SelectedRooms;

    void RoomSelectionCounterChanged(bool isRoomSelected)
    {
        if (isRoomSelected)
        {
            SelectedRooms++;
        }
        else
        {
            SelectedRooms--;
        }
    }
    // ...
}
همچنین متد RoomSelectionCounterChanged را هم برای تغییر مقدار SelectedRooms تعریف کرده‌ایم. اما این متد به تنهایی کار نمی‌کند و باید بتوان آن‌را به کامپوننت فرزند <IndividualRoom Room="room"></IndividualRoom> انتقال داد تا در زمان انتخاب آن اتاق (و یا عدم انتخاب آن) در کامپوننت IndividualRoom، پارامتر bool isRoomSelected بر اساس وضعیت checkbox آن دریافت شده و در نتیجه مقدار جاری SelectedRooms، یک واحد کم یا زیاد شود. بنابراین نیاز است تا بتوان اشاره‌گری از یک متد کامپوننت سطح بالا را به یک کامپوننت سطح پایین و فرزند آن انتقال داد. اینکار در Blazor توسط EventCallback‌ها انجام می‌شود.
در ادامه به کامپوننت IndividualRoom.razor مراجعه کرده و کدهای آن را به صورت زیر تغییر می‌دهیم:
<input type="checkbox" @onchange="RoomCheckBoxSelectionChanged" />

@code
{
    //...

    [Parameter]
    public EventCallback<bool> OnRoomCheckBoxSelection { get; set; }

    async Task RoomCheckBoxSelectionChanged(ChangeEventArgs e)
    {
        await OnRoomCheckBoxSelection.InvokeAsync((bool)e.Value);
    }
}
ابتدا یک checkbox را جهت فراهم آوردن امکان انتخاب یک اتاق اضافه کرده‌ایم. سپس رخ‌داد onchange آن‌را به متد RoomCheckBoxSelectionChanged متصل کرده‌ایم. نوع پارامتر این متد را با نزدیک کردن اشاره‌گر ماوس به onchange@ چک باکس می‌توان مشاهده کرد:


تا اینجا فقط یک رخ‌داد را به یک متد، در همان کامپوننت متصل کرده‌ایم. هربار که checkbox تعریف شده انتخاب شود، متد رویدادگردان RoomCheckBoxSelectionChanged اجرا می‌شود. مرحله‌ی بعد، انتقال اطلاعات آن، به کامپوننت والد است که اینکار توسط پارامتر OnRoomCheckBoxSelection صورت می‌گیرد. کار آن، انتقال وضعیت checkbox، به متد RoomSelectionCounterChanged کامپوننت والد است.
بنابراین در اینجا نیاز است تا بتوان ارجاعی از این متد کامپوننت والد را به کامپوننت فرزند ارسال کرد که EventCallback تعریف شده‌ی به صورت پارامتر، چنین هدفی را برآورده می‌کند. با پارامتر تعریف شدن آن، می‌توان OnRoomCheckBoxSelection را به صورت زیر، به هر المان تعریف کننده‌ی کامپوننت IndividualRoom در کامپوننت DemoHotel اضافه کرد:
@foreach (var room in Rooms)
{
    <IndividualRoom OnRoomCheckBoxSelection="RoomSelectionCounterChanged" Room="room"></IndividualRoom>
}
در این تعریف، پارامتر Room، یک پارامتر ورودی است و پارامتر OnRoomCheckBoxSelection، به نوعی یک پارامتر خروجی است که با اتصال به متدی در همین کامپوننت، امکان دریافت اطلاعات و رویدادها را از یک کامپوننت سطح پایین‌تر پیدا می‌کند.

بنابراین به صورت خلاصه، هر زمانیکه یک checkbox در کامپوننت IndividualRoom انتخاب می‌شود، در نتیجه‌ی آن متد منتسب به EventCallback ارسالی به آن کامپوننت نیز فراخوانی می‌گردد که اینکار، سبب اجرای کدی در کامپوننت والد خواهد شد.


یک تمرین: انتقال رویداد انتخاب شدن یک div به کامپوننت والد

در بخش 2، در انتهای مطلب، لیست امکانات رفاهی هتل را هم نمایش دادیم. در اینجا می‌خواهیم اگر کاربری بر روی خروجی کامپوننت یکی از امکانات موجود کلیک کرد (کلیک بر روی div آن)، نام آن ویژگی در کامپوننت والد نمایش داده شود.
برای این منظور کامپوننت Pages\LearnBlazor\LearnBlazor‍Components\IndividualAmenity.razor را به صورت زیر تغییر می‌دهیم:
<div class="bg-light border p-2 col-5 offset-1 mt-2"
    @onclick="args => AmenitySelectionChanged(args, Amenity.Name)">
    <h4 class="text-secondary">Amenity - @Amenity.Id</h4>
    @Amenity.Name<br />
    @Amenity.Description<br />
</div>

@code
{
    [Parameter]
    public BlazorAmenity Amenity { get; set; }

    [Parameter]
    public EventCallback<string> OnAmenitySelection { get; set; }

    protected async Task AmenitySelectionChanged(MouseEventArgs e, string name)
    {
        await OnAmenitySelection.InvokeAsync(name);
    }
}
هدف از این مثال، آشنایی با نحوه‌ی تغییر امضای متد منتسب به رویداد onclick@ است. چون نوع پارامتر متد متناظر با آن، از نوع MouseEventArgs است (<EventCallback<MouseEventArgs) و نه از نوع ChangeEventArgs مثال قبلی که به همراه خاصیت Value مفیدی بود:


در اینجا نیاز خواهیم داشت تا اطلاعات رشته‌ای نام Amenity جاری را پس از کلیک بر روی div، به کامپوننت والد انتقال دهیم و MouseEventArgs فقط به همراه اطلاعات مختصات محل قرارگیری اشاره‌گر ماوس است. در یک چنین حالتی می‌توان با استفاده از anonymous method زیر، امضای متد منتسب به آن‌را تغییر داد:
@onclick="args => AmenitySelectionChanged(args, Amenity.Name)"
اکنون با هر بار کلیک بر روی div، نام Amenity جاری از طریق EventCallback تعریف شده، به سمت کامپوننت والد ارسال می‌شود. بنابراین مرحله‌ی بعدی، مراجعه به کامپوننت DemoHotel.razor است و استفاده از پارامتر جدید OnAmenitySelection:
@page "/demoHotel"

    @foreach (var amenity in AmenitiesList)
    {
      <IndividualAmenity OnAmenitySelection="AmenitySelectionChanged" Amenity="amenity"></IndividualAmenity>
    }

    <div class="col-12">
        <p class="text-secondary"> Selected Amenity : @SelectedAmenity </p>
    </div>

@code{

    string SelectedAmenity = "";

    void AmenitySelectionChanged(string amenity)
    {
        SelectedAmenity = amenity;
    }
}
ابتدا پارامتر جدید OnAmenitySelection کامپوننت IndividualAmenity به متد AmenitySelectionChanged همین کامپوننت متصل می‌شود. امضای آن بر اساس نوع پارامتر <EventCallback<string کامپوننت IndividualAmenity تعیین شده‌است.
سپس این پارامتر رشته‌ای دریافتی، به فیلد جدید SelectedAmenity انتساب داده می‌شود که پس از پایان این متد و رویداد، سبب درج آن در زیر حلقه‌ی نمایش AmenitiesList خواهد شد:



کدهای کامل این مطلب را از اینجا می‌توانید دریافت کنید: Blazor-5x-Part-07.zip
مطالب
نوشتن یک بات تلگرامی با استفاده از webhookها
با رشد روز افزون شبکه‌های اجتماعی و نیاز روزمره مردم به این شبکه‌ها ،اکثر شبکه‌های اجتماعی با در اختیار قرار دادن کتاب خانه‌ها و apiها، توسعه و طراحی یک برنامه‌ی مبتنی بر آن‌ها را فراهم کرده‌اند. تلگرام نیز یکی  از این شبکه‌ها است و با طراحی بات‌ها میتوان یک نرم افزار کوچک و پر کاربرد را جهت آن طراحی کرد.
در این مقاله قصد دارم نحوه ساخت یک بات تلگرامی را با استفاده از webhook که پیشنهاد خود تلگرام میباشد و همچنین کار با سایر apiهای مانند گرفتن عکس پروفایل و ... به اشتراک بگذارم. ما آموزش را بنا بر یک مثال کاربردی، در قالب یک بات تلگرامی قرار می‌دهیم که بعد از start شدن، پیغام خوش آمد گویی را نمایش میدهد و سپس جملات فارسی را از کاربر دریافت و معادل انگلیسی آن‌ها را با استفاده از از google translate به کاربر نشان میدهد.


شروع به ساخت بات

 به طور کلی دو روش برای ساخت یک بات تلگرامی وجود دارد:
1- استفاده از کتابخانه‌های آماده
2 - استفاده webhook

در روش 1، از یک سری از کتابخانه‌های آماده و تعریف شده، استفاده میکنیم.

مزایا:
 بدون زحمت زیادی و فقط با فراخوانی توابع آماده، قادر خواهیم بود یک بات خیلی ساده را شبیه سازی کنیم.
هزینه آن نسبت به webhook کمتر است و شما میتوانید با یک vps، بات را اجرا کنید.

معایب:
1- این روش ازpolling استفاد میکند. یعنی دستور دریافت شده در یک حلقه‌ی بی نهایت قرا میگیرد و هر بار چک میشود که آیا درخواستی رسیده است یا خیر؟ که سربار بالایی را بر روی سرور ما خواهد داشت.
2- بعد از مدتی down میشود.
3- اگر شمار درخواست‌ها بالا رود، Down میشود.

روش  دیگر استفاده از webhook است که اصولی‌ترین روش و روشی است که خود سایت تلگرام آن را پیشنهاد داده‌است. اگر بخواهم توضیح کوتاهی درباره webhook بدهم، با استفاده از آن میتوانید تعیین کنید وقتی یک event، رخ‌داد، api ایی فرخوانی شود؛ یا مثلا شما یک سایت را با api نوشته‌اید (ASP.NET Web API) و آن را پابلیش کرده‌اید و الان میخواهید یک api جدید را بنویسید. در این حالت با استفاده از webhook، دیگر نیازی نیست تا کل پروژه را پابلیش کنید. یک پروژه api را می‌نویسید و آن را آپلود می‌کنید و درقسمت تنظیم وب هوک، آدرس دامین خودتون را می‌دهید. حتی میتوانید آن را با php  یا هر زبانی که میتوانید بنویسید.

 معایب:
1- هزینه آن. شما علاوه بر تهیه‌ی هاست و دامین، باید ssl را هم فعال کنید که در ادامه بیشتر توضیح خواهیم داد. البته نگرانی برای پیاده سازی ssl نیست. چون سایت‌هایی هستند که این سرویس‌ها را به صورت رایگان در اختیار شما میگذارند (مانند Lets encrypt).
2- تنظیم آن به مراتب سخت‌تر از روش قبل است.

مزایا:
1- سرعت آن بیشتر است.
2- درخواست‌های با تعداد بالا را می‌توان به راحتی پاسخ داد.
3- وابستگی ثالثی ندارد.


اولین مرحله ساخت بات

تا اینجای کار به مباحث تئوری بات‌ها پرداختیم. حال وارد اولین مرحله‌ی ساخت بات‌ها میشویم. قبل از شروع، شما باید در بات BotFather@ عضو شوید و سپس یک بات جدید را بسازید. برای آموزش ساخت بات در BotFather، میتوانید از این مبحث استفاده کنید. بعد از ساخت بات در BotFather، شما داری یک token خواهید شد که یک رشته‌ی کد شده‌است.


ایجاد پروژه‌ی جدید بات

- در ادامه سراغ ویژوال استودیو رفته و یک پروژه‌ی Web api Empty را ایجاد کنید.
- سپس وارد سایت تلگرام شوید و کتابخانه‌ی مربوطه را دریافت کنیدو یا میتوانید با استفاده از دستور زیر، این کتابخانه را نصب کنید:
 Install-Package Telegram.Bot
پس از آن، اولین کار، ایجاد یک controller جدید به نام Webhook میباشد. درون این کنترلر، یکaction متد جدید را به نام UpdateMsg ایجاد می‌کنیم:
[HttpPost]
public async Task<IHttpActionResult> UpdateMsg(Update update)
{
  //......
}
تمام درخواست‌های تلگرام (وقایع رسیده‌ی از آن) ،به این action متد ارسال خواهند شد. اگر دقت کنید این متد دارای یک آرگومان از نوع update میباشد که شامل تمام پراپرتی‌های یک درخواست، اعم از نام کاربری، نوع درخواست، پیام و ... است.


تنظیم کردن WebHook

- حال به قسمت تنظیم کردن webhook می‌رسیم. وارد فایل Global.asax.cs برنامه شوید و با دستور زیر، وب هوک را تنظیم کنید:
var bot = new Telegram.Bot.TelegramBotClient("Token");
bot.SetWebhookAsync("https://Domian/api/webhook").Wait();
- در قسمت token ،token خود را که از BotFather دریافت کردید، وارد کنید و در قسمت setwebhook، باید ادرس دامنه‌ی خود را وارد نمائید. البته برای آزمایش برنامه، ما دامنه‌ای نداریم و  قصد خرید هاستی را هم نداریم. بنابراین با استفاده از ابزار ngrok می‌توان به سادگی یک دامنه‌ی آزمایشی SSL را تهیه کرد و از آن استفاده نمود.
- در این حالت بعد از اجرای ngrok، آدرس https آن را کپی کرده و در قسمت بالا، بجای Domain ذکر شده قرار دهید.
- برای آزمایش انجام کار، یک break-point را در قسمت action متد یاد شده قرار دهید و سپس برنامه را اجرا کنید.
- اکنون از طریق تلگرام وارد بات شوید و یک درخواست را ارسال کنید.
- اگر کار را به درستی انجام داده باشید، در صفحه ngrok  پیغام 200 مبتنی بر ارسال صحیح درخواست را دریافت خواهید کرد و همچنین در قسمت breakpoints برنامه بر روی آرگومان update، میتوانید پراپرتی‌های یک درخواست را به صورت کامل دریافت کنید.
- ارسال اولین درخواست ما از طریق بات start/ میباشد. در این حالت میتوان دریافت که کاربر برای بار اول است که از بات استفاده میکند.
- در اکشن متد از طریق خاصیت update.Message.Text میتوان به متن فرستاده شده دسترسی داشت.
- همچین اطلاعات کاربر در update.Message.From، همراه با درخواست، فرستاده می‌شود.


کار با ابزار ترجمه‌ی گوگل و تکمیل پروژه‌ی Web API

اکنون طبق مثال بالا می‌خواهیم وقتی کاربر برای اولین بار وارد شد، پیغام خوش آمد گویی به او نمایش داده شود. بعد از آن هر متنی را که فرستاد، معنای آن را از گوگل ترنسلیت گرفته و مجددا به کاربر ارسال میکنیم. برای اینکار کلاس WebhookController را به شکل زیر تکمیل خواهیم کرد: 
namespace Telegrambot.Controllers
{
    public class WebhookController : ApiController
    {
        Telegram.Bot.TelegramBotClient _bot = new Telegram.Bot.TelegramBotClient("number");
        Translator _translator = new Translator();

        [HttpPost]
        public async Task<IHttpActionResult> UpdateMsg(Update update)
        {
            if (update.Message.Text == "/start")
            {
                await _bot.SendTextMessageAsync(update.Message.From.Id, "Welcome To My Bot");
            }
            else
            {
                var translatedRequest = _translator.Translate(update.Message.Text, "Persian", "English");
                await _bot.SendTextMessageAsync(update.Message.From.Id, translatedRequest);
            }
            return Ok(update);
        }
    }
}
توضیحات:
- با استفاده از update.Message.From.Id میتوان پیغام را به شخصی که درخواست داده‌است فرستاد.
- دقت کنید هنگام ارسال درخواست، در ngrok آیا درخواستی فرستاده می‌شود یا خطایی وجود دارد.

نکته! برای استفاده از بات باید حتما از ssl استفاده کنید. اگر نیاز به خرید این سرویس را ندارید، از این لینک نیز می‌توانید سرویس مورد نظر را بعد از 24 ساعت بر روی دامین خود تنظیم کنید.


توضیحات بیشتر در این مورد را مثلا دکمه‌های پویا و گرفتن عکس پروفایل و ....، در مقاله‌ی بعدی قرار خواهم داد.

شما میتوانید از این لینک پروژه بالا را دریافت و اجرا کنید .