Mtf.Permissions 3.0.9

dotnet add package Mtf.Permissions --version 3.0.9                
NuGet\Install-Package Mtf.Permissions -Version 3.0.9                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Mtf.Permissions" Version="3.0.9" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Mtf.Permissions --version 3.0.9                
#r "nuget: Mtf.Permissions, 3.0.9"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Mtf.Permissions as a Cake Addin
#addin nuget:?package=Mtf.Permissions&version=3.0.9

// Install Mtf.Permissions as a Cake Tool
#tool nuget:?package=Mtf.Permissions&version=3.0.9                

Mtf.Permissions Library Documentation

Overview

The Mtf.Permissions library simplifies permission management in .NET applications by providing tools to define, enforce, and apply permissions to UI controls and methods. It ensures secure access control based on user roles and permissions.


Installation

  1. Add the Package:
    Install the library using the following command:

    dotnet add package Mtf.Permissions
    
  2. Include the Namespace:
    Add the necessary namespace:

    using Mtf.Permissions;
    

Core Components

1. Class: PermissionManager

The PermissionManager class provides methods to manage permissions dynamically and validate user access to specific methods or UI components.

Properties
Property Type Description
currentUser User Represents the currently logged-in user.
Methods
Method Description
SetUser(Form form, User currentUser) Assigns the current user and applies permissions to the specified form and its controls.
ApplyPermissionsOnControls(Form form) Iterates through all controls in the form to enable or disable them based on the user's permissions.
EnsurePermissions() Verifies if the current user has the required permissions for the calling method, throwing an exception if not.
SetEnabledProperty(Form form, Control control) Dynamically enables or disables controls based on permissions tied to the Tag property.
Example Usage
var permissionManager = new PermissionManager();
permissionManager.SetUser(mainForm, currentUser);
permissionManager.ApplyPermissionsOnControls(mainForm);

2. Attribute: RequirePermissionAttribute

Annotates methods that require specific permissions.

The RequirePermission attribute can be instantiated with one of the following enum values: ApplicationManagementPermissions, CameraManagementPermissions, DisplayManagementPermissions, EventManagementPermissions, GeneralPermissions, GridManagementPermissions, GroupManagementPermissions, IODeviceManagementPermissions, LanguageManagementPermissions, LogManagementPermissions, MapManagementPermissions, PermissionManagementPermissions, SequenceManagementPermissions, SerialDeviceManagementPermissions, ServerManagementPermissions, SettingsManagementPermissions, TemplateManagementPermissions, UserManagementPermissions, WindowManagementPermissions

Properties
Property Type Description
PermissionValue long Defines the value of permission required to access the method.
PermissionGroup Type Defines the type of permission required to access the method.
Example Usage
[RequirePermission(ApplicationManagementPermissions.Exit)]
private void ExitApplication()
{
    Environment.Exit(0);
}

3. Class: User

Represents a system user and their associated permissions.

Properties
Property Type Description
Username string The username of the user.
IndividualPermissions List<Permission> List of permissions directly assigned to the user.
Groups List<Group> Groups the user belongs to, inheriting their permissions.

4. Class: Permission

Defines a specific permission that can be assigned to users or groups.

Properties
Property Type Description
PermissionType PermissionType The specific type of permission.

5. Enum: PermissionType

An enumeration defining various permission types for your application. Extend this enum to add custom permission types.


Example Application

Scenario

A Windows Forms application with three user roles: Guest, Member, and Admin, each having varying levels of access to UI controls and functionality.

Code Example: MainForm
public partial class MainForm : Form
{
    private PermissionManager permissionManager;
    private User currentUser;

    public MainForm()
    {
        InitializeComponent();
        permissionManager = new PermissionManager();

        // Define users and their permissions
        var guest = new User() { Username = "Guest", IndividualPermissions = [] };
        var member = new User() { Username = "Group member", Groups = [new Group { Permissions = [new Permission { PermissionGroup = typeof(GeneralPermissions), PermissionValue = (long)GeneralPermissions.View}] }] };
        var admin = new User()
        {
            Username = "Admin",
            IndividualPermissions =
            [
                new Permission { PermissionGroup = typeof(GeneralPermissions), PermissionValue = (long)GeneralPermissions.View },
                new Permission { PermissionGroup = typeof(GeneralPermissions), PermissionValue = (long)GeneralPermissions.Edit }
            ]
        };
		
        // Assign current user
        currentUser = admin;

        // Assign permissions to controls via the Tag property
        editButton.Tag = nameof(EditAction);
        viewButton.Tag = nameof(ViewAction);

        // Apply permissions
        permissionManager.SetUser(this, currentUser);
    }

    [RequirePermission(GeneralPermissions.Edit)]
    private void EditAction()
    {
        permissionManager.EnsurePermissions();
        MessageBox.Show("Edit action executed.");
    }

    [RequirePermission(GeneralPermissions.View)]
    private void ViewAction()
    {
        permissionManager.EnsurePermissions();
        MessageBox.Show("View action executed.");
    }
}

Dynamic Permissions for UI Components

  1. Controls (Control.Tag)
    Assign method names to the Tag property of controls. These methods must be decorated with [RequirePermission].

  2. Menu Items
    Use ToolStripItem.Tag for menu items. The library dynamically enables or disables them based on the user's permissions.

  3. Example: Dynamic ToolStrip Menu

fileMenuItem.Tag = nameof(OpenFile);
settingsMenuItem.Tag = nameof(ConfigureSettings);

[RequirePermission(PermissionType.View)]
private void OpenFile() { /* Logic */ }

[RequirePermission(PermissionType.Admin)]
private void ConfigureSettings() { /* Logic */ }

Error Handling

  • Permission Validation:
    Use EnsurePermissions() to validate user permissions for critical operations. If the user lacks the necessary permissions, an UnauthorizedAccessException is thrown.

    permissionManager.EnsurePermissions();
    
  • Null Checks:
    Ensure all methods handle null inputs gracefully (e.g., ArgumentNullException).


Best Practices

  1. Use RequirePermissionAttribute:
    Clearly define required permissions for all restricted methods.

  2. Leverage Groups:
    Organize permissions hierarchically using groups for better scalability.

  3. Control Tags:
    Ensure all UI controls have meaningful Tag values pointing to their associated methods.

  4. Caching:
    Cache user permissions for large applications to optimize performance.

Product Compatible and additional computed target framework versions.
.NET net8.0-windows7.0 is compatible.  net9.0-windows7.0 is compatible. 
.NET Framework net481 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETFramework 4.8.1

    • No dependencies.
  • net8.0-windows7.0

    • No dependencies.
  • net9.0-windows7.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.0.9 6 11/27/2024
3.0.8 6 11/27/2024
3.0.7 28 11/27/2024
3.0.6 57 11/26/2024
2.0.5 61 11/26/2024
2.0.4 51 11/26/2024
1.0.3 53 11/26/2024
1.0.2 63 11/26/2024
1.0.1 73 11/21/2024
1.0.0 53 11/21/2024