Move P/Invokes to NativeMethods class

Move P/Invokes to NativeMethods cla...

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Microsoft Visual Studio 2005/.NET Framework 2.0

Visual Studio Team System

Move P/Invokes to NativeMethods class

Updated: November 2007

TypeName	MovePInvokesToNativeMethodsClass
CheckId	CA1060
Category	Microsoft.Design
Breaking Change	Breaking

Cause

A method uses Platform Invocation Services to access unmanaged code and is not a member of one of the NativeMethods classes.

Rule Description

Platform Invocation methods, such as those marked with the System.Runtime.InteropServices..::.DllImportAttribute attribute, or methods defined by using the Declare keyword in Visual Basic, access unmanaged code. These methods should be in one of the following classes:

NativeMethods - This class does not suppress stack walks for unmanaged code permission. (System.Security..::.SuppressUnmanagedCodeSecurityAttribute must not be applied to this class.) This class is for methods that can be used anywhere because a stack walk will be performed.
SafeNativeMethods - This class suppresses stack walks for unmanaged code permission. (System.Security..::.SuppressUnmanagedCodeSecurityAttribute is applied to this class.) This class is for methods that are safe for anyone to call. Callers of these methods are not required to do a full security review to ensure that the usage is secure because the methods are harmless for any caller.
UnsafeNativeMethods - This class suppresses stack walks for unmanaged code permission. (System.Security..::.SuppressUnmanagedCodeSecurityAttribute is applied to this class.) This class is for methods that are potentially dangerous. Any caller of these methods must do a full security review to ensure that the usage is secure because no stack walk will be performed.

These classes are declared as internal (Friend, in Visual Basic), and declare a private constructor to prevent new instances from being created. The methods in these classes should be static and internal (Shared and Friend in Visual Basic).

How to Fix Violations

To fix a violation of this rule, move the method to the appropriate NativeMethods class. For most applications, moving P/Invokes to a new class that is named NativeMethods is enough.

However, if you are developing libraries for use in other applications, you should consider defining two other classes called SafeNativeMethods and UnsafeNativeMethods. These classes resemble the NativeMethods class, however, they are marked with a special attribute called SuppressUnmanagedCodeSecurityAttribute. When this attribute is applied, the runtime does not perform a full stack walk to make sure that all callers have the UnmanagedCode permission. The runtime ordinarily checks for this permission at startup. Because the check is not performed, it can greatly improve performance for calls to these unmanaged methods, and it also allows code with limited permissions to call these methods.

However, you should use this attribute with great care, because, implemented incorrectly, it can have serious security implications.

For information about how to implement the methods, see the NativeMethods Example, SafeNativeMethods Example, and UnsafeNativeMethods Example.

When to Suppress Warnings

Do not suppress a warning from this rule.

Example

The following example declares a method that violates this rule. To correct the violation, the RemoveDirectory P/Invoke should be moved to an appropriate class that is designed to only hold P/Invokes.

Visual Basic

Imports System

NameSpace MSInternalLibrary

' Violates rule: MovePInvokesToNativeMethodsClass.
Friend Class UnmanagedApi
    Friend Declare Function RemoveDirectory Lib "kernel32" ( _
       ByVal Name As String) As Boolean
End Class

End NameSpace

using System;
using System.Runtime.InteropServices;

namespace DesignLibrary
{
// Violates rule: MovePInvokesToNativeMethodsClass.
    internal class UnmanagedApi
    {
        [DllImport("kernel32.dll", CharSet = CharSet.Unicode)]
        internal static extern bool RemoveDirectory(string name);
    }
}

NativeMethods Example

Description

Because the NativeMethods class should not be marked with SuppressUnmanagedCodeSecurityAttribute, P/Invokes placed within in it will require UnmanagedCode permission. Because most applications run from the local computer and run with full trust, this is usually not a problem. However, if you are developing reusable libraries, you should consider defining a SafeNativeMethods or UnsafeNativeMethods class.

The following example shows a Interaction.Beep method that wraps the MessageBeep function from user32.dll. The MessageBeep P/Invoke is placed within the NativeMethods class.

Code

Visual Basic

Imports System    
Imports System.Runtime.InteropServices    
Imports System.ComponentModel         

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 Sub  

End Class         

Friend 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 Function  

End Class

using System;    
using System.Runtime.InteropServices;    
using System.ComponentModel;              

public 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 Example

Description

P/Invoke methods that are safe to be exposed to any application and that do not have any side effects should be placed in a class that is named SafeNativeMethods. You do not have to demand permissions and you do not have to pay too much attention to where they are called from.

The following example shows a Environment.TickCount property that wraps the GetTickCount function from kernel32.dll.

Code

Visual Basic

Imports System   
Imports System.Runtime.InteropServices   
Imports System.Security       

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 Property       

End 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 Function       

End Class

using System;   
using System.Runtime.InteropServices;   
using System.Security;  

public 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 Example

Description

P/Invoke methods that are not safe for someone to call and that might cause side effects should be placed in a class that is named UnsafeNativeMethods. These methods should be rigorously checked to make sure that they are not being exposed to the user unintentionally. The rule Review SuppressUnmanagedCodeSecurityAttribute usage can help with this. Alternatively, the methods should have another permission demanded in place of UnmanagedCode when they use them.

The following example shows a Cursor.Hide method that wraps the ShowCursor function from user32.dll.

Code

Visual Basic

Imports System   
Imports System.Runtime.InteropServices   
Imports System.Security   
Imports System.Security.Permissions       

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 Sub       

End 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 Function       

End Class

using System;   
using System.Runtime.InteropServices;   
using System.Security;   
using System.Security.Permissions;           

public 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);   
}

Other Resources

Design Warnings

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

Description

Code

Description

Code

Description

Code

Other Resources