Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devlooped/avatar
A modern compile-time generated interception/proxy library
https://github.com/devlooped/avatar
csharp-sourcegenerator dynamicproxy proxy-generation
Last synced: about 1 month ago
JSON representation
A modern compile-time generated interception/proxy library
- Host: GitHub
- URL: https://github.com/devlooped/avatar
- Owner: devlooped
- License: mit
- Archived: true
- Created: 2020-09-15T18:24:09.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2023-04-20T00:16:49.000Z (over 1 year ago)
- Last Synced: 2024-06-21T06:40:32.843Z (6 months ago)
- Topics: csharp-sourcegenerator, dynamicproxy, proxy-generation
- Language: C#
- Homepage: https://clarius.org/avatar
- Size: 1.32 MB
- Stars: 139
- Watchers: 4
- Forks: 10
- Open Issues: 9
-
Metadata Files:
- Readme: readme.md
- License: license.txt
Awesome Lists containing this project
- RSCG_Examples - avatar
README
Avatar
Avatar is a modern interception library which implements the [proxy pattern](https://en.wikipedia.org/wiki/Proxy_pattern) and runs everywhere, even where run-time code generation (Reflection.Emit) is forbidden or limitted, like physical iOS devices and game consoles, through compile-time code generation. The proxy behavior is configured in code using what we call a *behavior pipeline*.
> *Avatars blend in with the Na'vi seamlessly, and you can control their behavior precisely by 'driving' them through a psionic link. Just like a [proxy](https://en.wikipedia.org/wiki/Proxy_pattern), with behavior driven through code.*
[](https://www.nuget.org/packages/Avatar)
[](https://www.nuget.org/packages/Avatar)
[](https://github.com/devlooped/avatar/blob/main/LICENSE)
[](https://discord.gg/AfGsdRa)
[](https://github.com/devlooped/avatar)
[](https://pkg.kzu.io/index.json)
[](https://github.com/devlooped/avatar/actions?query=branch%3Amain+workflow%3Abuild+)
> NOTE: Avatar provides a fairly low-level API with just the essential building blocks on top of which higher-level APIs can be built, such as the upcoming Moq vNext API.
## Requirements
Avatar is a .NET Standard 2.0 library and runs on any runtime that supports that.
Compile-time proxy generation leverages [Roslyn source generators](https://github.com/dotnet/roslyn/blob/master/docs/features/source-generators.cookbook.md) and therefore requires C# 9.0, which at this time is included in Visual Studio 16.8 (preview or later) and the .NET 5.0 SDK (RC or later). Compile-time generated proxies support the broadest possible run-time platforms since they don't require any Reflection.Emit, and also don't pay that performance cost either.
Whenever compile-time proxy generation is not available, a fallback generation strategy is used instead, which leverages [Castle DynamicProxy](https://github.com/castleproject/Core/blob/master/docs/dynamicproxy-introduction.md) to provide the run-time code generation.
The client API for configuring proxy behaviors in either case is exactly the same.
> NOTE: even though generated proxies is the main usage for Avatar, the API was designed so that you can also consume the behavior pipeline easily from hand-coded proxies too.
## Usage
```csharp
ICalculator calc = Avatar.Of();
calc.AddBehavior((invocation, next) => ...);
```
`AddBehavior`/`InsertBehavior` overloads allow granular control of the avatar's behavior pipeline, which is basically a [chain of responsibility](https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern) that invokes all configured behaviors that apply to the current invocation. Individual behaviors can determine whether to short-circuit the call or call the next behavior in the chain.
Behaviors can also dynamically determine whether they apply to a given invocation by providing the optional `appliesTo` argument. In addition to the delegate-based overloads (called *anonymous behaviors*), you can also create behaviors by implementing the `IAvatarBehavior` interface:
```csharp
public interface IAvatarBehavior
{
bool AppliesTo(IMethodInvocation invocation);
IMethodReturn Execute(IMethodInvocation invocation, ExecuteHandler next);
}
```
## Common Behaviors
Some commonly used behaviors that are generally useful are provided in the library and can be added to avatars as needed:
* `DefaultValueBehavior`: sets default values for method return and *out* arguments. In addition to the built-in supported default values, additional default value factories can be registered for any type.
* `DefaultEqualityBehavior`: implements the *Object.Equals* and *Object.GetHashCode* members just like *System.Object* implements them.
* `RecordingBehavior`: simple behavior that keeps track of all invocations, for troubleshooting or reporting.
## Customizing Avatar Creation
If you want to centrally configure all your avatars, the easiest way is to simply provide your own factory method (i.e. `Stub.Of`), which in turn calls the `Avatar.Of` provided. For example:
```csharp
public static class Stub
{
[AvatarGenerator]
public static T Of() => Avatar.Of()
.AddBehavior(new RecordingBehavior())
.AddBehavior(new DefaultEqualityBehavior())
.AddBehavior(new DefaultValueBehavior());
}
```
The `[AvatarGenerator]` attribute is required if you want to leverage the built-in compile-time code generation, since that signals to the source generator that calls to your API end up creating an avatar at run-time and therefore a generated type will be needed for it during compile-time. You can actually explore how this very same behavior is implemented in the built-in Avatar API which is provided as a content file:
The `Avatar.cs` contains, for example:
```csharp
[AvatarGenerator]
public static T Of(params object[] constructorArgs) => Create(constructorArgs);
[AvatarGenerator]
public static T Of(params object[] constructorArgs) => Create(constructorArgs, typeof(T1));
```
As you can see, the Avatar API itself uses the same extensibility mechanism that your own custom factory methods can use.
### Static vs Dynamic Avatars
Depending on the project and platform, Avatars will automatically choose whether to use run-time proxies or compile-time ones (powered by Roslyn source generators). The latter are only supported when building C# 9.0+ projects.
You can opt out of the static avatars by setting `EnableCompiledAvatars=false` in your project file:
```xml
false
```
This will switch the project to run-time proxies based on Castle.Core.
## Debugging Optimizations
There is nothing more frustrating than a proxy you have carefully configured that doesn't behave the way you expect it to. In order to make this a less frustrating experience, avatars are carefully optimized for debugger display and inspection, so that it's clear what behaviors are configured, and invocations and results are displayed clearly and concisely. Here's the debugging display of the `RecordingBehavior` that just keeps track of invocations and their return values for example:
And here's the invocation debugger display from an anonymous behavior:
## Samples
The `samples` folder in the repository contains a few interesting examples of how *Avatar* can be used to implement some fancy use cases. For example:
* Forwarding calls to matching interface methods/properties (by signature) to a static class. The example uses this to wrap calls to *System.Console* via an *IConsole* interface.
* Forwarding calls to a target object using the DLR (that backs the *dynamic* keyword in C#) API for high-performance late binding.
* Custom `Stub.Of` factory that creates avatars that have common behaviors configured automatically.
* Custom avatar factory method that adds an int return value randomizer.
* Configuring the built-in *DefaultValueBehavior* so that every time a string property is retrieved, it gets a random lorem ipsum value.
* Logging all calls to an avatar to the Xunit output helper.
## Sponsors
by @clarius 
*[get mentioned here too](https://github.com/sponsors/devlooped)!*