DllImportAttribute.PreserveSig Feld

Definition

Namespace:

System.Runtime.InteropServices

Assembly:

System.Runtime.InteropServices.dll

Quelle:

DllImportAttribute.cs

Gibt an, ob nicht verwaltete Methoden, die Rückgabewerte aufweisen HRESULT , direkt übersetzt werden oder ob HRESULT Rückgabewerte automatisch in Ausnahmen konvertiert werden.

public: bool PreserveSig;

public bool PreserveSig;

val mutable PreserveSig : bool

Public PreserveSig As Boolean 

Feldwert

Boolean

Beispiele

Im folgenden Codebeispiel wird verwendet, DllImportAttribute um die nicht verwaltete SHAutoComplete Funktion einmal zu importieren, wobei das PreserveSig Feld auf true und erneut das PreserveSig Feld auf falsefestgelegt ist. Dieses Codebeispiel bewirkt, dass die SHAutoComplete Funktion alle Fehler generiert, die einmal und einmal eine HRESULT Ausnahme aufweisen.

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

Hinweise

Legen Sie das PreserveSig Feld auf fest true , um nicht verwaltete Signaturen direkt mit HRESULT Werten zu übersetzen. Legen Sie es auf false fest, um Rückgabewerte automatisch in Ausnahmen zu konvertieren HRESULT . Standardmäßig ist truedas PreserveSig Feld .

Bei truegibt die Signatur der verwalteten Methode einen ganzzahligen Wert zurück, der den HRESULT Wert enthält. In diesem Fall müssen Sie den Rückgabewert manuell überprüfen und in Ihrer Anwendung entsprechend reagieren.

Wenn Sie das PreserveSig Feld auf falsefestlegen, weist die Signatur der verwalteten Methode einen void-Rückgabetyp oder den Typ des letzten nicht verwalteten [out, retval]-Parameters auf. Wenn die nicht verwaltete Methode einen HRESULTerzeugt, ignoriert die Laufzeit automatisch den Rückgabewert S_OK (oder 0) und löst keine Ausnahme aus. Für HRESULTandere als S_OKlöst die Laufzeit automatisch eine Ausnahme aus, die dem HRESULTentspricht.

In Fällen, in denen Ausnahmen besser zur Fehlerberichterstattungsstruktur Ihrer Anwendung passen, können Sie das Standardverhalten der Fehlerberichterstattung von HRESULTs in Ausnahmen ändern.

Dieses Feld ähnelt dem PreserveSigAttribute. Im Gegensatz zum PreserveSig Feld ist falseder Standardwert für das Attribut jedoch .

In einigen Fällen verwenden Visual Basic-Entwickler anstelle DllImportAttributeder Declare -Anweisung, um eine DLL-Funktion in verwaltetem Code zu definieren. Das Festlegen des PreserveSig Felds ist einer dieser Fälle.

Weitere Informationen

• PreserveSigAttribute