CA1060

值

規則 ID

CA1060

類別

設計

修復是中斷修復還是非中斷修復

重大

原因

方法使用平臺調用服務訪問非托管代碼,不是 NativeMethods 類之一的成員。

規則說明

平臺調用方法(如使用 System.Runtime.InteropServices.DllImportAttribute 屬性標記的方法)或在 Visual Basic 中使用 declare 關鍵字定義的方法可訪問非托管代碼。 這些方法應是處于以下一個類中:

NativeMethods - 此類不會對非托管代碼權限取消堆棧審核。 (System.Security.SuppressUnmanagedCodeSecurityAttribute 不得應用于此類。)此類用于可在任何位置使用的方法,因為會執行堆棧審核。

SafeNativeMethods - 此類會對非托管代碼權限取消堆棧審核。 (System.Security.SuppressUnmanagedCodeSecurityAttribute 應用于此類。)此類用于可供任何人安全調用的方法。 這些方法的調用方不需要執行完整安全評審以確保使用是安全的,因為這些方法對于任何調用方都無害。

UnsafeNativeMethods - 此類會對非托管代碼權限取消堆棧審核。 (System.Security.SuppressUnmanagedCodeSecurityAttribute 應用于此類。)此類用于有潛在危險的方法。 這些方法的任何調用方都必須執行完整安全檢查,以確保使用是安全的,因為不會執行任何堆棧審核。

這些類聲明為 internal(在 Visual Basic 中為 Friend),并聲明一個私有構造函數來阻止創建新實例。 這些類中的方法應是 static 和 internal(在在 Visual Basic 中是 Shared 和 Friend)。

如何解決沖突

若要解決與此規則的沖突,請將方法移動到合適的 NativeMethods 類中。 對于大多數應用程序,將 P/Invoke 移動到名為 NativeMethods 的新類便足夠了。

但是,如果要開發在其他應用程序中使用的庫,應考慮定義兩個名為 SafeNativeMethods 和 UnsafeNativeMethods 的其他類。 這些類與 NativeMethods 類相似;但是,它們使用名為 SuppressUnmanagedCodeSecurityAttribute 的特殊屬性進行標記 。 應用此屬性時,運行時不會執行完整堆棧審核來確保所有調用方都具有 UnmanagedCode 權限。 運行時通常會在啟動時檢查是否具有此權限。 因此可極大地提高對這些非托管方法的調用的性能,還使具備有限權限的代碼可以調用這些方法。

不過,應非常小心地使用此屬性。 如果未正確實現,則可能會產生嚴重的安全隱患。

有關如何實現這些方法的信息,請參閱 NativeMethods 示例、SafeNativeMethods 示例和 UnsafeNativeMethods 示例 。

何時禁止顯示警告

不禁止顯示此規則發出的警告。

示例

下面的示例聲明了違反此規則的方法。 若要更正該沖突,應將 RemoveDirectory P/Invoke 移動到設計為僅保存 P/invoke 的適當類。

' Violates rule: MovePInvokesToNativeMethodsClass.Friend Class UnmanagedApi    Friend declare Function RemoveDirectory Lib "kernel32" (   ByVal Name As String) As BooleanEnd Class// Violates rule: MovePInvokesToNativeMethodsClass.internal class UnmanagedApi{    [DllImport("kernel32.dll", CharSet = CharSet.Unicode)]    internal static extern bool RemoveDirectory(string name);}

NativeMethods 示例

由于 NativeMethods 類不應使用 SuppressUnmanagedCodeSecurityAttribute 進行標記,因此,置于其中的 P/invoke 需要 UnmanagedCode 權限 。 由于大多數應用程序從本地計算機運行并隨完全信任一起運行,因此這通常不會成為問題。 但是,如果要開發可重用的庫,則應考慮定義 SafeNativeMethods 或 UnsafeNativeMethods 類 。

下面的示例演示了一個 Interaction.Beep 方法,它可包裝來自 user32.dll 的 MessageBeep 函數 。 MessageBeep P/Invoke 會置于 NativeMethods 類中 。

