ModuleEventRaiser.Generator 1.1.7.10

ModuleEventRaiser.Generator

A lightweight VB.NET source generator that automatically creates RaiseEvent helper methods for events declared in Modules. Enterprise-ready and fully compatible with Option Infer Off - making it perfect for healthcare, financial, and other regulated industries with strict coding standards.

v1.1.7.10 Latest Update: Fixed ArgumentOutOfRangeException.ThrowIfNegative compatibility for legacy .NET versions. If you are using .NET 8+, feel free to stay on 1.1.7.9.

New in version 1.1.7+:

• Priority-based event scheduling - control the order events are raised with priority values
• Enhanced asynchronous methods - add optional delays to async event raising
• Improved parameter documentation - better XML documentation for generated methods
• Comprehensive event scheduling system with thread-safe queue management, perfect for game frameworks (MonoGame, FNA, etc.)
• Delegate pattern detection - supports both traditional parameter lists and delegate-based events like As EventHandler
• Multiple event module support - resolves ambiguity in method calls and supports multiple event modules like GameEvents, UIEvents, AudioEvents and more

📦 Version Notes: 1.1.7.9 → 1.1.7.10

This is a compatibility fix for legacy .NET versions. If you are using .NET 8+, you can stay on 1.1.7.9.

The subroutine ArgumentOutOfRangeException.ThrowIfNegative requires .NET SDK 8.0 or later. For legacy .NET support, this API call has been replaced with a traditional if-check:

If withDelaySec < 0 Then Throw New ArgumentOutOfRangeException("withDelaySec", "Delay seconds must be non-negative.")

Note: If you want to use the multi-namespace feature, please upgrade to 1.1.7.9 or later. Version 1.1.7.5 does NOT support multiple namespaces as planned.

📦 Version Notes: 1.1.5 → 1.1.7.9

🎉 Ultimate Enterprise-Ready Release!

Version 1.1.7.9 represents the pinnacle of ModuleEventRaiser.Generator's evolution, delivering ultimate enterprise-grade compatibility with explicit typing for Option Infer Off projects, plus comprehensive namespace support.

🔥 Key Enterprise Features in 1.1.7.9

1. Option Infer Off Compatibility (Enterprise Critical)

• Explicit typing: All generated code uses explicit type declarations
• Healthcare/Financial ready: Perfect for regulated industries with strict coding standards
• Zero type inference: No reliance on Option Infer On - works in all VB.NET environments
• Enterprise compliance: Meets corporate coding standards requiring explicit typing

2. Multi-Namespace Support (Ultimate Feature)

• Namespace isolation: Define event modules in different namespaces without conflicts
• Proper imports: Automatic namespace handling for generated code
• Enterprise-ready: Perfect for large projects with organized namespace structure
• Flexible architecture: Support for complex project hierarchies

3. Priority-Based Event Scheduling

• Control event order: Assign priority values to scheduled events
• Higher priority first: Events with larger priority values are raised before lower ones
• Flexible syntax: ScheduleEvent_xxx(...parameters, Optional withPriority As Integer = 0)

4. Enhanced Asynchronous Methods

• Optional delay support: Add withDelaySec parameter to async methods
• Validation: Automatic validation to ensure non-negative delay values
• Improved syntax: RaiseEventAsync_xxx(...parameters, Optional withDelaySec As Double = 0)

5. Enterprise-Grade Code Quality

• Better XML docs: Enhanced parameter descriptions and method documentation
• Clearer usage guidelines: Improved comments for game framework compatibility
• Self-documenting code: More descriptive generated code with explicit typing

🛠️ Technical Evolution

🎯 Who Should Upgrade to 1.1.7.9?

🚀 Must Upgrade (Enterprise Critical)

• Healthcare/Financial projects: Require Option Infer Off compliance
• Regulated industries: Need explicit typing for coding standards
• Enterprise developers: Working with corporate coding standards
• Large project teams: Need namespace isolation and type safety
• Library authors: Want the most robust and enterprise-compatible version

