DllImportAttribute.PreserveSig Campo
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Indica se os métodos não gerenciados que têm HRESULT valores retornados são traduzidos diretamente ou se HRESULT os valores retornados são convertidos automaticamente em exceções.
public: bool PreserveSig;public bool PreserveSig;val mutable PreserveSig : boolPublic PreserveSig As Boolean Valor do campo
Exemplos
O exemplo de código a seguir usa o DllImportAttribute para importar a função não gerenciada SHAutoComplete uma vez com o PreserveSig campo definido true como e novamente com o PreserveSig campo definido como false. Este exemplo de código faz com que a SHAutoComplete função gere erros com uma exceção uma vez e outra HRESULT .
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
internal class Win32
{
// The SHAutoComplete function allows you
// to add auto-compete functionality to your
// Windows Forms text boxes. In .NET Framework
// 1.1 and earlier, you can use SHAutoComplete.
// Later versions have this ability built in without
// requiring platform invoke.
// See the MSDN documentation of the
// SHAutoComplete function for the
// complete set of flags.
public enum SHAutoCompleteFlags
{
SHACF_DEFAULT = 0x00000000,
SHACF_FILESYSTEM = 0x00000001
}
// Use the DllImportAttribute to import the SHAutoComplete function.
// Set the PreserveSig to false to specify exception errors.
[DllImportAttribute("shlwapi.dll", EntryPoint = "SHAutoComplete", ExactSpelling = true, PreserveSig = false)]
public static extern void SHAutoComplete(IntPtr hwndEdit, SHAutoCompleteFlags dwFlags);
// Use the DllImportAttribute to import the SHAutoComplete function.
// Use the default value of the PreserveSig field to specify HRESULT errors.
[DllImportAttribute("shlwapi.dll", EntryPoint = "SHAutoComplete", ExactSpelling = true)]
public static extern int SHAutoCompleteHRESULT(IntPtr hwndEdit, SHAutoCompleteFlags dwFlags);
}
static class Program
{
static void Main()
{
Run();
}
static void Run()
{
// Create a null (nothing in Visual Basic) IntPtr
// to pass to the SHAutoComplete method. Doing so
// creates a failure and demonstrates the two ways
// that the PreserveSig property allows you to handle
// failures.
// Normally, you would pass a handle to a managed
// Windows Forms text box.
IntPtr iPtr = new IntPtr(0);
// Call the SHAutoComplete function using exceptions.
try
{
Console.WriteLine("Calling the SHAutoComplete method with the PreserveSig field set to false.");
Win32.SHAutoComplete(iPtr, Win32.SHAutoCompleteFlags.SHACF_DEFAULT);
}
catch (Exception e)
{
Console.WriteLine("Exception handled: " + e.Message);
}
Console.WriteLine("Calling the SHAutoComplete method with the PreserveSig field set to true.");
// Call the SHAutoComplete function using HRESULTS.
int HRESULT = Win32.SHAutoCompleteHRESULT(iPtr, Win32.SHAutoCompleteFlags.SHACF_DEFAULT);
Console.WriteLine("HRESULT handled: " + HRESULT.ToString());
}
}
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Runtime.InteropServices
Module Win32
' The SHAutoComplete function allows you
' to add auto-compete functionality to your
' Windows Forms text boxes. In .NET Framework
' 1.1 and earlier, you can use SHAutoComplete.
' Later versions have this ability built in without
' requiring platform invoke.
' See the MSDN documentation of the
' SHAutoComplete function for the
' complete set of flags.
Public Enum SHAutoCompleteFlags
SHACF_DEFAULT = &H1
SHACF_FILESYSTEM = &H1
End Enum
' Use the DllImportAttribute to import the SHAutoComplete function.
' Set the PreserveSig to false to specify exception errors.
<DllImportAttribute("shlwapi.dll", EntryPoint:="SHAutoComplete", ExactSpelling:=True, PreserveSig:=False)> _
Public Sub SHAutoComplete(ByVal hwndEdit As IntPtr, ByVal dwFlags As SHAutoCompleteFlags)
End Sub
' Use the DllImportAttribute to import the SHAutoComplete function.
' Use the default value of the PreserveSig field to specify HRESULT errors.
<DllImportAttribute("shlwapi.dll", EntryPoint:="SHAutoComplete", ExactSpelling:=True)> _
Public Function SHAutoCompleteHRESULT(ByVal hwndEdit As IntPtr, ByVal dwFlags As SHAutoCompleteFlags) As Integer
End Function
End Module
Module Program
Sub Main()
Run()
End Sub
Sub Run()
' Create a null (nothing in Visual Basic) IntPtr
' to pass to the SHAutoComplete method. Doing so
' creates a failure and demonstrates the two ways
' that the PreserveSig property allows you to handle
' failures.
' Normally, you would pass a handle to a managed
' Windows Forms text box.
Dim iPtr As New IntPtr(0)
' Call the SHAutoComplete function using exceptions.
Try
Console.WriteLine("Calling the SHAutoComplete method with the PreserveSig field set to false.")
Win32.SHAutoComplete(iPtr,Win32.SHAutoCompleteFlags.SHACF_DEFAULT)
Catch e As Exception
Console.WriteLine("Exception handled: " + e.Message)
End Try
Console.WriteLine("Calling the SHAutoComplete method with the PreserveSig field set to true.")
' Call the SHAutoComplete function using HRESULTS.
Dim HRESULT As Integer = Win32.SHAutoCompleteHRESULT(iPtr,Win32.SHAutoCompleteFlags.SHACF_DEFAULT)
Console.WriteLine("HRESULT handled: " + HRESULT.ToString())
End Sub
End Module
Comentários
Defina o PreserveSig campo como true para converter assinaturas não gerenciadas com HRESULT valores diretamente; defina-o como false para converter HRESULT automaticamente valores retornados em exceções. Por padrão, o PreserveSig campo é true.
Quando true, a assinatura do método gerenciado retorna um valor inteiro que contém o HRESULT valor . Nesse caso, você deve inspecionar manualmente o valor retornado e responder adequadamente em seu aplicativo.
Quando você define o PreserveSig campo como false, a assinatura do método gerenciado tem um tipo de retorno nulo ou o tipo do último parâmetro [out, retval] não gerenciado. Quando o método não gerenciado produz um HRESULT, o runtime ignora automaticamente um valor retornado de S_OK (ou 0) e não gera uma exceção. Para HRESULTs diferente de S_OK, o runtime gera automaticamente uma exceção que corresponde ao HRESULT.
Você pode decidir alterar o comportamento de relatório de erros padrão de HRESULTs para exceções nos casos em que as exceções se ajustam melhor à estrutura de relatório de erros do aplicativo.
Esse campo é semelhante ao PreserveSigAttribute; no entanto, ao contrário do PreserveSig campo , o valor padrão para o atributo é false.
Em alguns casos, os desenvolvedores do Visual Basic usam o DllImportAttribute, em vez de usar a Declare instrução , para definir uma função DLL no código gerenciado. Definir o PreserveSig campo é um desses casos.
