Declare – příkaz

Článek
06/08/2015

Deklaruje odkaz na postup implementována v externím souboru.

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

Části

Termín	Definice
attributelist	Nepovinné.Viz seznam atributů.
accessmodifier	Nepovinné.Může být jeden z následujících: Veřejné Chráněné Přítel Soukromé Protected Friend Viz téma Úrovně přístupu v jazyce Visual Basic.
Shadows	Nepovinné.Viz stíny.
charsetmodifier	Nepovinné.Určuje znakovou sadu a soubor hledat informace.Může být jeden z následujících: Ansi (Visual Basic)(výchozí) Unicode (Visual Basic) Auto (Visual Basic)
Sub	Volitelné, ale buď Sub nebo Function musí být uvedeny.Označuje, že externí postup nevrací hodnotu.
Function	Volitelné, ale buď Sub nebo Function musí být uvedeny.Označuje, že externí procedura vrací hodnotu.
name	Povinné.Název externího odkazu.Další informace naleznete v tématu Deklarované názvy elementu (Visual Basic).
Lib	Povinné.Zavádí Lib klauzule, který identifikuje externí soubor (knihovny DLL nebo kódového prostředku), který obsahuje externí procedury.
libname	Povinné.Název souboru, který obsahuje deklarovaný postup.
Alias	Nepovinné.Označuje, že probíhá postup nelze identifikovat v rámci svého souboru název zadaný v name.Určit jeho identifikace v aliasname.
aliasname	Požadováno, pokud použijete Alias klíčové slovo.Řetězec, který určuje postup dvěma způsoby: Název položky bod postupu v rámci svého souboru do uvozovek ("") -nebo- Znak čísla (#) následovaný celé číslo určující pořadové číslo vstupní bod procedury v rámci svého souboru
parameterlist	Povinné, pokud trvá parametry.Viz téma Seznam parametrů (Visual Basic).
returntype	Vyžadován, pokud Function je určena a Option Strict je On.Datový typ hodnoty vrácené procedurou.

Poznámky

Někdy potřebujete volání procedury definované v souboru mimo projektu (například knihovny DLL nebo kódového prostředku).Pokud to uděláte, kompilátor Visual Basic nemá přístup k informace potřebné k volání správně postupem, jako například kde je umístěn postupem, jak je identifikována, jeho volací posloupnost a návratový typ a řetězec znakové sady, které používá.Declare Příkaz vytvoří odkaz na externí postup a dodává tyto nezbytné informace.

Můžete použít Declare pouze na úrovni modulu.To znamená prohlášení kontextu pro externí odkaz musí být třída, struktura nebo modul a nemůže být zdrojový soubor, obor názvů, rozhraní, postup nebo bloku.Další informace naleznete v tématu Kontexty deklarace a výchozí úrovně přístupu (Visual Basic).

Externí odkazy na výchozí Public (Visual Basic) přístup.Můžete nastavit jejich úrovně přístupu s modifikátory přístupu.

Pravidla

Atributy. Externí odkaz můžete použít atributy.Všechny atributy, které aplikujete účinek pouze v projektu, nikoli v externím souboru.
Modifikátory. Implicitně jsou externí procedury Shared (Visual Basic).Nelze použít Shared klíčové slovo při deklarování externí odkaz a nelze změnit jeho stav sdílení.

Externí procedury nemůže účastnit přepsání, implementovat členy rozhraní nebo zpracování událostí.Accordingly, you cannot use the Overrides, Overridable, NotOverridable, MustOverride, Implements, or Handles keyword in a Declare statement.
Externí název procedury. Není nutné dát této externí odkaz se stejným názvem (v name) jako název vstupní bod procedury v rámci svého externího souboru (aliasname).Můžete použít Alias klauzule určuje název vstupního bodu.To může být užitečné, pokud externí postup má stejný název jako vyhrazené modifikátor jazyka Visual Basic nebo proměnné, procedury nebo jiné programovací element ve stejném oboru.

[!POZNÁMKA]

Názvy vstupní bod knihovny DLL pro většinu rozlišují malá a velká písmena.
Externí číslo postupu. Můžete použít také Alias klauzule určit vstupní bod v rámci tabulky exportu externí soubor pořadové číslo.To provedete začnete aliasname symbolem čísla (#).To může být užitečné, pokud není povolen libovolný znak v názvu externí procedury v jazyce Visual Basic nebo externí soubor exportuje postup bez názvu.

Pravidla typu dat

Datové typy parametrů. Pokud Option Strict je On, je nutné určit typ dat každého parametru v parameterlist.Může to být libovolný datový typ nebo název výčtu, struktura, třídy nebo rozhraní.V rámci parameterlist, použijte As klauzuli určete datový typ argumentu předávat každý parametr.

[!POZNÁMKA]

Pokud nebyly zapsány externí postup pro.NET Framework je pečlivě, typy dat odpovídají.Například deklarovat externí odkaz na proceduru jazyka Visual Basic 6.0 s Integer parametr (16 bitů v jazyce Visual Basic 6.0) je nutné určit odpovídající argument jako Short v Declare prohlášení, protože typ 16bitové celé číslo v jazyce Visual Basic.Podobně Long má šířku různá data v jazyce Visual Basic 6.0 a Date je implementováno jiným způsobem.
Typ dat vrátíte. Je-li externí postup Function a Option Strict je On, je nutné určit typ dat hodnoty vrácené volání kódu.Může to být libovolný datový typ nebo název výčtu, struktura, třídy nebo rozhraní.

[!POZNÁMKA]

Kompilátor Visual Basic neověřuje, že datové typy jsou kompatibilní s externí procedury.Pokud se neshodují, generuje společného jazykového modulu runtime MarshalDirectiveException výjimka za běhu.
Výchozí datové typy. Pokud Option Strict je Off a neurčíte typ dat parametru v parameterlist, kompilátor Visual Basic převede na odpovídající argument Datový typ objektu.Podobně pokud nezadáte returntype, kompilátor trvá návrat datový typ je Object.

[!POZNÁMKA]

Protože se zabývají externí postupem, který může být napsán na jiné platformě, je nebezpečné všechny předpoklady typy dat nebo Povolit výchozí.Je mnohem bezpečnější určete datový typ každého parametru a vrácené hodnoty případné.To také zlepšuje čitelnost kódu.

Chování

Obor. Externí odkaz je v rozsahu celé své třídy, struktury nebo modulu.
Doba života. Externí odkaz má stejnou životnost jako třída, struktura nebo modul, který je deklarován.
Volání externích procedur. Volání procedury externí stejným způsobem jako při volání Function nebo Sub postup – pomocí ve výrazu, pokud vrátí hodnotu nebo ji v určením Call – příkaz (Visual Basic) Pokud nevrací hodnotu.

Předat argumenty externí postupem přesně podle parameterlist v Declare prohlášení.V úvahu jak bylo původně deklarováno parametry v externím souboru.Podobně pokud je vrácená hodnota, použít ji přesně podle returntype v Declare prohlášení.
Sady znaků. Můžete určit v charsetmodifier jak by Visual Basic zařazování řetězce při externí procedury volá.Ansi Modifikátor nařizuje Visual Basic k zařazování všechny řetězce ANSI hodnoty a Unicode modifikátor směruje jej k zařazování všechny řetězce hodnoty Unicode.Auto Modifikátor přesměruje na řetězec marshal podle jazyka Visual Basic.NET Framework pravidla, na základě externího odkazu name, nebo aliasname -li zadán.Výchozí hodnota je Ansi.

charsetmodifiertaké určuje, jak by Visual Basic vyhledat externí procedury v rámci svého externího souboru.Ansia Unicode i přímé Visual Basic vyhledat bez úpravy názvu při vyhledávání.Autopřesměruje Visual Basic určit základní znakové sady platform spuštění a případně změnit název externí procedury takto:
- Na platformě ANSI, jako je například Windows 95, Windows 98 nebo Windows Millennium Edition nejprve vyhledejte externí postup bez úprav název.Pokud se nezdaří, připojit "A" na konec názvu externí procedury a znovu vyhledat.
- Na platformě Unicode, jako například Windows NT, Windows 2000 nebo Windows XP nejprve vyhledejte externí postup bez úprav název.Pokud se nezdaří, připojit na konec externí postup "W" název a znovu vyhledat.
Mechanismus. Použití jazyka Visual Basic.NET Framework platform vyvolat (PInvoke) mechanismus řešení a externí procedury.Declare Prohlášení a DllImportAttribute třídy i pomocí tohoto mechanismu automaticky a není nutné žádné znalosti PInvoke.Další informace naleznete v tématu Návod: Volání rozhraní API systému Windows (Visual Basic).

Poznámka k zabezpečení
Pokud externí procedury mimo společného jazykového modulu runtime (CLR), je nespravovaný kód.Při volání takového postupu, například rozhraní Win32 API funkce nebo metody COM, může být aplikace bezpečnostním rizikům.Další informace naleznete v tématu Nespravovaný kód.

Příklad

Následující příklad deklaruje externí odkaz na Function procedura, která vrací aktuální uživatelské jméno.Poté vyvolá externí procedury GetUserNameA jako součást getUser postup.

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 Poskytuje alternativní způsob použití funkcí v nespravovaný kód.Následující příklad prohlašuje importované funkce bez použití Declare prohlášení.

' 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