AireFrame SDK

We publish a C# ASP.Net Core SDK that can be used to integrate AireFrame with custom data sources.

Currently the SDK supports .NET 8 upwards.

Installation

The SDK is published to a custom AzureDevops package feed. To access it you need to add a NuGet.config file to your project with the following:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="AireFrame" value="https://pkgs.dev.azure.com/AireLogic/Public/_packaging/AireFrame/nuget/v3/index.json" />
  </packageSources>
</configuration>

Then install the package into your project.

Install-Package AireLogic.AireFrame.DataProviderSdk

Or:

dotnet add package AireLogic.AireFrame.DataProviderSdk

Usage

These are the interfaces you can implement:

• ISubjectProvider, ISubjectLocationProvider, IStructureTypeProvider, IStructuralEntityProvider, IGroupProvider (or their read-only counterparts)
• IStructuredDataProvider

In Startup.ConfigureServices:

services
    .AddDataProviderServer<YourDataSource>(
        new DataProviderServerSettings(
            new AuthOptions(
                AUHTORITY_HOST,
                ISSUER_HOST,
                AUDIENCE)
        )
    )
    .AddSubjectProvider<YourSubjectProviderImplementation, YourSubjectLocationProviderImplementation, YourStructureTypeProvider, YourStructuralEntityProvider, YourGroupProvider>() // Or .AddReadOnlySubjectProvider
    .AddStructuredDataProvider<YourStructuredDataProviderImplementation>(o => {
        // This adds the IDataChangeNotificationClient which enables caching of structured data
        options.ServerConfiguration = new AireFrameServerConfiguration(GrpcEndpoint, ClientCredentials);
    });

In Startup.Configure:

app.UseDataProviderServer();

..

app.UseEndpoints(endpoints =>
{
    endpoints.MapDataProvider();
});

Configuration

Our Data Provider SDK supports configuring data sources with distinct read-only and read-write capabilities. This allows you to tailor the behavior based on runtime conditions.

• Read-Only Capabilities: For scenarios where data modification is not required or should be restricted. Use ReadOnlySubjectProviderOptions to configure data sources that should only support read operations.
• Read-Write Capabilities: Use ReadWriteSubjectProviderOptions for data sources that require both read and write operations. These options also support dynamically setting the data source to read-only mode based on runtime conditions.

In Startup.ConfigureServices:

1. Define Read-Write Capabilities

services
    .AddDataProviderServer<YourDataSource>(
        // Configuration settings
    )
    .AddSubjectProvider<YourSubjectProviderImplementation, YourSubjectLocationProviderImplementation>(options => {
      options.Lifetime = ServiceLifetime.Scoped;
      // Configure dynamic read-only check
      options.IsReadOnly = (serviceProvider, dataSourceContext) => {
          // Insert logic to determine if the provider should be read-only
          return Task.FromResult(false); // Example: dynamically determine based on context
      };
    })
    .AddStructuredDataProvider<YourStructuredDataProviderImplementation>()
    .AddEventHandler<YourEventHandlerImplementation>();

2. Define Read-Only Capabilities

services.AddDataProviderServer<YourDataSource>(config => {
    // Configuration settings
})
.AddReadOnlySubjectProvider<ReadOnlySubjectProvider, ReadOnlySubjectLocationProvider>(options => {
    options.Lifetime = ServiceLifetime.Scoped;
    // Read-only options do not require IsReadOnly configuration
});

Authentication

To setup authentication for your service you need to create an client and a scope on the authority server that AireFrame is using. For cloud-hosted AireFrame production this is AireIdentity

This address is what you need to provide for both the AUHTORITY_HOST and ISSUER_HOST values. The scope you created will be the AUDIENCE value.

Storage Libraries

In order to make it easier to implement the SDK we have created a storage library that can be used to store data in a Postgres. This is available as NuGet package AireLogic.AireFrame.DataProvider.Storage.PostgreSql.

Code Generation Library

We have also created a code generation library that can be used to generate the boilerplate code for the SDK. This is available as NuGet package AireLogic.AireFrame.DataProviderSdk.Analyzers.

To use this library, add the package to your csproj:

<PackageReference Include="AireLogic.AireFrame.DataProviderSdk.Analyzers" Version="..">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

When one or more [DataPointItem("key")] attributes are added to members on a partial class, the library will automatically generate a GetDataPointItems method on that class that will convert the members to DataPointItems.