[Feature] CommunityToolkit.AppServices package

[Sergio0694]

CommunityToolkit.AppServices

A library and accompanying source generator to make working with AppService much easier 🚀

Simply define an interface:

[AppService("MyAppService")]
public interface IMyAppService
{
    Task<int> SumNumbersAsync(int x, int y);
}

Then implement it in your desktop extension:

public sealed partial class MyAppService : IMyAppService
{
    public async Task<int> SumNumbersAsync(int x, int y)
    {
        return x + y;
    }
}

That's it! The source generator will automatically create for you:

• The base desktop extension infrastructure to receive commands, invoke them and send back results
• The whole UWP/WinUI 3 service to represent the other connection endpoint

That means, the host (the UWP/WinUI 3 app) can literally just do this:

int result = await App.Services.GetRequiredService<IMyAppService>().SumNumbersAsync(40, 2); // 42

This enables a fundamentally easier, less error prone and much less verbose way to interact with AppService APIs 🚀

We developed this library for the Microsoft Store, which uses it for all the desktop extension functionaly, and would like to open source it and add it to the Windows Community Toolkit, so that it can benefit all developers using UWP and WinUI 3. This can be used both to support UWP applications needing a desktop extension component to escape the sandbox (like the Microsoft Store is doing), as well as both UWP and WInUI 3 apps using AppService to connect to other applications registered as extensions.

Additional features

The library comes bundled with:

• Full set of APIs to manually create hosts and services
• Source generator generating all the endpoints manually
• Comprehensive Roslyn analyzers to emit errors/warnings for invalid uses
• Support for IProgress<T> values across processes
• Support for CancellationToken values across processes
• Support for custom serializers to be able to also marshal arbitrary types

API breakdown

namespace CommunityToolkit.AppServices;

[AttributeUsage(AttributeTargets.Interface, AllowMultiple = false, Inherited = false)]
public sealed class AppServiceAttribute : Attribute
{
    public AppServiceAttribute(string appServiceName);

    public string AppServiceName { get; }
}

[AttributeUsage(AttributeTargets.ReturnValue | AttributeTargets.Parameter, AllowMultiple = false, Inherited = false)]
public sealed class ValueSetSerializerAttribute : Attribute
{
    public ValueSetSerializerAttribute(Type valueSetSerializerType);

    public Type ValueSetSerializerType { get; }
}

public interface IValueSetSerializer<T>
{
    [return: NotNullIfNotNull("value")]
    ValueSet? Serialize(T? value);
    
    [return: NotNullIfNotNull("valueSet")]
    T? Deserialize(ValueSet? valueSet);
}

public enum AppServiceStatus
{
    Ok,
    Error,
    ActionNotFound,
    NoResponse,
    InvalidRequest,
    InvalidResponse,
    MismatchedResponseType,
    SerializationError,
    CantSend,
    AppServiceNotCompatible,
    Timeout,
    Canceled,
    CantStart
}

public sealed class AppServiceException : Exception
{
    public AppServiceStatus Status { get; }
}

public abstract class AppServiceHost
{
    protected AppServiceHost(string appServiceName);

    public bool OnBackgroundActivated(BackgroundActivatedEventArgs args);

    protected AppServiceRequest CreateAppServiceRequest([CallerMemberName] string? requestName = null);

    protected sealed class AppServiceRequest
    {
        public AppServiceRequest(AppServiceHost host, string requestName);

        public AppServiceRequest WithParameter<T>(T parameter, [CallerArgumentExpression("parameter")] string? parameterName = null);
        public AppServiceRequest WithParameter<TSerializer, TParameter>(TSerializer serializer, TParameter? parameter, [CallerArgumentExpression("parameter")] string? parameterName = null) where TSerializer : IValueSetSerializer<TParameter>;
        public AppServiceRequest WithProgress<T>(IProgress<T> progress);
        public AppServiceRequest WithProgress<TSerializer, TResult>(TSerializer serializer, IProgress<TResult?> progress) where TSerializer : IValueSetSerializer<TResult>;
        public AppServiceRequest WithCancellationToken(CancellationToken cancellationToken);

