DllImportAttribute.PreserveSig Field
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Indicates whether unmanaged methods that have HRESULT return values are directly translated or whether HRESULT return values are automatically converted to exceptions.
public: bool PreserveSig;public bool PreserveSig;val mutable PreserveSig : boolPublic PreserveSig As Boolean Field Value
Examples
The following code example uses the DllImportAttribute to import the unmanaged SHAutoComplete function once with the PreserveSig field set to true and again with the PreserveSig field set to false. This code example causes the SHAutoComplete function to generate any errors with an exception one time and an HRESULT the next.
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
Remarks
Set the PreserveSig field to true to translate unmanaged signatures with HRESULT values directly; set it to false to automatically convert HRESULT return values to exceptions. By default, the PreserveSig field is true.
When true, the managed method signature returns an integer value that contains the HRESULT value. In this case, you must manually inspect the return value and respond accordingly in your application.
When you set the PreserveSig field to false, the managed method signature has a void return type or the type of the last unmanaged [out, retval] parameter. When the unmanaged method produces an HRESULT, the runtime automatically ignores a return value of S_OK (or 0) and does not throw an exception. For HRESULTs other than S_OK, the runtime automatically throws an exception that corresponds to the HRESULT.
You might decide to change the default error reporting behavior from HRESULTs to exceptions in cases where exceptions better fit the error reporting structure of your application.
This field is similar to the PreserveSigAttribute; however, in contrast to the PreserveSig field, the default value for the attribute is false.
In some cases, Visual Basic developers use the DllImportAttribute, instead of using the Declare statement, to define a DLL function in managed code. Setting the PreserveSig field is one of those cases.
