DllImportAttribute.PreserveSig 欄位

定義

命名空間:

System.Runtime.InteropServices

組件:

System.Runtime.InteropServices.dll

來源:

DllImportAttribute.cs

指出是否直接轉譯具有 HRESULT 傳回值的 Unmanaged 方法，還是 HRESULT 會自動將傳回值轉換成例外狀況。

public: bool PreserveSig;

public bool PreserveSig;

val mutable PreserveSig : bool

Public PreserveSig As Boolean 

欄位值

Boolean

範例

下列程式代碼範例會使用 匯入 Unmanaged SHAutoComplete 函式一次，PreserveSig並將欄位設定true為 ，然後再PreserveSig將 字段設定為 false。DllImportAttribute 此程式代碼範例會導致 SHAutoComplete 函式產生任何錯誤，一次和下一 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

備註

將 PreserveSig 欄位設定為 ， true 以直接轉譯具有值的 Unmanaged 簽章 HRESULT ;將它設定為 false ，以自動將傳回值轉換為 HRESULT 例外狀況。 根據預設， PreserveSig 欄位為 true。

當 為 時 true，Managed 方法簽章會傳回包含 HRESULT 值的整數值。 在此情況下，您必須手動檢查傳回值，並在應用程式中據以回應。

當您將 PreserveSig 欄位設定為 false時，Managed 方法簽章具有 void 傳回型別或最後一個 Unmanaged [out， retval] 參數的類型。 當 Unmanaged 方法產生 HRESULT時，運行時間會自動忽略傳回值 S_OK (或 0) ，而且不會擲回例外狀況。 針對 HRESULT以外的 S_OK，運行時間會自動擲回對應至 的 HRESULT例外狀況。

在例外狀況更符合應用程式的錯誤報告結構的情況下，您可能會決定將預設錯誤報告行為從 HRESULT變更為例外狀況。

此欄位類似於 PreserveSigAttribute;不過， PreserveSig 相較於欄位，屬性的預設值為 false。

在某些情況下，Visual Basic 開發人員會使用 DllImportAttribute，而不是使用 Declare 語句，在 Managed 程式代碼中定義 DLL 函式。 PreserveSig設定欄位是其中一種情況。

另請參閱

• PreserveSigAttribute