Compartilhar via

Instrução Declare

Declara uma referência a um procedimento implementado em um arquivo externo.

Sintaxe

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

Partes

Prazo Definição
attributelist Opcional. Consulte a Lista de Atributos.
accessmodifier Opcional. Pode ser um dos seguintes:

- Público
- Protegido
- Amigo
- Privado
- Amigo Protegido
- Proteção Privada

Consulte Níveis de acesso no Visual Basic.
Shadows Opcional. Veja Sombras.
charsetmodifier Opcional. Especifica informações de conjunto de caracteres e pesquisa de arquivo. Pode ser um dos seguintes:

- Ansi (padrão)
- Unicode
- Automático
Sub Opcional, mas ou SubFunction deve aparecer. Indica que o procedimento externo não retorna um valor.
Function Opcional, mas ou SubFunction deve aparecer. Indica que o procedimento externo retorna um valor.
name Obrigatório Nome dessa referência externa. Para obter mais informações, consulte Nomes de Elementos Declarados.
Lib Obrigatório Introduz uma Lib cláusula, que identifica o arquivo externo (DLL ou recurso de código) que contém um procedimento externo.
libname Obrigatório Nome do arquivo que contém o procedimento declarado.
Alias Opcional. Indica que o procedimento que está sendo declarado não pode ser identificado em seu arquivo pelo nome especificado em name. Especifique sua identificação em aliasname.
aliasname Obrigatório se você usar a Alias palavra-chave. Cadeia de caracteres que identifica o procedimento de uma das duas maneiras:

O nome do ponto de entrada do procedimento em seu arquivo, entre aspas ("")

- ou -

