دعم Visual Basic و Visual C#‎

توفر السمات طريقة فعالة من إقران المعلومات التعريفية مع التعليمات البرمجية (أنواع ، خصائص وأساليب وهكذا دواليك). بعد أن تم إرفاق سمة مع كيان برنامج يطالب السمة في وقت التشغيل بإستخدام أسلوب يسمى انعكاس . لمزيد من المعلومات، راجع انعكاس (C# و Visual Basic).

ويمكن أن يكون للسمات الخواص التالية:

• تضيف السمات بيانات التعريف إلى البرنامج. بيانات التعريف هي معلومات حول الأنواع المعرفة في أحد البرامج. كل تجميعات .NET تحتوي على مجموعة محددة من بيانات تعريف التي تصف أنواع والأعضاء نوع المعرفة في التجميع. يمكنك إضافة سمات مخصصة لتحديد أية معلومات إضافية مطلوبة. لمزيد من المعلومات، راجع لإنشاء سمات مخصصة (C# و Visual Basic).

• يمكنك تطبيق سمة أو أكثر من السمات للتجميعات بأكملها أو الوحدات النمطية, أو عناصر برنامج أصغر عناصر برنامج مثل الفئات والخصائص.

• يمكن للسمات قبول الوسائط بالطريقة نفسها كما في الأساليب والخصائص.

• يمكن للبرنامج فحص بيانات التعريف الخاصة به أو بيانات التعريف في برامج أخرى بإستخدام الانعكاس. لمزيد من المعلومات، راجع الوصول إلى سمات باستخدام الانعكاس (C# و Visual Basic).

إستخدام السمات

يمكن وضع السمات في تعريف أي الأكثر لو سمة معينة قد تقييد أنواع التعريفات حيث تكون صحيحة. في C# ، يمكنك تعيين سمة بوضع اسم السمة محاطة بأقواس مربعة ([]) أو أعلى تعريف الوحدة إلى الذي يتم تطبيقه. في Visual Basic، تتم تضمين السمة بأقواس معقوفة (<>). يجب أن يظهر مباشرة قبل العنصر إلى الذي يتم تطبيقه, على نفس الخط.

في هذا المثال، SerializableAttributeيتم إستخدام السمة ليطبق صفة مميزة و معينة للفئة:

<System.Serializable()> Public Class SampleClass
    ' Objects of this type can be serialized.
End Class

[System.Serializable]
public class SampleClass
{
    // Objects of this type can be serialized.
}

يتم التصريح عن أسلوب مع السمة DllImportAttribute كما يلي:

Imports System.Runtime.InteropServices


...


<System.Runtime.InteropServices.DllImport("user32.dll")> 
Sub SampleMethod()
End Sub

using System.Runtime.InteropServices;


...


[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();

يمكن وضع أكثر من سمة واحدة في تعريف:

Imports System.Runtime.InteropServices


...


Sub MethodA(<[In](), Out()> ByVal x As Double)
End Sub
Sub MethodB(<Out(), [In]()> ByVal x As Double)
End Sub

using System.Runtime.InteropServices;


...


void MethodA([In][Out] ref double x) { }
void MethodB([Out][In] ref double x) { }
void MethodC([In, Out] ref double x) { }

يمكن أن يتم تعيين بعض السمات أكثر من مرة لوحدة معطاه. مثال عن مثل هذه السمة المتعددة الإستخدام ConditionalAttribute:

<Conditional("DEBUG"), Conditional("TEST1")> 
Sub TraceMethod()
End Sub

[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
    // ...
}

ملاحظة

اصطلاحاً, كافة أسماء السمات التي تنتهي بالكلمة "سمة" لتمييزها عن العناصر الأخرى في .NET Framework. ومع ذلك، لا تحتاج لتعيين لاحقة السمة عند إستخدام السمات في التعليمات البرمجية. على سبيل المثال، [DllImport]يكافئ إلى [DllImportAttribute], ولكن DllImportAttributeهو اسم السمة الفعلية في .NET Framework.

معلمات السمة

تحتوي العديد من السمات على معلمات يمكن أن تكون موضعية ,غير مسمى أو مسماة. يجب أن تكون أية معلمات الموضعية محددة في ترتيب معين ولا يمكن حذفها ؛ المعلمات المسماة اختيارية و يمكن تحديدها في أي ترتيب. يتم تعيين المعلمات الموضعية أولاً. على سبيل المثال، السمات الثلاثة متكافئة:

[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]

<DllImport("user32.dll")>
<DllImport("user32.dll", SetLastError:=False, ExactSpelling:=False)>
<DllImport("user32.dll", ExactSpelling:=False, SetLastError:=False)>

المعلمة الأولى اسم DLL الموضعية ويتم دوماً يأتي أولاً; المسمى الأخرى. في هذه الحالة، كل المعلمات المسماة يجب افتراضهم ل"خطأ " بحيث يمكن القيام بحذفها. تشير إلى وثائق سمة فردية للحصول على معلومات حول قيم المعلمات الافتراضية.

أهداف السمة

الهدف للسمة هو الوحدة الذي يتم تطبيق السمة فيها. على سبيل المثال، قد يتم تطبيق سمة لفئة أو أسلوب خاص أو تجميع بأكمله. يتم تطبيق سمة على العنصر الذي يسبق عليه بشكل افتراضي. ولكن يمكنك أيضاً بوضوح تعريف, على سبيل المثال، ما إذا كان تطبيق سمة إلى الأسلوب، أو لمعلمة أو لقيمة مرجعة.

لتعريف هدف السمة بوضوح, إستخدم بناء الجملة التالي:

[target : attribute-list]

<target : attribute-list>

قائمة المحتملة targetيتم إظهار القيم في الجدول التالي.

C#‎	Visual Basic	ينطبق على
assembly	Assembly	التجميع بأكمله
module	Module	الوحدة النمطية للتجميع الحالي (وهي مختلفة عن الوحدة النمطية لـ Visual Basic)
field	غير مدعم	حقل في فئة
event	غير مدعم	الحدث
method	غير مدعم	أو أسلوب getو الخاصية setaccessors
param	غير مدعم	معلمات الأسلوب أو معلمات استرجاع قيمة set الخاصية أو معلمات الأسلوب
property	غير مدعم	الخصائص
return	غير مدعم	إرجاع القيمة لأسلوب أو خاصية مفهرس أو أسلوب استرجاع القيمة الخاصية get
type	غير مدعم	بنية, فئة, واجهة, أو enum

المثال يعرض كيفية تطبيق السمات إلى التجميعات والوحدات النمطية. لمزيد من المعلومات، راجع سمات الشائعة (C# و Visual Basic).

Imports System.Reflection
<Assembly: AssemblyTitleAttribute("Production assembly 4"), 
Module: CLSCompliant(True)> 

using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]

المثال التالي يعرض كيفية تطبيق السمات للأساليب لمعلمات أسلوب وأساليب بإرجاع قيم في C#‎.

// default: applies to method
[SomeAttr]
int Method1() { return 0; }

// applies to method
[method: SomeAttr]
int Method2() { return 0; }

// applies to return value
[return: SomeAttr]
int Method3() { return 0; }

ملاحظة

بغض النظر عن الأهداف حيث تكون SomeAttrمعرّفة ل "صالح", يمكن للهدف return أن يكون محدد حتى إذا تم تعريف SomeAttr ليطبق فقط لقيم الإرجاع. في صيغة اخرى لن يستخدم المحول البرمجي المعلومات AttributeUsage لحل أهداف السمة الملبسة. لمزيد من المعلومات، راجع AttributeUsage (C# و Visual Basic).

الإستخدامات الشائعة للسمات

تتضمن القائمة التالية بعض الإستخدامات الشائعة للسمات في التعليمات البرمجية:

• وضع علامة على الأساليب بإستخدام سمةWebMethod في خدمات ويب لتوضيح أن يجب أن يكون الأسلوب للاستدعاء عبر بروتوكول SOAP. لمزيد من المعلومات، راجع WebMethodAttribute.

• يصف كيفية تنظيم معلمات الأسلوب عند التفاعل مع كعب تعليمات برمجية. لمزيد من المعلومات، راجع MarshalAsAttribute.

• يصف خصائص الفئات وأساليب واجهات COM.

• استدعاء تعليمات برمجية غير مُدارة بإستخدام الفئة DllImportAttribute.

• تصف التجميع الخاص بك من العنوان أو الإصدار أو الوصف أو العلامات التجارية.

• تصف أي الأعضاء في الفئة يحدد لإجراء تسلسل لـلاستمرارية.

• يصف كيفية التخطيط بين أعضاء الفئة و XML العقد للسَلسَلة XML.

• تصف متطلبات الأمان من أجل الأساليب.

• تعيين الصفات المميزة المستخدمة لفرض الأمان.

• التحكم بالأمثلية عن طريق برنامج التحويل البرمجي في نفس الوقت (JIT) بحيث تبقى التعليمات برمجية سهلة التصحيح.

الأقسام ذات الصلة

لمزيد من المعلومات، راجع:

• لإنشاء سمات مخصصة (C# و Visual Basic)

• الوصول إلى سمات باستخدام الانعكاس (C# و Visual Basic)

• كيفية القيام بما يلي: إنشاء اتحاد C/C++ باستخدام سمات (C# و Visual Basic)

• سمات الشائعة (C# و Visual Basic)

راجع أيضًا:

المرجع

انعكاس (C# و Visual Basic)

المبادئ

دليل البرمجة لـ #C

لتوسيع بيانات التعريف باستخدام السمات

موارد أخرى

دليل البرمجة Visual Basic