Public NotInheritable Class Interaction    Private Sub New()    End Sub    ' Callers require Unmanaged permission            Public Shared Sub Beep()        ' No need to demand a permission as callers of Interaction.Beep                             ' will require UnmanagedCode permission                             If Not NativeMethods.MessageBeep(-1) Then            Throw New Win32Exception()        End If    End SubEnd ClassFriend NotInheritable Class NativeMethods    Private Sub New()    End Sub    <DllImport("user32.dll", CharSet:=CharSet.Auto)>    Friend Shared Function MessageBeep(ByVal uType As Integer) As <MarshalAs(UnmanagedType.Bool)> Boolean    End FunctionEnd Classpublic static class Interaction{    // Callers require Unmanaged permission            public static void Beep()    {        // No need to demand a permission as callers of Interaction.Beep                    // will require UnmanagedCode permission                    if (!NativeMethods.MessageBeep(-1))            throw new Win32Exception();    }}internal static class NativeMethods{    [DllImport("user32.dll", CharSet = CharSet.Auto)]    [return: MarshalAs(UnmanagedType.Bool)]    internal static extern bool MessageBeep(int uType);}

SafeNativeMethods 示例

可以安全地向任何應用程序公開并且沒有任何副作用的 P/Invoke 方法應置于名為 SafeNativeMethods 的類中。 不必要求獲得權限,也不必過多注意從其處調用權限。

下面的示例演示了一個 Environment.TickCount 屬性,它可包裝來自 kernel32.dll 的 GetTickCount 函數 。

Public NotInheritable Class Environment    Private Sub New()    End Sub    ' Callers do not require Unmanaged permission           Public Shared ReadOnly Property TickCount() As Integer        Get            ' No need to demand a permission in place of                           ' UnmanagedCode as GetTickCount is considered                           ' a safe method                           Return SafeNativeMethods.GetTickCount()        End Get    End PropertyEnd Class<SuppressUnmanagedCodeSecurityAttribute()>Friend NotInheritable Class SafeNativeMethods    Private Sub New()    End Sub    <DllImport("kernel32.dll", CharSet:=CharSet.Auto, ExactSpelling:=True)>    Friend Shared Function GetTickCount() As Integer    End FunctionEnd Classpublic static class Environment{    // Callers do not require UnmanagedCode permission           public static int TickCount    {        get        {            // No need to demand a permission in place of                           // UnmanagedCode as GetTickCount is considered                          // a safe method                          return SafeNativeMethods.GetTickCount();        }    }}[SuppressUnmanagedCodeSecurityAttribute]internal static class SafeNativeMethods{    [DllImport("kernel32.dll", CharSet = CharSet.Auto, ExactSpelling = true)]    internal static extern int GetTickCount();}

UnsafeNativeMethods 示例

不能安全調用并且可能導致副作用的 P/Invoke 方法應置于名為 UnsafeNativeMethods 的類中。 應嚴格檢查這些方法,以確保不會無意中向用戶公開它們。 此外,這些方法在使用時,還應具有所需的其他權限,而不是 UnmanagedCode。

下面的示例演示了一個 Cursor.Hide 方法,它可包裝來自 user32.dll 的 ShowCursor 函數 。

Public NotInheritable Class Cursor    Private Sub New()    End Sub    ' Callers do not require Unmanaged permission, however,             ' they do require UIPermission.AllWindows           Public Shared Sub Hide()        ' Need to demand an appropriate permission                           ' in  place of UnmanagedCode permission as                            ' ShowCursor is not considered a safe method                           Dim permission As New UIPermission(UIPermissionWindow.AllWindows)        permission.Demand()        UnsafeNativeMethods.ShowCursor(False)    End SubEnd Class<SuppressUnmanagedCodeSecurityAttribute()>Friend NotInheritable Class UnsafeNativeMethods    Private Sub New()    End Sub    <DllImport("user32.dll", CharSet:=CharSet.Auto, ExactSpelling:=True)>    Friend Shared Function ShowCursor(<MarshalAs(UnmanagedType.Bool)> ByVal bShow As Boolean) As Integer    End FunctionEnd Classpublic static class Cursor{    // Callers do not require UnmanagedCode permission, however,           // they do require UIPermissionWindow.AllWindows.        public static void Hide()    {        // Need to demand an appropriate permission                   // in place of UnmanagedCode permission as                    // ShowCursor is not considered a safe method.               new UIPermission(UIPermissionWindow.AllWindows).Demand();        UnsafeNativeMethods.ShowCursor(false);    }}[SuppressUnmanagedCodeSecurityAttribute]internal static class UnsafeNativeMethods{    [DllImport("user32.dll", CharSet = CharSet.Auto, ExactSpelling = true)]    internal static extern int ShowCursor([MarshalAs(UnmanagedType.Bool)] bool bShow);}

另請參閱

設計規則