✅ Recommended Upgrade

• Game developers: Priority-based scheduling helps manage event order
• Async users: Delay support adds flexibility to async event handling
• Documentation lovers: Improved XML docs for better IntelliSense
• Future-proofing: Planning for project growth and enterprise requirements

🤝 Can Stay on Previous Versions

• Simple projects: Single module, single namespace usage with Option Infer On
• Stability-focused: Current version works perfectly for your non-enterprise needs

📊 Version Comparison Matrix

Features

• Automatically generate RaiseEvent_xxx methods for Module events
• Supports any event parameter types (Double, String, custom classes, etc.)
• Zero runtime dependencies
• Compile-time only code generation
• Clean and easy to use
• Automatically adds required Imports for recognized types
• RaiseEventAsync_xxx methods for asynchronous event raising (available in version 1.0.9+)
• New in 1.1.2: ScheduleEvent_xxx methods for deferred event raising
• New in 1.1.2: Thread-safe event scheduler with queue management, perfect for game frameworks (MonoGame, FNA, etc.)
• New in 1.1.3: Delegate pattern detection that supports both traditional parameter lists and delegate-based events like As EventHandler
• New in 1.1.6: Multiple event module support - fully qualified method calls for no ambiguity
• New in 1.1.7: Priority-based event scheduling - control event order with priority values
• New in 1.1.7: Enhanced asynchronous methods - optional delay support with validation
• New in 1.1.7.9: Multi-namespace support - ultimate feature completeness for enterprise projects (NOT in 1.1.7.5)
• New in 1.1.7.9: Option Infer Off compatibility - explicit typing for healthcare, financial, and regulated industries

Usage Example

Basic Single Namespace Usage

Define your events in a partial module (like MyEvents.vb), which will be located in your project's root namespace:

Partial Public Module MyEvents
    Public Event TemperatureChanged(temperature As Double)
    Public Event HumidityChanged(humidity As Double)
    Public Event LightLevelChanged(lightLevel As Integer)
End Module

Multi-Namespace Support (NEW in 1.1.7.9)

Important Note: Version 1.1.7.5 does NOT support multiple namespaces as planned.

Define event modules in different namespaces for better organization. Note that the namespace declarations are natually on top of the project's root namespace:

GameEvents.vb (in {RootNamespace}.Events namespace):

Namespace Events
    Partial Public Module GameEvents
        Public Event PlayerDied(playerId As Integer)
        Public Event ScoreUpdated(newScore As Integer)
        Public Event LevelCompleted(levelId As Integer)
    End Module
End Namespace

UIEvents.vb (in {RootNamespace}.UI.Events namespace):

Namespace UI.Events
    Partial Public Module UIEvents
        Public Event ButtonClicked(buttonName As String)
        Public Event MenuOpened(menuId As Integer)
        Public Event DialogClosed(dialogId As Integer)
    End Module
End Namespace

AudioEvents.vb (in {RootNamespace}.Audio.Events namespace):

Namespace Audio.Events
    Partial Public Module AudioEvents
        Public Event SoundPlayed(soundId As Integer)
        Public Event MusicChanged(trackId As Integer)
        Public Event VolumeChanged(newVolume As Double)
    End Module
End Namespace

Namespace isolation and proper code generation are ensured for each namespace.

Output: Generated Event Raiser Methods

Option Explicit On
Option Strict On

