Bagikan melalui

Pernyataan Declare (Deklarasikan)

  • Artikel

Mendeklarasikan referensi ke prosedur yang diterapkan dalam file eksternal.

Sintaks

[ <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 ]

Generator

Term Definisi
attributelist Opsional. Lihat Daftar Atribut.
accessmodifier Opsional. Bisa jadi salah satu dari yang berikut:

- Publik
- Terlindungi
- Teman
- Privat
- Teman yang Terlindungi
- Dilindungi secara Privat

Lihat Tingkat akses di Visual Basic.
Shadows Opsional. Lihat Bayangan.
charsetmodifier Opsional. Menentukan kumpulan karakter dan informasi pencarian file. Bisa jadi salah satu dari yang berikut:

- Ansi (default)
- Unicode
- Auto
Sub Opsional, tetapi salah satu Sub atau Function harus muncul. Menunjukkan bahwa prosedur eksternal tidak mengembalikan nilai.
Function Opsional, tetapi salah satu Sub atau Function harus muncul. Menunjukkan bahwa prosedur eksternal mengembalikan nilai.
name Harus diisi. Nama referensi eksternal ini. Untuk informasi selengkapnya, lihat Nama Elemen yang Dideklarasikan.
Lib Harus diisi. Memperkenalkan klausul Lib, yang mengidentifikasi file eksternal (DLL atau sumber daya kode) yang berisi prosedur eksternal.
libname Harus diisi. Nama file yang berisi prosedur yang dinyatakan.
Alias Opsional. Menunjukkan bahwa prosedur yang dideklarasikan tidak dapat diidentifikasi dalam filenya dengan nama yang ditentukan dalam name. Anda menentukan identifikasinya di aliasname.
aliasname Diperlukan jika Anda menggunakan kata kunci Alias. String yang mengidentifikasi prosedur dengan salah satu dari dua cara:

Nama titik entri prosedur dalam filenya, dalam tanda kutip ("")

-atau-

