Awareness email.

Author: gfraiteur

metalama-awareness-campaign/01_more_effective_way.md

@@ -0,0 +1,72 @@
+# Discover Metalama: A New Code Generation Toolkit for C#
+
+Hi {{firstName}},
+
+My name is **{{sendingAccountFirstName}}** and I’m helping PostSharp’s founder to gather feedback about **Metalama**, a new, free code generation and validation toolkit for C#.
+
+Given your experience in .NET, I thought you might be interested to learn about it and, on our side, we’re eager to hear your opinion, therefore this cold email.
+
+The idea behind Metalama is that you write custom attributes called **aspects**, which work as code templates. Here is our Hello World example: a logging aspect.
+
+```csharp
+using Metalama.Framework.Aspects;
+
+public class LogAttribute : OverrideMethodAspect
+{
+  public override dynamic? OverrideMethod()
+  {
+    Console.WriteLine( "Entering {meta.Target.Method}." );
+    try
+    {
+       return meta.Proceed();
+    }
+    finally
+    {
+       Console.WriteLine( "Leaving {meta.Target.Method}." );
+    }
+  }
+}
+```
+
+You can then use the aspect on any method, like this:
+
+```csharp
+[Log]
+void SomeMethod() => Console.WriteLine( "Hello, World!" );
+```
+
+Metalama transforms the code during compilation into this:
+
+```csharp
+void SomeMethod()
+{
+  Console.WriteLine( "Entering Program.SomeMethod()" );
+  try
+  {
+    Console.WriteLine( "Hello, World!" );
+  }
+  finally
+  {
+  Console.WriteLine( "Leaving Program.SomeMethod()" );
+  }
+}
+```
+
+It’s possible to preview or even debug the code generated by Metalama. The real benefit of this approach is that you can **drastically reduce repetitive code**. And if you want to change the code generation pattern, you just need to change the aspect. You get the idea!
+
+**Key Benefits of Metalama:**
+
+-   **Reduce repetitive code**
+-   **Easy code modifications**
+-   **Real-time feedback and code modifications**
+-   **Preview and debug generated code**
+
+You can find the source code of this example, as well as more examples, on [GitHub](https://github.com/postsharp/Metalama.Demo/blob/master/src/01_Log/LogAttribute.cs?mtm_campaign=awareness&mtm_source=instantly). You can learn more about Metalama thanks to the [video tutorials](https://doc.postsharp.net/metalama/videos?mtm_campaign=awareness&mtm_source=instantly) and [commented examples](https://doc.postsharp.net/metalama/examples?mtm_campaign=awareness&mtm_source=instantly).
+
+Our development team is looking forward to your feedback and questions on our [Slack community workspace](https://www.postsharp.net/slack?mtm_campaign=awareness&mtm_source=instantly). Of course, you can also answer this email and I’ll make sure it will reach an engineer.
+
+Thank you!
+
+All the best,
+**{{sendingAccountFirstName}}**
+Community Manager

metalama-awareness-campaign/02_naming_conventions.md

@@ -0,0 +1,38 @@
+# Validate Naming Conventions with Metalama
+
+Hi {{firstName}},
+
+In my previous email I briefly showed how you can use Metalama to generate code. Today, I would like to introduce Metalama’s second pillar: code verification.
+
+You’ve perhaps experienced how hard it can be to align everyone on the same naming conventions. With Metalama, you define rules and conventions using plain C#. They will be enforced both in real-time in the IDE and at compile time.
+
+For instance, assume you want every class implementing IInvoiceFactory to have the InvoiceFactory suffix. You can do this with a single attribute.
+
+```csharp
+[DerivedTypesMustRespectNamingConvention( "*InvoiceFactory" )]
+public interface IInvoiceFactory
+{
+Invoice CreateFromOrder( Order order );
+}
+```
+
+If someone violates this rule, a warning will immediately be reported:
+
+```
+LAMA0903. The type ‘MyInvoiceConverted’ does not respect the naming convention set on the base class or interface ‘IInvoiceFactory’. The type name should match the "\*InvoiceFactory" pattern.
+```
+
+The shorter the feedback loop is, the smoother the code reviews will go! Not talking about the frustration both sides avoided!
+
+You can learn more about code validation with Metalama in our [online documentation](https://doc.postsharp.net/metalama/examples?mtm_campaign=awareness&mtm_source=instantly).
+
+As I wrote in my first email, our development team is looking forward to your feedback and questions on our [Slack community workspace](https://www.postsharp.net/slack?mtm_campaign=awareness&mtm_source=instantly). Of course, you can also answer this email and I’ll make sure it will reach an engineer.
+
+Thank you!
+
+All the best,
+**{{sendingAccountFirstName}}**
+Community Manager
+
+_P.S. We will send you 3 more emails about Metalama and then stop. You can unsubscribe at any time._
+

metalama-awareness-campaign/04_caching.md metalama-awareness-campaign/03_caching.mdmetalama-awareness-campaign/04_caching.md renamed to metalama-awareness-campaign/03_caching.md

@@ -1,3 +1,6 @@
+# Here is How to Save Time on Caching
+
+
 Hello!
 
 It's Fedja from Metalama again. In my previous emails, I described Metalama as a meta-programming _framework_ that allows you to generate and validate code as you type.

metalama-awareness-campaign/04_validating_architecture.md

@@ -0,0 +1,83 @@
+# Get your development team to adhere to architecture
+
+Developers need to follow specific rules and conventions to work together effectively as a team. This adherence ensures that individual contributions integrate seamlessly into the overall application.
+
+In a previous email, we discussed how to enforce naming conventions. Today, let's examine how to verify that components are _used_ as expected. You might have just written a method meant only to support a test, but how can you enforce that it's not used in production code?
+
+* Option 1: Add comments such as **DO NOT USE IN PRODUCTION CODE!**, hoping the exclamation mark will help.
+* Option 2: Rely on code reviews. This can be slow, frustrating, and costly.
+* Option 3: Make your architecture _executable_ so it can be automatically enforced straight from the editor. You guessed it, that's where Metalama comes in handy.
+
+The [open-source](https://github.com/postsharp/Metalama.Extensions/tree/HEAD/src/Metalama.Extensions.Architecture) [Metalama.Extensions.Architecture](https://www.nuget.org/packages/Metalama.Extensions.Architecture) package offers several pre-made custom attributes and compile-time APIs that cover many common conventions teams might want to follow.
+
+## Custom attributes
+
+Let's assume we have a constructor that slightly modifies the object's behavior to make it more testable. We want to ensure that this constructor is used only in tests. Metalama provides the [CanOnlyBeUsedFrom](https://doc.postsharp.net/etalama/api/metalama-extensions-architecture-aspects-canonlybeusedfromattribute) attribute for this purpose.
+
+```c#
+using Metalama.Extensions.Architecture.Aspects;
+
+namespace CommonTasks.ValidatingArchitecture
+{
+    public class OrderShipping
+    {
+        private bool isTest;
+
+        public OrderShipping()
+        {
+        }
+
+        [CanOnlyBeUsedFrom(Namespaces = new[] {"**.Tests"})]
+        public OrderShipping(bool isTest)
+        {
+            // Used to trigger specific test configuration
+            this.isTest = isTest;
+        }
+    }
+}
+```
+
+If we attempt to create a new `OrderShipping` instance in a namespace that isn't suffixed by `Tests`, we will see a warning.
+
+![](../metalama-email-course/images/ValidationWarning.jpg)
+
+## Fabrics
+
+Suppose we have a project composed of a large number of components. Each of these components is implemented in its own namespace and is made up of several classes. There are so many components that we don't want to have them each in their own project.
+
+However, we still want to isolate components from each other. Specifically, we want `internal` members of each namespace to be visible only within this namespace. Only `public` members should be accessible outside of its home namespace.
+
+Additionally, we want `internal` components to be accessible from any test namespace.
+
+With Metalama, you can validate each namespace by adding a _fabric_ type: a compile-time class that executes within the compiler or the IDE.
+
+```cs
+namespace MyComponent
+{
+    internal class Fabric : NamespaceFabric
+    {
+        public override void AmendNamespace(INamespaceAmender amender)
+        {
+            amender.InternalsCanOnlyBeUsedFrom(from =>
+                from.CurrentNamespace().Or(or => or.Type("**.Tests.**")));
+        }
+    }
+}
+```
+
+Now, if some foreign code tries to access an internal API of the `MyComponent` namespace, a warning will be reported.
+
+In addition to `InternalsCanOnlyBeUsedFrom`, the package also includes `InternalsCannotBeUsedFrom`, `CanOnlyBeUsedFrom`, and `CannotOnlyBeUsedFrom`. You can easily build more rules based on the code model.
+
+## Conclusion
+
+We've just seen two examples of how you can validate your code using pre-built Metalama aspects or compile-time APIs.
+
+Enforcing rules and conventions in this manner allows you to:
+
+- Eliminate the need for a written set of rules to which everyone must refer.
+- Provide immediate feedback to developers within the familiar confines of the IDE itself.
+- Improve code reviews as they now only need to focus on the code itself.
+- Simplify the codebase because it adheres to consistent rules.
+
+You can learn more about architecture validation in our online [documentation](https://doc.postsharp.net/metalama/conceptual/architecture/usage).