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

يصف هذا الموضوع السمات المستخدمة بشكلٍ مشترك في برنامجي C# و Visual Basic.

• سمات العمومية

• سمة قديمة

• سمة الشرطي

• سمات (Visual Basic)

سمات العمومية

يتم يطبق سمات معظم عناصر لغة معينة مثل الفئات أو أساليب القيم؛ وبالرغم من ذلك، يتم بعض السمات العمومية — ويتم يطبقها إلى التجميع بأكمله أو وحدة نمطية. على سبيل المثال، AssemblyVersionAttributeيمكن إستخدام السمة ليضمّن معلومات الإصدار في تجميع مع مثل هذا:

[assembly: AssemblyVersion("1.0.0.0")]

<Assembly: AssemblyVersion("1.0.0.0")>

سمات العمومية تظهر في تعليمات برمجية المصدر بعد أي توجيهات من المستوى الأعلى using ( Importsفي Visual Basic) ثم قبل أي نوع وحدة نمطية أو مساحة الاسم التعريفات. يمكن أن تظهر سمات العمومية في ملفات مصدر متعددة لكن يجب أن يكون التحويل البرمجي الملفات في مرور واحد التحويل برمجي. لمشاريع Visual Basic, بشكل عام يتم وضع سمات العمومية في الملف AssemblyInfo.vb الذي يتم إنشاؤه تلقائياً مع المشاريع Visual Basic. في مشاريع C# يتم وضعها في الملف AssemblyInfo.cs .

سمات التجميع هي قيم توفر معلومات حول التجميع. يكون وقوعها ضمن الفئات التالية:

• سمات الهوية للتجميع.

• سمات إعلامية.

• سمات بيان التجميع.

• سمات الاسم القوي.

سمات الهوية للتجميع.

ثلاثة سمات،مقترنة مع الاسم القوي (إن أمكن) ، تحدد هوية التجميع: الاسم , و الإصدار , و الثقافة. هذه السمات تمثل الاسم الكامل للتجميع و هي مطلوبة عند الإشارة إلى التجميع في التعليمات البرمجية. يمكنك إستخدام السمات لتعيين إصدار التجميع و الثقافة. Assembly Information Dialog Boxمربع حوار معلومات التجميععلى الرغم من ذلك، يتم تعيين القيمة اسم بواسطة المترجم ال Visual Studio IDE في مربع حوار معلومات التجميع, أو "رابط التجميع" (Al.exe) عند إنشاء التجميع استناداً إلى الملف الذي يحتوي على ملف بيان التجميع. ‎تحدد سمة T:System.Reflection.AssemblyFlagsAttribute ما إذا كان يمكن أن تتواجد النسخ متعددة من التجميع.

يعرض الجدول التالي سمات الهوية.

السمة	الغرض
AssemblyName	وصف كامل هوية التجميع.
AssemblyVersionAttribute	تحدد الإصدار من تجميع.
AssemblyCultureAttribute	تعيّن أي ثقافة يدعمها التجميع.
AssemblyFlagsAttribute	تحديد ما إذا كان يدعم تجميع التنفيذ متعدد على الكمبيوتر نفسه في نفس العملية أو في نفس مجال التطبيق.

سمات إعلامية.

يمكنك إستخدام السمات الإعلامية لتوفير معلومات إضافية عن الشركة أو المنتج لتجميع. يعرض الجدول التالي سمات معلوماتية المعرفة في مساحة الاسم System.Reflection.

السمة	الغرض
AssemblyProductAttribute	تعريف سمة مخصصة التي تحدد اسم منتج للحصول بيان التجميع.
AssemblyTrademarkAttribute	تعريف سمة مخصصة التي تحدد اسم منتج للحصول بيان التجميع.
AssemblyInformationalVersionAttribute	تعريف سمة مخصصة التي تحدد إصدار معلوماتي لبيان التجميع.
AssemblyCompanyAttribute	تعريف سمة مخصصة التي تحدد اسم الشركة للحصول على بيان التجميع.
AssemblyCopyrightAttribute	تعريف سمة مخصصة التي تحدد حقوق النشر للحصول بيان التجميع.
AssemblyFileVersionAttribute	يرشد المحول البرمجي لإستخدام رقم إصدار محدد لمورد إصدار ملف Win32.
CLSCompliantAttribute	الإشارة إلى ما إذا كان التجميع متوافق مع مواصفات اللغة العامة (CLS).

سمات بيان التجميع.

يمكنك إستخدام سمات بيان التجميع بتوفير المعلومات في ملف التجميع الظاهر. يتضمن هذا العنوان وصف اسم مستعار الافتراضي والتكوين. يبين الجدول التالي بيان التجميع السمات المعرفة في مساحة الاسم System.Reflection.

السمة	الغرض
AssemblyTitleAttribute	تعريف سمة مخصصة التي تحدد اسم منتج للحصول بيان التجميع.
AssemblyDescriptionAttribute	تعريف سمة مخصصة التي تحدد وصف المنتج لبيان التجميع.
AssemblyConfigurationAttribute	تعريف سمة مخصصة التي تحدد تكوين تجميع (مثل البيع بالتجزئة أو تصحيح) لبيان التجميع.
AssemblyDefaultAliasAttribute	تعريف الاسم مستعار افتراضي مألوف لبيان التجميع