Partial Public Module MyEvents
    Public Sub RaiseEvent_TemperatureChanged(temperature As Double)
        RaiseEvent TemperatureChanged(temperature)
    End Sub

    Public Sub RaiseEvent_HumidityChanged(humidity As Double)
        RaiseEvent HumidityChanged(humidity)
    End Sub

    Public Sub RaiseEvent_LightLevelChanged(lightLevel As Integer)
        RaiseEvent LightLevelChanged(lightLevel)
    End Sub

    ' --- Asynchronous event raising methods (available in version 1.0.9+) ---
    Public Async Function RaiseEventAsync_TemperatureChanged(temperature As Double, Optional withDelaySec As Double = 0) As Task
        If withDelaySec < 0 Then Throw New ArgumentOutOfRangeException("withDelaySec", "Delay seconds must be non-negative.")
        If withDelaySec > 0 Then Await Task.Delay(TimeSpan.FromSeconds(withDelaySec))
        Await Task.Run(Sub() RaiseEvent TemperatureChanged(temperature))
    End Function

    Public Async Function RaiseEventAsync_HumidityChanged(humidity As Double, Optional withDelaySec As Double = 0) As Task
        If withDelaySec < 0 Then Throw New ArgumentOutOfRangeException("withDelaySec", "Delay seconds must be non-negative.")
        If withDelaySec > 0 Then Await Task.Delay(TimeSpan.FromSeconds(withDelaySec))
        Await Task.Run(Sub() RaiseEvent HumidityChanged(humidity))
    End Function

    Public Async Function RaiseEventAsync_LightLevelChanged(lightLevel As Integer, Optional withDelaySec As Double = 0) As Task
        If withDelaySec < 0 Then Throw New ArgumentOutOfRangeException("withDelaySec", "Delay seconds must be non-negative.")
        If withDelaySec > 0 Then Await Task.Delay(TimeSpan.FromSeconds(withDelaySec))
        Await Task.Run(Sub() RaiseEvent LightLevelChanged(lightLevel))
    End Function

    ' --- Event scheduling methods (NEW in version 1.1.2) ---
    Public Sub ScheduleEvent_TemperatureChanged(temperature As Double, Optional withPriority As Integer = 0)
        MyEventsEventScheduler.ScheduleEventAction(Sub() RaiseEvent TemperatureChanged(temperature), withPriority)
    End Sub

    Public Sub ScheduleEvent_HumidityChanged(humidity As Double, Optional withPriority As Integer = 0)
        MyEventsEventScheduler.ScheduleEventAction(Sub() RaiseEvent HumidityChanged(humidity), withPriority)
    End Sub

    Public Sub ScheduleEvent_LightLevelChanged(lightLevel As Integer, Optional withPriority As Integer = 0)
        MyEventsEventScheduler.ScheduleEventAction(Sub() RaiseEvent LightLevelChanged(lightLevel), withPriority)
    End Sub
End Module

' --- Event scheduler module (NEW in version 1.1.2, Updated in 1.1.7) ---
''' <summary>
''' Schedules event actions from the MyEvents module to be raised later. 
''' Useful for game frameworks (MonoGame, FNA, etc.) where you want to avoid raising events 
''' during the update phase.
''' </summary>
Public Module MyEventsEventScheduler
    Private ReadOnly _pendingEvents As New Queue(Of ([event] As Action, priority As Integer))
    Private ReadOnly _lock As New Object

    ''' <summary>
    ''' Schedules an event action to be raised later.
    ''' </summary>
    ''' <param name="eventAction">The event action to schedule.</param>
    ''' <param name="priorityValue">The priority value of the event (default is 0).
    ''' Events with higher priority values are raised first.</param>
    Public Sub ScheduleEventAction(eventAction As Action, Optional priorityValue As Integer = 0)
        ArgumentNullException.ThrowIfNull(eventAction)  ' Fixed in 1.1.7.4
        SyncLock _lock
            _pendingEvents.Enqueue((eventAction, priorityValue))
        End SyncLock
    End Sub

    ''' <summary>
    ''' Raises all scheduled event actions defined in this module.
    ''' </summary>
    ''' <remarks>
    ''' All scheduled events are raised in priority order (higher priority first),
    ''' and FIFO order within the same priority level.
    ''' </remarks>
    Public Sub RaiseScheduledEvents()
        ' Key fix in 1.1.7.9: Add explicit typing in case of `Option Infer Off`
        Dim actionsToRaise As Action() = Array.Empty(Of Action)()
        SyncLock _lock
            If _pendingEvents.Count = 0 Then Exit Sub
            actionsToRaise = Aggregate e In _pendingEvents Order By e.priority Descending
                                 Select e.event Into ToArray()
            _pendingEvents.Clear()
        End SyncLock

        ' Raise all events outside the lock to avoid deadlocks
        Array.ForEach(actionsToRaise, Sub(atn) atn.Invoke())
    End Sub

    ''' <summary>
    ''' Gets the number of pending events scheduled to be raised.
    ''' </summary>
    Public ReadOnly Property PendingEventCount As Integer
        Get
            SyncLock _lock
                Return _pendingEvents.Count
            End SyncLock
        End Get
    End Property

    ''' <summary>
    ''' Clears all scheduled events without raising them.
    ''' </summary>
    Public Sub ClearScheduledEvents()
        SyncLock _lock
            _pendingEvents.Clear()
        End SyncLock
    End Sub
