Declare – příkaz

Článek
03/05/2024

Deklaruje odkaz na proceduru implementovanou v externím souboru.

Syntaxe

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

Součástky

Pojem	definice
`attributelist`	Nepovinné. Viz seznam atributů.
`accessmodifier`	Nepovinné. Může to být jedna z následujících možností: - Public - Protected - Friend - Private - Protected Friend - Private Protected Viz úrovně Accessu v jazyce Visual Basic.
`Shadows`	Nepovinné. Podívejte se na stíny.
`charsetmodifier`	Nepovinné. Určuje znakové sady a informace o hledání souborů. Může to být jedna z následujících možností: - Ansi (výchozí) - Unicode - Auto
`Sub`	Volitelné, ale `Sub` musí se zobrazit nebo `Function` musí. Označuje, že externí procedura nevrací hodnotu.
`Function`	Volitelné, ale `Sub` musí se zobrazit nebo `Function` musí. Označuje, že externí procedura vrací hodnotu.
`name`	Povinný: Název tohoto externího odkazu Další informace naleznete v tématu Deklarované názvy elementů.
`Lib`	Povinný: `Lib` Zavádí klauzuli, která identifikuje externí soubor (dll nebo prostředek kódu), který obsahuje externí proceduru.
`libname`	Povinný: Název souboru, který obsahuje deklarovanou proceduru.
`Alias`	Nepovinné. Označuje, že procedura deklarovaná nelze v rámci souboru identifikovat názvem zadaným v `name`. Určíte jeho identifikaci v `aliasname`.
`aliasname`	Vyžaduje se, pokud použijete `Alias` klíčové slovo. Řetězec, který identifikuje proceduru jedním ze dvou způsobů: Název vstupního bodu procedury v souboru v uvozovkách (`""`) nebo Znaménko čísla (`#`) následované celé číslo určující pořadové číslo vstupního bodu procedury v rámci souboru
`parameterlist`	Vyžaduje se, pokud procedura přebírá parametry. Viz seznam parametrů.
`returntype`	Vyžaduje se, pokud `Function` je zadána a `Option Strict` je `On`. Datový typ hodnoty vrácené postupem.

Poznámky

Někdy potřebujete volat proceduru definovanou v souboru (například knihovně DLL nebo zdroji kódu) mimo váš projekt. Když to uděláte, kompilátor jazyka Visual Basic nemá přístup k informacím, které potřebuje správně volat proceduru, například kde je procedura umístěna, jak je identifikována, její volající sekvence a návratový typ, a řetězcová znaková sada, kterou používá. Příkaz Declare vytvoří odkaz na externí proceduru a poskytuje tyto nezbytné informace.

Můžete použít Declare pouze na úrovni modulu. To znamená, že kontext deklarace externího odkazu musí být třída, struktura nebo modul a nemůže to být zdrojový soubor, obor názvů, rozhraní, procedura nebo blok. Další informace naleznete v tématu Kontexty deklarace a výchozí úrovně přístupu.

Externí odkazy mají výchozí veřejný přístup. Jejich úrovně přístupu můžete upravit pomocí modifikátorů přístupu.

Pravidla

Atributy. Na externí odkaz můžete použít atributy. Jakýkoli atribut, který použijete, má vliv jenom v projektu, ne v externím souboru.
Modifikátory. Externí procedury jsou implicitně sdíleny. Klíčové slovo nelze použít Shared při deklarování externího odkazu a nemůžete změnit jeho sdílený stav.

Externí procedura se nemůže účastnit přepsání, implementace členů rozhraní ani zpracování událostí. Proto nelze v příkazu použít Overridesklíčové slovo , , NotOverridableOverridableImplementsMustOverridenebo Handles klíčové slovo.Declare
Název externí procedury. Tento externí odkaz nemusíte udělovat stejnému názvu (v name) jako název vstupního bodu procedury v rámci externího souboru (aliasname). Pomocí klauzule můžete Alias zadat název vstupního bodu. To může být užitečné, pokud má externí procedura stejný název jako vyhrazený modifikátor jazyka Visual Basic nebo proměnná, procedura nebo jakýkoli jiný programovací prvek ve stejném oboru.

Poznámka:

V názvech vstupních bodů ve většině knihoven DLL se rozlišují malá a velká písmena.
Číslo externí procedury. Alternativně můžete použít Alias klauzuli k určení pořadového čísla vstupního bodu v tabulce exportu externího souboru. Uděláte to tak, že začnete aliasname znaménkem čísla (#). To může být užitečné, pokud žádný znak v názvu externí procedury není povolen v jazyce Visual Basic nebo pokud externí soubor exportuje proceduru bez názvu.

Pravidla datových typů

Datové typy parametrů. Pokud Option Strict je On, je nutné zadat datový typ každého parametru v parameterlist. Může to být libovolný datový typ nebo název výčtu, struktury, třídy nebo rozhraní. Uvnitř parameterlistpoužijete As klauzuli k určení datového typu argumentu, který se má předat každému parametru.

Poznámka:

Pokud externí procedura nebyla napsána pro rozhraní .NET Framework, je nutné zajistit, aby datové typy odpovídaly. Pokud například deklarujete externí odkaz na proceduru jazyka Visual Basic 6.0 s parametrem Integer (16 bitů v jazyce Visual Basic 6.0), musíte určit odpovídající argument jako Short v Declare příkazu, protože se jedná o 16bitový celočíselnou typ v jazyce Visual Basic. Long Podobně má odlišnou šířku dat v jazyce Visual Basic 6.0 a Date implementuje se odlišně.
Návratový datový typ Pokud je externí procedura a FunctionOption Strict je On, musíte zadat datový typ hodnoty vrácené volajícímu kódu. Může to být libovolný datový typ nebo název výčtu, struktury, třídy nebo rozhraní.

Poznámka:

Kompilátor jazyka Visual Basic neověřuje, zda jsou datové typy kompatibilní s externí procedurou. Pokud dojde k neshodě, modul CLR (Common Language Runtime) vygeneruje MarshalDirectiveException výjimku za běhu.
Výchozí datové typy Pokud Option Strict je Off a nezadáte datový typ parametru v parameterlist, kompilátor jazyka Visual Basic převede odpovídající argument na datový typ objektu. Podobně, pokud nezadáte returntype, kompilátor převezme návratový datový typ být Object.

Poznámka:

Vzhledem k tomu, že pracujete s externí procedurou, která by mohla být napsána na jiné platformě, je nebezpečné provést jakékoli předpoklady o datových typech nebo umožnit jejich výchozí nastavení. Je mnohem bezpečnější zadat datový typ každého parametru a návratové hodnoty, pokud existuje. To také zlepšuje čitelnost kódu.

Chování

Rozsah. Externí odkaz je v oboru ve své třídě, struktuře nebo modulu.
Životnost: Externí odkaz má stejnou životnost jako třída, struktura nebo modul, ve kterém je deklarován.
Volání externí procedury Externí proceduru voláte stejným způsobem, jakým voláte proceduru Function nebo Sub proceduru – jejím použitím ve výrazu, pokud vrací hodnotu, nebo zadáním v příkazu volání, pokud nevrací hodnotu.

Do externí procedury předáte argumenty přesně tak, jak je specifikováno parameterlist v Declare příkazu. Nebere v úvahu, jak byly parametry původně deklarovány v externím souboru. Podobně pokud existuje návratová hodnota, použijte ji přesně tak, jak je zadáno returntypeDeclare v příkazu.
Znakové sady Můžete určit charsetmodifier , jak má Jazyk Visual Basic zařaizovat řetězce při volání externí procedury. Ansi Modifikátor směruje Jazyk Visual Basic k zařazování všech řetězců na hodnoty ANSI a Unicode modifikátor ho směruje na zařazování všech řetězců na hodnoty Unicode. Auto Modifikátor směruje Jazyk Visual Basic na zařazování řetězců podle pravidel rozhraní .NET Framework na základě externího odkazu name, nebo aliasname pokud je zadán. Výchozí hodnota je Ansi.

charsetmodifier Určuje také, jak má Jazyk Visual Basic vyhledat externí proceduru v rámci svého externího souboru. Ansi a Unicode jak přímo Visual Basic, aby ho vyhledal beze změny jeho názvu během hledání. Auto směruje Jazyk Visual Basic k určení základní znakové sady platformy runtime a případně úpravě názvu externí procedury následujícím způsobem:
- Na platformě Unicode, jako je například Windows, nejprve vyhledejte externí proceduru bez úpravy názvu. Pokud se to nezdaří, připojte na konec názvu externí procedury "W" a znovu ho vyhledejte.
- Na platformě ANSI nejprve vyhledejte externí proceduru bez úpravy názvu. Pokud se to nezdaří, připojte na konec názvu externí procedury "A" a znovu ho vyhledejte.
Mechanismus. Visual Basic používá mechanismus volání platformy .NET Framework (PInvoke) k řešení externích procedur a přístupu k němu. Příkaz Declare i DllImportAttribute třída používají tento mechanismus automaticky a nepotřebujete žádné znalosti PInvoke. Další informace naleznete v tématu Návod: Volání rozhraní API systému Windows.

Důležité

Pokud se externí procedura spouští mimo modul CLR (Common Language Runtime), jedná se o nespravovaný kód. Při volání takového postupu, například funkce rozhraní API systému Windows nebo metoda MODELU COM, můžete aplikaci vystavit rizikům zabezpečení. Další informace naleznete v tématu Pokyny pro zabezpečené kódování pro nespravovaný kód.

Příklad 1

Následující příklad deklaruje externí odkaz na proceduru Function , která vrací aktuální uživatelské jméno. Potom volá externí proceduru GetUserNameAgetUser jako součást procedury.

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

Příklad 2

Poskytuje DllImportAttribute alternativní způsob použití funkcí v nespravovaném kódu. Následující příklad deklaruje importovanou funkci bez použití Declare příkazu.

' 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