Tanda angka (#) diikuti dengan integer yang menentukan nomor ordinal titik entri prosedur dalam filenya
parameterlist Diperlukan jika prosedur mengambil parameter. Lihat Daftar parameter.
returntype Diperlukan jika Function ditentukan dan Option Strict adalah On. Jenis data nilai yang dikembalikan oleh prosedur.

Keterangan

Terkadang Anda perlu memanggil prosedur yang ditentukan dalam file (seperti DLL atau sumber daya kode) di luar proyek Anda. Ketika Anda melakukan ini, kompiler Visual Basic tidak memiliki akses ke informasi yang dibutuhkan untuk memanggil prosedur dengan benar, seperti di mana prosedur berada, bagaimana diidentifikasi, urutan panggilan dan jenis pengembaliannya, dan set karakter string yang digunakannya. Pernyataan Declare membuat referensi ke prosedur eksternal dan menyediakan informasi yang diperlukan ini.

Anda dapat menggunakan Declare hanya pada tingkat modul. Ini berarti konteks deklarasi untuk referensi eksternal harus berupa kelas, struktur, atau modul, dan tidak boleh berupa file sumber, namespace, antarmuka, prosedur, atau blok. Untuk informasi selengkapnya, lihat Konteks Deklarasi dan Tingkat Akses Default.

Referensi eksternal default ke Akses Publik. Anda dapat menyesuaikan tingkat aksesnya dengan pengubah akses.

Aturan

  • Atribut. Anda dapat menerapkan atribut ke referensi eksternal. Atribut apa pun yang Anda terapkan hanya berpengaruh pada proyek Anda, bukan di file eksternal.

  • Pengubah. Prosedur eksternal dibagikan secara implisit. Anda tidak dapat menggunakan kata kunci Shared saat mendeklarasikan referensi eksternal, dan Anda tidak dapat mengubah status berbaginya.

    Prosedur eksternal tidak dapat berpartisipasi dalam menimpa, mengimplementasikan anggota antarmuka, atau menangani peristiwa. Dengan demikian, Anda tidak dapat menggunakan kata kunci Overrides, Overridable, NotOverridable, MustOverride, Implements atau Handles dalam pernyataan Declare.

  • Nama Prosedur Eksternal. Anda tidak perlu memberikan referensi eksternal ini nama yang sama (dalam name) sebagai nama titik entri prosedur dalam file eksternalnya (aliasname). Anda dapat menggunakan klausul Alias untuk menentukan nama titik entri. Ini dapat berguna jika prosedur eksternal memiliki nama yang sama dengan pengubah yang dicadangkan Visual Basic atau variabel, prosedur, atau elemen pemrograman lainnya dalam ruang lingkup yang sama.

    Catatan

    Nama titik entri di sebagian besar DLL peka huruf besar/kecil.

  • Nomor Prosedur Eksternal. Atau, Anda dapat menggunakan klausul Alias untuk menentukan nomor ordinal titik entri dalam tabel ekspor file eksternal. Untuk melakukan ini, Anda mulai aliasname dengan tanda angka (#). Ini dapat berguna jika ada karakter dalam nama prosedur eksternal yang tidak diizinkan dalam Visual Basic, atau jika file eksternal mengekspor prosedur tanpa nama.

Aturan Jenis Data

  • Jenis Data Parameter. Jika Option Strict adalah On, Anda harus menentukan jenis data dari setiap parameter di parameterlist. Ini bisa berupa jenis data atau nama enumerasi, struktur, kelas, atau antarmuka. Dalam parameterlist, Anda menggunakan klausul As untuk menentukan jenis data argumen yang akan diteruskan ke setiap parameter.

    Catatan

    Jika prosedur eksternal tidak ditulis untuk .NET Framework, Anda harus berhati-hati agar jenis data sesuai. Misalnya, jika Anda mendeklarasikan referensi eksternal ke prosedur Visual Basic 6.0 dengan parameter Integer (16 bit dalam Visual Basic 6.0), Anda harus mengidentifikasi argumen yang sesuai seperti Short dalam pernyataan Declare, karena itu adalah jenis integer 16-bit dalam Visual Basic. Demikian pula, Long memiliki lebar data yang berbeda di Visual Basic 6.0, dan Date diimplementasikan secara berbeda.

  • Jenis Data Kembalian. Jika prosedur eksternal adalah Function dan Option Strict adalah On, Anda harus menentukan jenis data nilai yang dikembalikan ke kode panggilan. Ini bisa berupa jenis data atau nama enumerasi, struktur, kelas, atau antarmuka.

    Catatan

    Kompiler Visual Basic tidak memverifikasi bahwa jenis data Anda kompatibel dengan prosedur eksternal. Jika ada ketidakcocokan, runtime bahasa umum menghasilkan pengecualian MarshalDirectiveException pada durasi.

  • Jenis Data Default. Jika Option Strict adalah Off dan Anda tidak menentukan jenis data parameter di parameterlist, kompiler Visual Basic mengonversi argumen yang sesuai ke Jenis Data Objek. Demikian pula, jika Anda tidak menentukan returntype, kompiler mengambil jenis data kembalian menjadi Object.

    Catatan

    Karena Anda berurusan dengan prosedur eksternal yang mungkin telah ditulis pada platform yang berbeda, berbahaya untuk membuat asumsi tentang jenis data atau mengizinkannya menjadi default. Jauh lebih aman menentukan jenis data dari setiap parameter dan nilai pengembalian, jika ada. Ini juga meningkatkan keterbacaan kode Anda.

Perilaku

  • Cakupan. Referensi eksternal berada dalam lingkup di seluruh kelas, struktur, atau modulnya.

  • Masa pakai. Referensi eksternal memiliki masa hidup yang sama dengan kelas, struktur, atau modul tempat ia dinyatakan.

  • Memanggil Prosedur Eksternal. Anda memanggil prosedur eksternal dengan cara yang sama seperti Anda memanggil prosedur Function atau Sub —dengan menggunakannya dalam ekspresi jika itu mengembalikan nilai, atau dengan menentukannya dalam Pernyataan Call jika tidak mengembalikan nilai.

    Anda meneruskan argumen ke prosedur eksternal persis seperti yang ditentukan oleh parameterlist dalam pernyataan Declare. Jangan memperhitungkan bagaimana parameter awalnya dideklarasikan dalam file eksternal. Demikian pula, jika ada nilai pengembalian, gunakan persis seperti yang ditentukan oleh returntype dalam pernyataan Declare.

  • Kumpulan Karakter. Anda dapat menentukan dalam charsetmodifier bagaimana Visual Basic harus menggunakan string marshal saat memanggil prosedur eksternal. Pengubah Ansi mengarahkan Visual Basic ke marshal semua string ke nilai ANSI, dan pengubah Unicode mengarahkannya ke marshal semua string ke nilai Unicode. Pengubah Auto mengarahkan Visual Basic ke string marshal sesuai dengan aturan .NET Framework berdasarkan referensi eksternal name, atau aliasname jika ditentukan. Nilai defaultnya adalah Ansi.

    charsetmodifier juga menentukan bagaimana Visual Basic harus mencari prosedur eksternal dalam file eksternalnya. Ansi dan Unicode keduanya mengarahkan Visual Basic untuk mencarinya tanpa memodifikasi namanya selama pencarian. Auto mengarahkan Visual Basic untuk menentukan kumpulan karakter dasar platform run-time dan mungkin mengubah nama prosedur eksternal, sebagai berikut:

    • Pada platform Unicode, seperti Windows, pertama cari prosedur eksternal tanpa modifikasi nama. Jika gagal, tambahkan "W" ke akhir nama prosedur eksternal dan cari lagi.

    • Pada platform ANSI, pertama cari prosedur eksternal tanpa modifikasi nama. Jika gagal, tambahkan "A" ke akhir nama prosedur eksternal dan cari lagi.

  • Mekanisme. Visual Basic menggunakan mekanisme pemanggilan platform .NET Framework (PInvoke) untuk menyelesaikan dan mengakses prosedur eksternal. Pernyataan Declare dan kelas DllImportAttribute keduanya menggunakan mekanisme ini secara otomatis, dan Anda tidak memerlukan pengetahuan tentang PInvoke. Untuk informasi selengkapnya, lihat Panduan: Memanggil API Windows.

Penting

Jika prosedur eksternal berjalan di luar runtime bahasa umum (CLR), itu adalah kode yang tidak dikelola. Ketika Anda memanggil prosedur seperti itu, misalnya fungsi API Windows atau metode COM, Anda mungkin mengekspos aplikasi Anda ke risiko keamanan. Untuk informasi selengkapnya, lihat Panduan Pengodean Aman untuk Kode Tidak Terkelola.

Contoh 1

Contoh berikut mendeklarasikan referensi eksternal ke prosedur Function yang mengembalikan nama pengguna saat ini. Kemudian memanggil prosedur eksternal GetUserNameA sebagai bagian dari prosedur 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

Contoh 2

DllImportAttribute menyediakan cara alternatif untuk menggunakan fungsi dalam kode yang tidak dikelola. Contoh berikut mendeklarasikan fungsi yang diimpor tanpa menggunakan pernyataan 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

Lihat juga