End Module

Event Scheduling Usage (New in 1.1.2, Enhanced in 1.1.7)

The event scheduling system is queue-based, particularly useful for game frameworks where you need to avoid raising events during critical phases like the update loop. Version 1.1.7 adds priority-based scheduling for more control over event order.

Basic Scheduling Usage

' Schedule an event to be raised later (default priority = 0)
MyEvents.ScheduleEvent_TemperatureChanged(25.5)

' Raise all scheduled events at an appropriate time (e.g., during Draw phase)
MyEventsEventScheduler.RaiseScheduledEvents()

Priority-Based Scheduling (NEW in 1.1.7)

' Schedule events with different priorities
MyEvents.ScheduleEvent_PlayerDied(playerId, withPriority:=10) ' High priority
MyEvents.ScheduleEvent_ScoreUpdated(newScore, withPriority:=5)   ' Medium priority
MyEvents.ScheduleEvent_ParticleEffect(x, y, withPriority:=1)     ' Low priority

' Raising events will process them in priority order:
' 1. PlayerDied (priority 10)
' 2. ScoreUpdated (priority 5)
' 3. ParticleEffect (priority 1)
MyEventsEventScheduler.RaiseScheduledEvents()

Game Framework Example (MonoGame/FNA)

Public Class Game1
    Inherits Game
    
    Protected Overrides Sub Update(gameTime As GameTime)
        ' During update phase, schedule events instead of raising them immediately
        If playerHealth <= 0 Then
            ' Critical event - high priority
            MyEvents.ScheduleEvent_PlayerDied(playerId, withPriority:=100)
        ElseIf scoreChanged Then
            ' Important but not critical
            MyEvents.ScheduleEvent_ScoreUpdated(newScore, withPriority:=50)
        ElseIf enemyKilled Then
            ' Regular gameplay event
            MyEvents.ScheduleEvent_EnemyKilled(enemyId, withPriority:=10)
        End If
        
        MyBase.Update(gameTime)
    End Sub
    
    Protected Overrides Sub Draw(gameTime As GameTime)
        ' During draw phase, safely raise all scheduled events
        ' Events will be processed in priority order
        MyEventsEventScheduler.RaiseScheduledEvents()
        
        MyBase.Draw(gameTime)
    End Sub
End Class

Enhanced Async Methods (NEW in 1.1.7)

' Async event with delay
Await MyEvents.RaiseEventAsync_TemperatureChanged(25.5, withDelaySec:=2.0)

' Async event without delay (backward compatible)
Await MyEvents.RaiseEventAsync_HumidityChanged(65.0)

Advanced Scheduler Features

' Check how many events are pending
Dim pendingCount = MyEventsEventScheduler.PendingEventCount

' Clear all scheduled events without raising them (useful for scene transitions)
MyEventsEventScheduler.ClearScheduledEvents()

Installation

Install via NuGet Package Manager:

Install-Package ModuleEventRaiser.Generator

Or via .NET CLI:

dotnet add package ModuleEventRaiser.Generator

License

BSD 3-Clause License