Um sinal numérico (#) seguido por um inteiro especificando o número ordinal do ponto de entrada do procedimento em seu arquivo
parameterlist Necessário se o procedimento usa parâmetros. Consulte Lista de parâmetros.
returntype Obrigatório se Function for especificado e Option Strict for On. Tipo de dados do valor retornado pelo procedimento.

Observações

Às vezes, você precisa chamar um procedimento definido em um arquivo (como uma DLL ou um recurso de código) fora do projeto. Quando você faz isso, o compilador do Visual Basic não tem acesso às informações necessárias para chamar o procedimento corretamente, como onde o procedimento está localizado, como ele é identificado, sua sequência de chamadas e tipo de retorno e o conjunto de caracteres de cadeia de caracteres que ele usa. A Declare instrução cria uma referência a um procedimento externo e fornece essas informações necessárias.

Você só pode usar Declare no nível do módulo. Isso significa que o contexto de declaração para uma referência externa deve ser uma classe, estrutura ou módulo e não pode ser um arquivo de origem, namespace, interface, procedimento ou bloco. Para obter mais informações, consulte contextos de declaração e níveis de acesso padrão.

Referências externas padrão para acesso público . Você pode ajustar os níveis de acesso com os modificadores de acesso.

Regras

  • Atributos. Você pode aplicar atributos a uma referência externa. Qualquer atributo aplicado só tem efeito em seu projeto, não no arquivo externo.

  • Modificadores. Os procedimentos externos são implicitamente compartilhados. Você não pode usar a Shared palavra-chave ao declarar uma referência externa e não pode alterar seu status compartilhado.

    Um procedimento externo não pode participar na substituição, implementação de membros da interface ou manipulação de eventos. Assim, você não pode usar a Overridespalavra-chave , , NotOverridableOverridable, MustOverrideImplementsou Handles palavra-chave em uma Declare instrução.

  • Nome do procedimento externo. Você não precisa dar a essa referência externa o mesmo nome (em name) que o nome do ponto de entrada do procedimento em seu arquivo externo (aliasname). Você pode usar uma Alias cláusula para especificar o nome do ponto de entrada. Isso pode ser útil se o procedimento externo tiver o mesmo nome de um modificador reservado do Visual Basic ou uma variável, procedimento ou qualquer outro elemento de programação no mesmo escopo.

    Observação

    Os nomes de ponto de entrada na maioria das DLLs diferenciam maiúsculas de minúsculas.

  • Número do procedimento externo. Como alternativa, você pode usar uma Alias cláusula para especificar o número ordinal do ponto de entrada dentro da tabela de exportação do arquivo externo. Para fazer isso, comece aliasname com um sinal de número (#). Isso pode ser útil se qualquer caractere no nome do procedimento externo não for permitido no Visual Basic ou se o arquivo externo exportar o procedimento sem um nome.

Regras de tipo de dados

  • Tipos de dados de parâmetro. Se Option Strict estiver On, você deve especificar o tipo de dados de cada parâmetro em parameterlist. Pode ser qualquer tipo de dados ou o nome de uma enumeração, estrutura, classe ou interface. Dentro parameterlist, você usa uma As cláusula para especificar o tipo de dados do argumento a ser passado para cada parâmetro.

    Observação

    Se o procedimento externo não foi gravado para o .NET Framework, você deve ter cuidado para que os tipos de dados correspondam. Por exemplo, se você declarar uma referência externa a um procedimento do Visual Basic 6.0 com um Integer parâmetro (16 bits no Visual Basic 6.0), deverá identificar o argumento correspondente como Short na Declare instrução, pois esse é o tipo inteiro de 16 bits no Visual Basic. Da mesma forma, Long tem uma largura de dados diferente no Visual Basic 6.0 e Date é implementada de forma diferente.

  • Tipo de dados de retorno. Se o procedimento externo for um Function e Option Strict for On, você deverá especificar o tipo de dados do valor retornado ao código de chamada. Pode ser qualquer tipo de dados ou o nome de uma enumeração, estrutura, classe ou interface.

    Observação

    O compilador do Visual Basic não verifica se os tipos de dados são compatíveis com os do procedimento externo. Se houver uma incompatibilidade, o common language runtime gerará uma MarshalDirectiveException exceção em tempo de execução.

  • Tipos de dados padrão. Se Option Strict for Off e você não especificar o tipo de dados de um parâmetro, parameterlisto compilador do Visual Basic converterá o argumento correspondente para o Tipo de Dados de Objeto. Da mesma forma, se você não especificar returntype, o compilador usará o tipo de dados de retorno para ser Object.

    Observação

    Como você está lidando com um procedimento externo que pode ter sido escrito em uma plataforma diferente, é perigoso fazer suposições sobre tipos de dados ou permitir que eles sejam padrão. É muito mais seguro especificar o tipo de dados de cada parâmetro e do valor retornado, se houver. Isso também melhora a legibilidade do código.

Comportamento

  • Escopo. Uma referência externa está no escopo em toda a classe, estrutura ou módulo.

  • Vida. Uma referência externa tem o mesmo tempo de vida que a classe, a estrutura ou o módulo no qual ela é declarada.

  • Chamando um procedimento externo. Você chama um procedimento externo da mesma forma que chama um Function procedimento ou Sub um procedimento, usando-o em uma expressão se ele retorna um valor ou especificando-o em uma Instrução de Chamada se ele não retornar um valor.

    Você passa argumentos para o procedimento externo exatamente como especificado na parameterlist instrução Declare . Não leve em conta como os parâmetros foram declarados originalmente no arquivo externo. Da mesma forma, se houver um valor retornado, use-o exatamente como especificado na returntype instrução Declare .

  • Conjuntos de caracteres. Você pode especificar como charsetmodifier o Visual Basic deve fazer marshaling de cadeias de caracteres quando ele chama o procedimento externo. O Ansi modificador direciona o Visual Basic para fazer marshaling de todas as cadeias de caracteres para valores ANSI e o modificador o Unicode direciona para fazer marshaling de todas as cadeias de caracteres para valores Unicode. O Auto modificador direciona o Visual Basic para realizar marshaling de cadeias de caracteres de acordo com as regras do .NET Framework com base na referência nameexterna ou aliasname se especificado. O valor padrão é Ansi.

    charsetmodifier também especifica como o Visual Basic deve pesquisar o procedimento externo em seu arquivo externo. Ansi e Unicode o Visual Basic direto para pesquisá-lo sem modificar seu nome durante a pesquisa. Auto direciona o Visual Basic para determinar o conjunto de caracteres base da plataforma em tempo de execução e, possivelmente, modificar o nome do procedimento externo, da seguinte maneira:

    • Em uma plataforma Unicode, como o Windows, primeiro procure o procedimento externo sem modificação de nome. Se isso falhar, acrescente "W" ao final do nome do procedimento externo e procure-o novamente.

    • Em uma plataforma ANSI, primeiro procure o procedimento externo sem modificação de nome. Se isso falhar, acrescente "A" ao final do nome do procedimento externo e procure-o novamente.

  • Mecanismo. O Visual Basic usa o mecanismo PInvoke ( invocação de plataforma do .NET Framework) para resolver e acessar procedimentos externos. A Declare instrução e a DllImportAttribute classe usam esse mecanismo automaticamente e você não precisa de nenhum conhecimento do PInvoke. Para obter mais informações, consulte Passo a passo: chamando APIs do Windows.

Importante

Se o procedimento externo for executado fora do CLR (Common Language Runtime), ele será um código não gerenciado. Ao chamar esse procedimento, por exemplo, uma função de API do Windows ou um método COM, você pode expor seu aplicativo a riscos de segurança. Para obter mais informações, consulte Diretrizes de codificação segura para código não gerenciado.

Exemplo 1

O exemplo a seguir declara uma referência externa a um Function procedimento que retorna o nome de usuário atual. Em seguida, ele chama o procedimento GetUserNameA externo como parte do getUser procedimento.

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

Exemplo 2

Fornece DllImportAttribute uma maneira alternativa de usar funções em código não gerenciado. O exemplo a seguir declara uma função importada sem usar uma Declare instrução.

' 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

Consulte também

  • Last updated on