        public Task SendAndWaitForResultAsync();
        public Task<T> SendAndWaitForResultAsync<T>();
        public Task<TResult?> SendAndWaitForResultAsync<TSerializer, TResult>(TSerializer serializer) where TSerializer : IValueSetSerializer<TResult>;
        public Task SendAndWaitForResultAsync(TimeSpan timeout);
        public Task<T> SendAndWaitForResultAsync<T>(TimeSpan timeout);
        public Task<TResult?> SendAndWaitForResultAsync<TSerializer, TResult>(TSerializer serializer, TimeSpan timeout) where TSerializer : IValueSetSerializer<TResult>;
    }
}

public abstract class AppServiceComponent : IDisposable
{
    public event EventHandler? ConnectionFailed;
    public event EventHandler? ConnectionClosed;

    protected AppServiceComponent(string appServiceName);

    public async Task InitializeAppService();

    public void Dispose();

    protected void RegisterEndpoint(Action endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);
    protected void RegisterEndpoint<T>(Func<T> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);
    protected void RegisterEndpoint<TSerializer, TResult>(TSerializer serializer, Func<TResult?> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null) where TSerializer : IValueSetSerializer<TResult>;
    protected void RegisterEndpoint(Action<AppServiceParameters> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);
    protected void RegisterEndpoint<T>(Func<AppServiceParameters, T> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);
    protected void RegisterEndpoint<TSerializer, TResult>(TSerializer serializer, Func<AppServiceParameters, TResult?> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null) where TSerializer : IValueSetSerializer<TResult>;
    protected void RegisterEndpoint(Func<Task> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);
    protected void RegisterEndpoint<T>(Func<Task<T>> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);
    protected void RegisterEndpoint<TSerializer, TResult>(TSerializer serializer, Func<Task<TResult?>> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null) where TSerializer : IValueSetSerializer<TResult>; 
    protected void RegisterEndpoint(Func<AppServiceParameters, Task> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);    
    protected void RegisterEndpoint<T>(Func<AppServiceParameters, Task<T>> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null);    
    protected void RegisterEndpoint<TSerializer, TResult>(TSerializer serializer, Func<AppServiceParameters, Task<TResult?>> endpoint, [CallerArgumentExpression("endpoint")] string? endpointName = null) where TSerializer : IValueSetSerializer<TResult>;

    protected readonly struct AppServiceParameters
    {
        public AppServiceParameters(AppServiceComponent component, AppServiceConnection connection, ValueSet valueSet);

        public void GetParameter<T>(out T parameter, [CallerArgumentExpression("parameter")] string? parameterName = null);
        public void GetParameter<TSerializer, TParameter>(TSerializer serializer, out TParameter? parameter, [CallerArgumentExpression("parameter")] string? parameterName = null) where TSerializer: IValueSetSerializer<TParameter>;
        
        public void GetProgress<T>(out IProgress<T> progress);
        public void GetProgress<TSerializer, TResult>(TSerializer serializer, out IProgress<TResult?> progress) where TSerializer : IValueSetSerializer<TResult>;            
        
        public void GetCancellationToken(out CancellationToken cancellationToken);
    }
}

[michael-hawker]

@Sergio0694 we'll have to figure out how we demo this in the sample app, as we'll need the extension registered on the sample app itself, eh? It's a more advanced scenario we haven't really thought about how the infrastructure could support, so we'll have to do some thinking or special casing for the demo of this on the UWP sample head. 🤔

[Arlodotexe]

Samples are set up to primarily demo UI controls. Since this isn't a UI control, we have the option to write docs as usual and leave out the > [!SAMPLE SampleName] control part. Can always add something later :)

[Arlodotexe]

Related CommunityToolkit/Tooling-Windows-Submodule#57