DllImportAttribute.PreserveSig DllImportAttribute.PreserveSig DllImportAttribute.PreserveSig DllImportAttribute.PreserveSig Field

Definition

Gibt an, ob nicht verwaltete Methoden, die über HRESULT-Rückgabewerte oder retval-Rückgabewerte verfügen, direkt übersetzt werden oder ob HRESULT-Rückgabewerte oder retval-Rückgabewerte automatisch in Ausnahmen konvertiert werden.Indicates whether unmanaged methods that have HRESULT or retval return values are directly translated or whether HRESULT or retval return values are automatically converted to exceptions.

public: bool PreserveSig;
public bool PreserveSig;
val mutable PreserveSig : bool
Public PreserveSig As Boolean 

Feldwert

Beispiele

Im folgenden Codebeispiel wird verwendet DllImportAttribute , um die nicht verwaltete SHAutoComplete Funktion einmal zu importieren PreserveSig , wobei das true -Feld falseauf fest PreserveSig gelegt ist und das-Feld wieder auf festgelegt ist.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. Dieses Codebeispiel bewirkt, SHAutoComplete dass die-Funktion alle Fehler mit einer-Ausnahme einmalig und HRESULT als nächstes generiert.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

Hinweise

Legen Sie PreserveSig das- true Feld auf fest, um nicht verwaltete HRESULT Signaturen retval direkt mit-oder-Werten zu über HRESULT setzen retval . Legen Sie es auf false fest, um die Werte automatisch zu konvertierenSet the PreserveSig field to true to directly translate unmanaged signatures with HRESULT or retval values; set it to false to automatically convert HRESULT or retval values to exceptions. Standardmäßig ist truedas PreserveSig -Feld.By default, the PreserveSig field is true.

Wenn trueder Wert ist, gibt die resultierende Methoden Signatur einen ganzzahligen Wert zurück, der den HRESULT Wert enthält.When true, the resulting method signature returns an integer value that contains the HRESULT value. In diesem Fall müssen Sie den Rückgabewert manuell überprüfen und in Ihrer Anwendung entsprechend antworten.In this case, you must manually inspect the return value and respond accordingly in your application.

Wenn Sie das PreserveSig -Feld auf falsefestlegen, enthält die resultierende Methoden Signatur einen void-Rückgabetyp anstelleHRESULTeines Integer ()-Rückgabe Typs.When you set the PreserveSig field to false, the resulting method signature contains a void return type instead of an integer (HRESULT) return type. Wenn die nicht verwaltete Methode einen HRESULTerzeugt, ignoriert die Runtime automatisch einen Rückgabewert von (oder 0) und löst keine Ausnahme aus. S_OKWhen the unmanaged method produces an HRESULT, the runtime automatically ignores a return value of S_OK (or 0) and does not throw an exception. Bei HRESULTanderen Ausnahmen als S_OKlöst die Common Language Runtime automatisch eine Ausnahme aus, die HRESULTdem entspricht.For HRESULTs other than S_OK, the runtime automatically throws an exception that corresponds to the HRESULT. Beachten Sie, DllImportAttribute dass das-Attribut diese Konvertierung nur in Methoden durch HRESULTführt, die zurückgeben.Note that the DllImportAttribute attribute only performs this conversion to methods that return an HRESULT.

In Fällen, in denen Ausnahmen besser zur Fehler Berichterstattungs HRESULTStruktur der Anwendung passen, können Sie das Standardverhalten der Fehlerberichterstattung von s in "Ausnahmen" ändern.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.

Dieses Feld ähnelt dem PreserveSigAttribute, aber im Gegensatz PreserveSig zum-Feld ist falseder Standardwert für das-Attribut.This field is similar to the PreserveSigAttribute; however, in contrast to the PreserveSig field, the default value for the attribute is false.

In einigen Fällen verwenden DllImportAttributeVisual Basic Entwickler anstelle Declare der-Anweisung, um eine DLL-Funktion in verwaltetem Code zu definieren.In some cases, Visual Basic developers use the DllImportAttribute, instead of using the Declare statement, to define a DLL function in managed code. Das Festlegen PreserveSig des Felds ist einer dieser Fälle.Setting the PreserveSig field is one of those cases.

Gilt für:

Siehe auch