سمات الاسم القوي.

في الإصدارات السابقة من ‏‫Visual Studio تم إجراء تسجيل التجميعات بإستخدام أسماء قوية مع هذه السمات المستوى التجميع:

• AssemblyKeyFileAttribute

• AssemblyKeyNameAttribute

• AssemblyDelaySignAttribute

لا يزال يتم دعم ذلك ولكنه الطريقة المفضلة لتوقيع التجميعات هي إستخدام الصفحة التوقيع في مصمم مشروع. لمزيد من المعلومات، راجع صفحة تسجيل الدخول، مصمم المشروع و كيفية القيام بما يلي: التوقيع على التجميع (‏‫Visual Studio) .

سمة قديمة

سمة Obsoleteتحدد وحدة بالرنامج كعنصر غير مفضل إستخدامه. كل إستخدام لوحدة التمييز محددة كصيغة قديمة سوف تقوم بإنشاء تحذير أو خطأ استناداً إلى كيفية تكوين السمة. فعلى سبيل المثال:

    <System.Obsolete("use class B")> 
    Class A
        Sub Method()
        End Sub
    End Class

    Class B
        <System.Obsolete("use NewMethod", True)> 
        Sub OldMethod()
        End Sub

        Sub NewMethod()
        End Sub
    End Class

[System.Obsolete("use class B")]
class A
{
    public void Method() { }
}
class B
{
    [System.Obsolete("use NewMethod", true)]
    public void OldMethod() { }
    public void NewMethod() { }
}

في هذا المثال السمةObsoleteمطبقة للفئة Aوإلى الأسلوب B.OldMethod. لأن الوسيطة الثانية للسمة الدالة الإنشائية تطبق إلى B.OldMethodمعينًا إلى true، يتسبب هذا الأسلوب بخطأ برنامج التحويل البرمجي بينما بإستخدام فئة Aسيقوم فقط بإنتاج تحذير. استدعاء B.NewMethod ومع ذلك، لا ينتج أي تحذير أو خطأ.

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

' Generates 2 warnings:
' Dim a As New A
' Generate no errors or warnings:

Dim b As New B
b.NewMethod()

' Generates an error, terminating compilation:
' b.OldMethod()

// Generates 2 warnings:
// A a = new A();

// Generate no errors or warnings:
B b = new B();
b.NewMethod();

// Generates an error, terminating compilation:
// b.OldMethod();

A‎‎يتم إنشاء تحذيرين فئة ‎‏: واحد من أجل تعريف مرجع الفئة, وواحد لوحدة مُنشئ الفئة.

يمكن إستخدام السمةObsolete بدون وسائط ولكن تفسير سبب كون العنصر قديم وما الإستخدام المستحسن بدلاً من ذلك.

السمة Obsolete هي سمة الإستخدام الواحد ويمكن تطبيقها إلى لأي وحدة تسمح السمات. Obsoleteهو اسم مستعار لـObsoleteAttribute.

سمة الشرطي

السمةConditional تجعل تنفيذ الأسلوب معتمد على معرّف preprocessing. السمة Conditional هي اسم مستعار لـ ConditionalAttribute، ويمكن أن يتم تطبيقها إلى أسلوب أو فئة السمات.

في هذا المثال، Conditionalيتم تطبيق إلى أسلوب إلى تمكين أو يعطل عرض المعلومات الخاصة بالبرامج التشخيص:

#Const TRACE_ON = True
Imports System
Imports System.Diagnostics
Module TestConditionalAttribute
    Public Class Trace
        <Conditional("TRACE_ON")> 
        Public Shared Sub Msg(ByVal msg As String)
            Console.WriteLine(msg)
        End Sub

    End Class

    Sub Main()
        Trace.Msg("Now in Main...")
        Console.WriteLine("Done.")
    End Sub
End Module

#define TRACE_ON
using System;
using System.Diagnostics;

public class Trace
{
    [Conditional("TRACE_ON")]
    public static void Msg(string msg)
    {
        Console.WriteLine(msg);
    }
}

public class ProgramClass
{
    static void Main()
    {
        Trace.Msg("Now in Main...");
        Console.WriteLine("Done.");
    }
}

إذا كان TRACE_ONلم يتم تعريف معرّف, يتم عرض لا إخراج التتبع.

غالباً ما يتم إستخدام السمة Conditionalمع معرّف DEBUGلتمكين التتبع والميزات التسجيل لـ يصحح بناء ولكن بناء موجود في إصدار مثل هذا:

<Conditional("DEBUG")> 
Shared Sub DebugMethod()

End Sub

[Conditional("DEBUG")]
static void DebugMethod()
{
}

عندما يتم استدعاء أسلوب وضعت الشرطي وجود أو غياب رمز preprocessing المحدد يحدد ما إذا كانت المكالمة المضمنة أو تم حذفها. إذا تم تعريف الرمز, يتم تضمين الإتصال وإلا بهمل الإتصال. إستخدام Conditionalيعتبر وسيلة أنظف و أكثرأناقة و أقل خطأ لإحاطة الأساليب داخل كتل #if…#endif كما يلي:

