diff --git a/docs/visual-basic/misc/bc42328.md b/docs/visual-basic/misc/bc42328.md
index 89ba3c35ddf91..d5d3e0072b052 100644
--- a/docs/visual-basic/misc/bc42328.md
+++ b/docs/visual-basic/misc/bc42328.md
@@ -24,28 +24,15 @@ Visual Basic allows you to assign methods to delegates even when their signature
## When this warning occurs
-This warning appears when Visual Basic can handle the assignment through relaxed conversion, making the explicit `AddressOf` unnecessary. For example:
+This warning appears when Visual Basic can handle the assignment through relaxed conversion, making the explicit `AddressOf` unnecessary.
-```vb
-' Event delegate expects (sender As Object, e As EventArgs)
-Public Event SomeEvent As EventHandler
+### Complete example showing the warning
-' Method with exact signature - no warning
-Sub Handler1(sender As Object, e As EventArgs)
- ' Implementation
-End Sub
+The following example shows one scenario that produces BC42328:
-' Method with omitted parameters - causes BC42328
-Sub Handler2()
- ' Implementation
-End Sub
+:::code language="vb" source="snippets/bc42328/AddressOfExample.vb" id="DocumentProcessor":::
-' Using AddHandler with exact match - no warning
-AddHandler SomeEvent, AddressOf Handler1
-
-' Using AddHandler with relaxed conversion - causes BC42328
-AddHandler SomeEvent, AddressOf Handler2
-```
+When you compile this code, Visual Basic shows the BC42328 warning for the `AddHandler` statements that use relaxed delegate conversion.
## Why AddressOf appears to have "no effect"
@@ -57,36 +44,72 @@ However, `AddressOf` is still syntactically required in `AddHandler` and `Remove
## To correct this error
-You have several options depending on your needs:
+You have several options depending on your needs. Using the `DocumentProcessor` example from previously, here are the different ways to resolve the BC42328 warning:
-- **Assign to a variable first (preserves exact semantics):**
+### Option 1: Assign to a variable first (preserves exact semantics)
- ```vb
- Dim handler As EventHandler = AddressOf Handler2
- AddHandler SomeEvent, handler
- ```
+```vb
+Public Sub DemonstrateHandler()
+ ' Create delegate variable first - this eliminates the warning
+ Dim handler As EventHandler = AddressOf OnDocumentProcessed_Simple
+ AddHandler DocumentProcessed, handler
+End Sub
+```
-- **Match the delegate signature exactly:**
+### Option 2: Match the delegate signature exactly
- ```vb
- Sub Handler2(sender As Object, e As EventArgs)
- ' Implementation - use parameters or ignore them
- End Sub
- ```
+```vb
+' Change the method signature to match EventHandler exactly
+Private Sub OnDocumentProcessed_Simple(sender As Object, e As EventArgs)
+ ' You can ignore the parameters if you don't need them
+ Console.WriteLine("Document processed (simple)")
+End Sub
-- **Use a lambda expression:**
+Public Sub DemonstrateHandler()
+ ' Now this works without warning
+ AddHandler DocumentProcessed, AddressOf OnDocumentProcessed_Simple
+End Sub
+```
- ```vb
- AddHandler SomeEvent, Sub() Handler2()
- ```
+### Option 3: Use a lambda expression
-- **Use the `Handles` clause if appropriate:**
+```vb
+Public Sub DemonstrateHandler()
+ ' Wrap the method call in a lambda that matches the signature
+ AddHandler DocumentProcessed, Sub(sender, e) OnDocumentProcessed_Simple()
+
+ ' Or create a more complex lambda inline
+ AddHandler DocumentProcessed,
+ Sub(sender, e)
+ Console.WriteLine($"Event from {sender}")
+ OnDocumentProcessed_Simple()
+ End Sub
+End Sub
+```
+
+### Option 4: Use the `Handles` clause (if appropriate)
- ```vb
- Sub Handler2() Handles someObject.SomeEvent
- ' Implementation
- End Sub
- ```
+```vb
+Public Class DocumentHandler
+ ' Declare the event source with WithEvents
+ Private WithEvents processor As DocumentProcessor
+
+ ' Use Handles clause - no AddHandler needed
+ Private Sub OnDocumentComplete() Handles processor.DocumentProcessed
+ Console.WriteLine("Document processing is done!")
+ End Sub
+End Class
+```
+
+### Option 5: Direct assignment to delegate variable
+
+```vb
+Public Sub DemonstrateHandler()
+ ' Assign to delegate variable then use with AddHandler
+ Dim handler As EventHandler = AddressOf OnDocumentProcessed_Simple
+ AddHandler DocumentProcessed, handler
+End Sub
+```
## When you can ignore this warning
@@ -95,8 +118,27 @@ This warning is often safe to ignore when:
- Your handler method intentionally omits parameters it doesn't need.
- You're using a simpler method signature for cleaner code.
- The performance impact is negligible for your application.
+- You're prototyping or writing quick utility code where clarity matters more than efficiency.
+
+The relaxed conversion works correctly; this warning just indicates a minor efficiency consideration. The compiler creates a wrapper delegate automatically, which adds a small performance overhead but doesn't affect functionality.
-The relaxed conversion works correctly; this warning just indicates a minor efficiency consideration.
+### Example of when ignoring is appropriate
+
+```vb
+Public Class QuickLogger
+ Public Event LogMessage As Action(Of String, DateTime)
+
+ ' Simple handler that ignores the timestamp parameter
+ Private Sub WriteToConsole()
+ Console.WriteLine("Something was logged")
+ End Sub
+
+ Public Sub SetupLogging()
+ ' This generates BC42328, but it's fine for simple scenarios
+ AddHandler LogMessage, AddressOf WriteToConsole
+ End Sub
+End Class
+```
## See also
diff --git a/docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vb b/docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vb
new file mode 100644
index 0000000000000..39ae891067d4f
--- /dev/null
+++ b/docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vb
@@ -0,0 +1,84 @@
+Imports System
+
+'
+Public Class DocumentProcessor
+ ' Standard .NET event using EventHandler
+ Public Event DocumentProcessed As EventHandler
+
+ ' Custom event with different signature
+ Public Event StatusChanged As Action(Of String)
+
+ ' Handlers with different signatures
+
+ ' Exact match for EventHandler - no warning
+ Private Sub OnDocumentProcessed_Exact(sender As Object, e As EventArgs)
+ Console.WriteLine("Document processed (exact signature)")
+ End Sub
+
+ ' Simplified handler - causes BC42328 with EventHandler
+ Private Sub OnDocumentProcessed_Simple()
+ Console.WriteLine("Document processed (simple)")
+ End Sub
+
+ ' Handler for custom event - exact match
+ Private Sub OnStatusChanged_Exact(message As String)
+ Console.WriteLine($"Status: {message}")
+ End Sub
+
+ ' Handler with ignored parameters - causes BC42328 with custom event
+ Private Sub OnStatusChanged_Simple()
+ Console.WriteLine("Status changed")
+ End Sub
+
+ Public Sub DemonstrateWarnings()
+ Console.WriteLine("Setting up event handlers...")
+
+ ' These work without warnings (exact matches)
+ AddHandler DocumentProcessed, AddressOf OnDocumentProcessed_Exact
+ AddHandler StatusChanged, AddressOf OnStatusChanged_Exact
+
+ ' These generate BC42328 warnings (relaxed conversions)
+ AddHandler DocumentProcessed, AddressOf OnDocumentProcessed_Simple
+ AddHandler StatusChanged, AddressOf OnStatusChanged_Simple
+
+ ' Fire the events
+ RaiseEvent DocumentProcessed(Me, EventArgs.Empty)
+ RaiseEvent StatusChanged("Processing complete")
+ End Sub
+
+ Public Sub DemonstrateSolutions()
+ Console.WriteLine("Using solutions to avoid warnings...")
+
+ ' Solution 1: Assign to variable first
+ Dim handler1 As EventHandler = AddressOf OnDocumentProcessed_Simple
+ AddHandler DocumentProcessed, handler1
+
+ ' Solution 2: Use lambda expression
+ AddHandler DocumentProcessed, Sub(s, e) OnDocumentProcessed_Simple()
+
+ ' Solution 3: Direct assignment to delegate variable
+ Dim handler2 As Action(Of String) = AddressOf OnStatusChanged_Simple
+ AddHandler StatusChanged, handler2
+
+ ' Fire the events
+ RaiseEvent DocumentProcessed(Me, EventArgs.Empty)
+ RaiseEvent StatusChanged("All solutions work")
+ End Sub
+End Class
+'
+
+Module Program
+ Sub Main()
+ Dim processor As New DocumentProcessor()
+
+ Console.WriteLine("=== Demonstrating BC42328 Warning ===")
+ processor.DemonstrateWarnings()
+
+ Console.WriteLine()
+ Console.WriteLine("=== Demonstrating Solutions ===")
+ processor.DemonstrateSolutions()
+
+ Console.WriteLine("Press any key to exit...")
+ Console.ReadKey()
+ End Sub
+End Module
\ No newline at end of file
diff --git a/docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vbproj b/docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vbproj
new file mode 100644
index 0000000000000..5a06255081c8d
--- /dev/null
+++ b/docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vbproj
@@ -0,0 +1,9 @@
+
+
+
+ Exe
+ net8.0
+ BC42328Example
+
+
+
\ No newline at end of file