Akka.Analyzer: Add AK2002 documentation (#7527)

* Akka.Analyzer: Add AK2002 documentation

* Update documentation

* Cleanup

Author: Arkatufus

docs/articles/debugging/akka-analyzers.md

@@ -23,6 +23,7 @@ Akka.Analyzer is a [Roslyn Analysis and Code Fix](https://learn.microsoft.com/en
 | [AK1008](xref:AK1008) | Creating actors using `ActorSystem.ActorOf()` inside an actor | Warning  | Actor Design |
 | [AK2000](xref:AK2000) | Do not use `Ask` with `TimeSpan.Zero` for timeout.                                                                      | Error    | API Usage    |
 | [AK2001](xref:AK2001) | Do not use automatically handled messages in inside `Akka.Cluster.Sharding.IMessageExtractor`s.                         | Warning  | API Usage    |
+| [AK2002](xref:AK2002) | `Context.Materializer()` should not be invoked multiple times, use a cached value instead.                              | Warning  | API Usage    |
 
 ## Deprecated Rules
 

docs/articles/debugging/rules/AK2002.md

@@ -0,0 +1,97 @@
+---
+uid: AK2002
+title: Akka.Analyzers Rule AK2002 - "`Context.Materializer()` should not be invoked multiple times, use a cached value instead."
+---
+
+# AK2002 - Warning
+
+`Context.Materializer()` should not be invoked multiple times, use a cached value instead.
+
+## Cause
+
+Calling `Context.Materializer()` inside an actor will create a new instance of streams [`ActorMaterializer`](xref:Akka.Streams.ActorMaterializer). When you create multiple streams, most likely you will only need a single actor materializer; creating multiple `ActorMaterializer` would only create memory pressure and potential memory leak if they're not disposed properly.
+
+> [!NOTE]
+>
+> Using `ActorSystem.Materializer()` is safe because it is cached internally and disposed of during shutdown.
+
+An example:
+
+```csharp
+using Akka.Actor;
+using Akka.Streams;
+using Akka.Streams.Dsl;
+
+public sealed class MyActor : ReceiveActor
+{
+    public MyActor()
+    {
+        ReceiveAsync<string>(
+            s => s == "hello",
+            async _ =>
+            {
+                await Source.Single(1)
+                    .Select(x => x + 1)
+                    .ToMaterialized(Sink.ForEach<int>(_ => { }), Keep.Right)
+                    .Run(Context.Materializer());
+            });
+    }
+}
+```
+
+## Resolution
+
+There are two ways to resolve this problem:
+
+```csharp
+using Akka.Actor;
+using Akka.Streams;
+using Akka.Streams.Dsl;
+
+public sealed class MyActor : ReceiveActor
+{
+    private readonly ActorMaterializer _materializer;
+    
+    public MyActor()
+    {
+        _materializer = Context.Materializer();
+        
+        ReceiveAsync<string>(
+            s => s == "hello",
+            async _ =>
+            {
+                await Source.Single(1)
+                    .Select(x => x + 1)
+                    .ToMaterialized(Sink.ForEach<int>(_ => { }), Keep.Right)
+                    .Run(_materializer); // Use a cached ActorMaterializer
+            });
+    }
+
+    protected override void PostStop()
+    {
+        _materializer.Dispose(); // Dispose the ActorMaterializer when the actor is stopped.
+    }
+}
+```
+
+```csharp
+using Akka.Actor;
+using Akka.Streams;
+using Akka.Streams.Dsl;
+
+public sealed class MyActor : ReceiveActor
+{
+    public MyActor()
+    {
+        ReceiveAsync<string>(
+            s => s == "hello",
+            async _ =>
+            {
+                await Source.Single(1)
+                    .Select(x => x + 1)
+                    .ToMaterialized(Sink.ForEach<int>(_ => { }), Keep.Right)
+                    .Run(Context.System.Materializer()); // Use ActorSystem.Materializer(), this is cached internally
+            });
+    }
+}
+```

docs/articles/debugging/rules/toc.yml

@@ -19,4 +19,6 @@
 - name: AK2000
   href: AK2000.md
 - name: AK2001
-  href: AK2001.md
+  href: AK2001.md
+- name: AK2002
+  href: AK2002.md