#If DEBUG Then
    Sub ConditionalMethod()
    End Sub
#End If

#if DEBUG
    void ConditionalMethod()
    {
    }
#endif

يجب أن يكون أسلوب في تعريف الفئة أو البنية أسلوب شرطي كما يجب ألا يكون هناك قيمة إرجاع.

إستخدام معرفات متعددة

إذا كان يوجد للأسلوب سماتConditionalمتعددة، الاستدعاء للأسلوب مُضمن إذا تم تعريف رمز واحد من الرموز الشرطية ( الرموز منطقياً مرتبطة مع بعضها البعض بإستخدام ال أو عامل التشغيل). في هذا المثال وجود إما Aأو Bسيؤدي استدعاء أسلوب:

<Conditional("A"), Conditional("B")> 
Shared Sub DoIfAorB()

End Sub

[Conditional("A"), Conditional("B")]
static void DoIfAorB()
{
    // ...
}

لتحقيق تأثيرالربط المنطقي بربط الرموز بإستخدام عامل التشغيل AND يمكنك تعريف الأساليب الشرطي تسلسلي. على سبيل المثال، تنفذ الطريقة الثانية أدناه فقط إذا كان كلاAو Bمعرفان:

<Conditional("A")> 
Shared Sub DoIfA()
    DoIfAandB()
End Sub

<Conditional("B")> 
Shared Sub DoIfAandB()
    ' Code to execute when both A and B are defined...
End Sub

[Conditional("A")]
static void DoIfA()
{
    DoIfAandB();
}

[Conditional("B")]
static void DoIfAandB()
{
    // Code to execute when both A and B are defined...
}

إستخدام الشرطية مع سمة الفئات

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

<Conditional("DEBUG")> 
Public Class Documentation
    Inherits System.Attribute
    Private text As String
    Sub New(ByVal doc_text As String)
        text = doc_text
    End Sub
End Class

Class SampleClass
    ' This attribute will only be included if DEBUG is defined.
    <Documentation("This method displays an integer.")> 
    Shared Sub DoWork(ByVal i As Integer)
        System.Console.WriteLine(i)
    End Sub
End Class

[Conditional("DEBUG")]
public class Documentation : System.Attribute
{
    string text;

    public Documentation(string text)
    {
        this.text = text;
    }
}

class SampleClass
{
    // This attribute will only be included if DEBUG is defined.
    [Documentation("This method displays an integer.")]
    static void DoWork(int i)
    {
        System.Console.WriteLine(i.ToString());
    }
}

سمات (Visual Basic)

يسرد الجدول التالي السماتالمعينة إلى Visual Basic.

السمة	الغرض
ComClassAttribute	يشير إلى المحول البرمجي الفئة يجب أن يكون كشف ككائن COM.
HideModuleNameAttribute	يسمح الوصول لأعضاء الوحدة النمطية بإستخدام تأهيل الوحدة النمطية المطلوبة فقط.
VBFixedStringAttribute	تحديد حجم السلسلة ذات الطول في البنية للإستخدام مع دالات ملف الإدخال والإخراج .
VBFixedArrayAttribute	تحديد حجم السلسلة ذات الصفيف الثابت للإستخدام مع دالات ملف الإدخال والإخراج .

COMClassAttribute

إستخدام COMClassAttribute لتبسيط عملية إنشاء مكونات COM من Visual Basic. كائنات COM تختلف بشكل كبير عن التجميعات .NET Framework ، ودون COMClassAttribute، تحتاج إلى أن تتبع عدد الخطوات لإنشاء كائن COM من Visual Basic. للفئات المحددة ب COMClassAttribute، ينفذ المحول البرمجي العديد من الخطوات المذكورة تلقائياً.

HideModuleNameAttribute

إستخدام HideModuleNameAttributeللسماح بالوصول لأعضاء الوحدة النمطية بإستخدام التأهيل اللازم للوحدة نمطية.

VBFixedStringAttribute

إستخدم VBFixedStringAttributeلفرض Visual Basic لإنشاء سلسلة ذات طول ثابت. السلاسل ذات الطول المتغير افتراضياً, و هذه السمة مفيدة عند تخزين سلاسل إلى الملفات. التعليمة البرمجية التالية توضح ذلك:

Structure Worker
    ' The runtime uses VBFixedString to determine 
    ' if the field should be written out as a fixed size.
    <VBFixedString(10)> Public LastName As String
    <VBFixedString(7)> Public Title As String
    <VBFixedString(2)> Public Rank As String
End Structure

VBFixedArrayAttribute

إستخدام VBFixedArrayAttributeللتصريح بالصفائف التي تم تثبيت حجمها. مثل سلاسل Visual Basic، الصفائف متغيرة الطول بشكل افتراضي. هذه السمة مفيدة عند إجراء تسلسل أو كتابة بيانات للملفات.

راجع أيضًا:

المرجع

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

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

System.Reflection

Attribute

المبادئ

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

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

موارد أخرى

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