How it works
Last updated
Last updated
In the Blackboard framework, we make extensive use of modern C# features such as partial classes, the Roslyn compiler and its analyzers, and source generators to simplify development and automate code generation. Below, we'll break down these concepts and how they work together to enhance your workflow.
Partial classes allow you to split the definition of a class across multiple files. This is particularly useful for large classes or for situations where parts of the class need to be automatically generated, as seen in our framework.
In the image, the green and blue boxes are part of the same class, but they are declared in different sections of the code:
Green Box: This is where you manually define certain properties or fields like private int health = 100;.
Blue Box: This part of the class is automatically generated by a source generator (explained later), which wraps the field into a signal-based structure for better data management.
Partial classes allow both the manually written and automatically generated code to coexist and work seamlessly.
The above code represents the two different parts of the same class, with one part written manually and the other generated automatically.
The C# compiler is responsible for transforming your C# code into machine-readable code. When you compile your code, the compiler reads both manually written code (green box) and automatically generated code (blue box), combining them into a single class at runtime.
In our framework, this means that the compiler:
Reads your custom code from files like ExampleBlackboard.
Incorporates the generated code from partial classes created by the source generator.
Produces the final binary that is executed at runtime.
Roslyn Analyzers are tools that run during compilation and can inspect, diagnose, and provide warnings or suggestions about your code. They can be thought of as static analysis tools that help improve code quality by catching errors, enforcing coding styles, or suggesting performance improvements.
In the Blackboard framework, Roslyn Analyzers play a role in ensuring that your custom blackboard classes conform to the expected patterns and conventions. For example, if a user fails to set up a signal property correctly, an analyzer could provide a compile-time warning with a suggestion to fix the issue.
Source generators are a powerful feature of the C# compiler that allows additional source code to be automatically generated at compile time. In the context of the Blackboard framework, source generators take care of the repetitive and boilerplate code necessary for signal management.
In the example provided in the image, the blue box is generated by a source generator. Instead of manually creating the signal wrappers for fields like health, the source generator creates this code automatically based on some input rules or configurations.
For example, the code generator could inspect the field private int health = 100; and generate the corresponding signal code like so:
This greatly simplifies development by reducing boilerplate code and ensuring consistency across your project.
You define a partial class like ExampleBlackboard, with some fields and properties.
The compiler reads your partial class and looks for additional code generated by source generators.
The source generator creates code that integrates your fields with the signal system.
During compilation, the Roslyn Analyzers ensure that your code follows the framework’s best practices, issuing warnings or suggestions if needed.
Finally, the compiler merges your manually written and automatically generated code into a complete class that can be used in your project.
By understanding these components, you can see how the Blackboard framework automates signal management and keeps your code clean and maintainable, while allowing flexibility with manual additions through partial classes.