Share via

عبارة التعريف

  • مقالة

يقوم بتعريف مرجع إلى إجراء تم تنفيذه في ملف خارجي.

[ <attributelist> ] [ accessmodifier ] [ Shadows ] [ Overloads ] _
Declare [ charsetmodifier ] [ Sub ] name Lib "libname" _
[ Alias "aliasname" ] [ ([ parameterlist ]) ]
' -or-
[ <attributelist> ] [ accessmodifier ] [ Shadows ] [ Overloads ] _
Declare [ charsetmodifier ] [ Function ] name Lib "libname" _
[ Alias "aliasname" ] [ ([ parameterlist ]) ] [ As returntype ]

الأجزاء

  • attributelist
    اختياري. راجع قائمة سمة.

  • accessmodifier
    اختياري. يمكن أن يكون أحد الخيارات التالية:

    انظر مستويات الوصول في Visual Basic

  • Shadows
    اختياري. راجع الظلال.

  • charsetmodifier
    اختياري. تُعيّن مجموعة أحرف و ملف معلومات بحث. يمكن أن يكون أحد الخيارات التالية:

  • Sub
    اختياري، لكن يجب أن يظهر إما Sub أو Function. يشير إلى أن الإجراء الخارجي لا يقوم بإرجاع قيمة.

  • Function
    اختياري، لكن يجب أن يظهر إما Sub أو Function. يشير إلى أن الإجراء الخارجي يقوم بإرجاع قيمة.

  • name
    مطلوبة. اسم هذا المرجع الخارجي. لمزيد من المعلومات، راجع أسماء العنصر المعرف.

  • Lib
    مطلوبة. يقدم البند Lib، الذي يعرّف الملف الخارجي (ملف DLL أو مورد تعليمات برمجية) الذي يحتوي على إجراء خارجي.

  • libname
    مطلوبة. اسم الملف الذي يحتوي على الإجراء المعرّف.

  • Alias
    اختياري. يشير إلى أن الإجراء الذي يتم تعريفه لا يمكن تحديده ضمن الملف الخاص به بالاسم المحدد في name. تحدد التعريف الخاص به في aliasname.

  • aliasname
    مطلوب إذا استخدمت الكلمة الأساسية Alias. السلسلة التي تعرّف الإجراء بإحدى طريقتين:

    اسم نقطة الإدخال لإجراء داخل الملف الخاص به ضمن علامات اقتباس ("")

    -أو-

    علامة الرقم (#) متبوعة بعدد صحيح يحدد العدد الترتيبي لنقطة إدخال الإجراء الموجودة داخل الملف الخاص به

  • parameterlist
    مطلوب إذا كان الإجراء يأخذ معلمات. انظر قائمة المعلمة

  • returntype
    مطلوب إذا تم تعيين Function و Option Strict كانت On. نوع بيانات القيمة التي تم إرجاعها بواسطة الإجراء.

ملاحظات

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

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

المراجع الخارجية افتراضية للوصول عام (Visual Basic) . يمكنك ضبط مستويات الوصول الخاصة بهم بمعدلات الوصول.

القواعد

  • السمات يمكنك تطبيق سمات إلى مرجع خارجي. أي سمة تطبقها لها تأثير في مشروعك فقط, وليس في الملف الخارجي.

  • معدلات تكون الإجراءات الخارجية (Visual Basic) المشترك ضمنيًا. لا يمكنك استخدام الكلمة الأساسية Shared عند تعريف مرجع خارجي, و لا يمكنك تبديل حالته المشتركة.

    لا يمكن لإجراء خارجي المشاركة في تجاوز, تطبيق واجهة أعضاء أو معالجة أحداث. وفقًا لذلك, لا يمكنك استخدام Overrides, Overridable, NotOverridable, MustOverride, Implements، أو الكلمة الأساسية Handles في العبارة Declare.

  • اسم إجراء خارجي. لا يتوجب عليك إعطاء هذا المرجع الخارجي نفس اسم (في name) نقطة إدخال الإجراء في داخل الملف الخارجي الخاص به (aliasname). يمكنك استخدام البند Alias لتحديد اسم نقطة الإدخال. يمكن أن يكون هذا مفيداً إذا كان الإجراء الخارجي له نفس اسم معدّل Visual Basic محجوز أو متغير, إجراء أو أي عنصر برمجة آخر في نفس النطاق.

    ملاحظة

    معظم أسماء نقاط الإدخال في DLL حساسة لحالة الأحرف.

  • رقم إجراء خارجي. بدلاً من ذلك، يمكن استخدام البند Alias لتحديد العدد الترتيبي لنقطة الإدخال في جدول التصدير للملف الخارجي. للقيام بذلك، ابدأ aliasname بعلامة الرقم (#). يكون هذا مفيداً, إذا كان أي حرف في اسم الإجراء الخارجي غير مسموح به في Visual Basic, أو في حالة تصدير الملف الخارجي للإجراء دون اسم.

قواعد نوع البيانات

  • أنواع بيانات المعلمة. إذا Option Strict كان On، يجب تحديد نوع بيانات كل معلمة في parameterlist. يمكن لهذا أن يكون أي نوع بيانات أو اسم قائمة تعداد، فئة, بنية, أو واجهة. داخل parameterlist، يمكنك استخدام بند As لتحديد نوع بيانات الوسيطة لتمريرها إلى كل معلمة.

    ملاحظة

    إذا لم تتم كتابة الإجراء الخارجي لـ .NET Framework، يجب الانتباه إلى أن أنواع البيانات متطابقة. على سبيل المثال، إذا قمت بتعريف مرجع خارجي إلى إجراء Visual Basic 6.0 باستخدام معلمة Integer (هي 16 بيت في Visual Basic) ، يجب تحديد الوسيطة المناظرة كـ Short في العبارة Declare ، لأن ذلك هو نوع العدد الصحيح ذو 16 بت في Visual Basic. وبشكل مماثل، Long له عرض بيانات مختلف في Visual Basic 6.0، و يتم تطبيق Date بشكل مختلف.

  • إرجاع نوع بيانات. إذا كان الإجراء الخارجي Function و Option Strict كان On، يجب تحديد نوع بيانات القيمة التي يتم إرجاعها إلى التعليمات البرمجية التي استدعتها. يمكن لهذا أن يكون أي نوع بيانات أو اسم قائمة تعداد، فئة, بنية, أو واجهة.

    ملاحظة

    لا يتحقق برنامج التحويل البرمجي Visual Basic من أن أنواع البيانات الخاصة بك متوافقة مع تلك الموجودة في الإجراء الخارجي. في حال وجود عدم توافق, وقت تشغيل اللغة العامة ينشئ استثناء MarshalDirectiveException في وقت التشغيل.

  • أنواع بيانات افتراضية. إذا Option Strict كان Off و لم تحدد نوع البيانات لمعلمة في parameterlist، يحول برنامج التحويل البرمجي Visual Basic الوسيطة المناظرة إلى نوع البيانات كائن. وبنفس الطريقة، إذا لم تقم بتعيين returntype، يأخذ المحول البرمجي نوع البيانات العائد على أنه Object.

    ملاحظة

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

السلوك

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

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

  • استدعاء إجراء خارجي. تقوم باستدعاء إجراء خارجي بنفس الطريقة التي تستدعي فيها Function أو إجراء Sub باستخدامه في تعبير إذا كان يرجع قيمة، أو بواسطة تحديده في عبارة استدعاء (Vsual Basic) إذا كان لا يرجع قيمة.

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

  • مجموعات الأحرف يمكنك تحديد في charsetmodifier كيف يجب على Visual Basic تنظيم وإرسال السلاسل عندما يستدعي الإجراء الخارجي. المعدّل Ansi يوجه Visual Basic لتنظيم وإرسال كل السلاسل إلى قيم ‏‫ANSI و المعدّل Unicode يوجهه لتنظيم وإرسال كل السلاسل إلى قيم Unicode. المعدّل Auto يوجه Visual Basic لتنظيم وإرسال سلاسل وفقاً لقواعد .NET Framework استناداً على المرجع الخارجي name، أو aliasname في حالة تحديده. القيمة الافتراضية هي Ansi.

    charsetmodifier يحدد أيضاً كيف يجب على Visual Basic البحث عن الإجراء الخارجي داخل الملف الخارجي الخاص به. Ansi و Unicode كلاهما يوجهان Visual Basic ليبحث عنه دون تعديل اسمه أثناء البحث. Auto يوجه Visual Basic لتحديد مجموعة الأحرف الأساسية لوقت تشغيل النظام الأساسي وتعديل اسم الإجراء الخارجي إن أمكن كما يلي:

    • على نظام أساسي ‏‫ANSI، مثل ‏‫Windows 95 أو Windows 98 أو Windows Millennium Edition، أولا ابحث عن الإجراء الخارجي دون تعديل الاسم. وإذا فشل ذلك، ألحق "A" إلى نهاية اسم الإجراء الخارجي وابحث عنه مرة أخرى.

    • على نظام أساسي Unicode، مثل Windows NT أو Windows 2000 أو Windows XP، أولا ابحث عن الإجراء الخارجي دون تعديل الاسم. وإذا فشل ذلك، ألحق "W" إلى نهاية اسم الإجراء الخارجي وابحث عنه مرة أخرى.

  • آلية. Visual Basic يستخدم آلية .NET Framework استدعاء النظام الأساسي (PInvoke) لحل والوصول إلى إجراءات خارجية . العبارة Declare و الفئة DllImportAttribute كلاهما يستخدمان هذه الآلية بشكل تلقائي, و لا تحتاج لأي معرفة في PInvoke. لمزيد من المعلومات، راجع الإرشادات التفصيلية: استدعاء Windows API.

ملاحظة الأمانملاحظة الأمان

في حالة تشغيل الإجراء الخارجي خارج وقت تشغيل اللغة العامة (CLR) ، يصبح تعليمات برمجية غير مُدارة . عند استدعاء مثل هذا الإجراء, على سبيل المثال دالة Win32 API أو أسلوب COM، قد تعرّض التطبيق الخاص بك إلى مخاطر أمنية. لمزيد من المعلومات، راجع التعليمات البرمجية غير المُدارة.

مثال

يقوم المثال التالي بتعريف مرجع خارجي إلى إجراء Function الذي يقوم بإرجاع اسم مستخدم الحالي. ثم يستدعي الإجراء الخارجي GetUserNameA كجزء من الإجراء getUser.

Declare Function getUserName Lib "advapi32.dll" Alias "GetUserNameA" (
    ByVal lpBuffer As String, ByRef nSize As Integer) As Integer
Sub getUser()
    Dim buffer As String = New String(CChar(" "), 25)
    Dim retVal As Integer = getUserName(buffer, 25)
    Dim userName As String = Strings.Left(buffer, InStr(buffer, Chr(0)) - 1)
    MsgBox(userName)
End Sub

يوفر DllImportAttribute طريقة بديلة لاستخدام الدوال في التعليمات البرمجية الغير المُدارة. يقوم المثال التالي بتعريف دالة تم استيرادها بدون استخدام العبارة Declare.

' Add an Imports statement at the top of the class, structure, or
' module that uses the DllImport attribute.
Imports System.Runtime.InteropServices

<DllImportAttribute("kernel32.dll", EntryPoint:="MoveFileW", 
    SetLastError:=True, CharSet:=CharSet.Unicode, 
    ExactSpelling:=True, 
    CallingConvention:=CallingConvention.StdCall)> 
Public Shared Function moveFile(ByVal src As String, 
  ByVal dst As String) As Boolean
    ' This function copies a file from the path src to the path dst.
    ' Leave this function empty. The DLLImport attribute forces calls
    ' to moveFile to be forwarded to MoveFileW in KERNEL32.DLL.
End Function

راجع أيضًا:

المهام

الإرشادات التفصيلية: استدعاء Windows API

المرجع

استيراد كشف (مساحة الاسم و نوع NET.)

عامل التشغيل AddressOf

كشف دالة (Visual Basic)

عبارة Vsual Basic) Sub)

قائمة المعلمة

عبارة استدعاء (Vsual Basic)