Archetypical.Software.Vega.Api.Abstractions 1.5.0

Archetypical.Software.Vega.Api.Abstractions

Base controllers and other service registry helpers.

Getting Started

Instructions to get started with this project.

Usage

VegaApiOptions

The VegaApiOptions class allows you to configure various aspects of the Vega API. Here are the main properties:

• ServiceName: The name of the service.
• Version: The version of the API.
• TurnOff: Options to disable certain features.
• OpenTelemetryOptions: Options for OpenTelemetry configuration.
• DistributedCache: Options for configuring the Dapr distributed cache (DaprDistributedCacheOptions). Default state store name is "statestore".

BuilderExtensions

The BuilderExtensions class provides methods to configure and initialize the Vega API. Key methods include:

• CreateVegaApi: Sets up the API with the provided options. This includes configuring controllers, OData, OpenTelemetry, Dapr integration, and registering the DaprDistributedCache as the default IDistributedCache implementation if Dapr is enabled.
• ConfigureDbContext: Configures the database context.
• ConfigureOtel: Configures OpenTelemetry for logging, tracing, and metrics.
• ExposeOData: Exposes OData endpoints.
• UseVegaApiDefaults: Applies default configurations and initializes contexts.

appsettings.json

The appsettings.json file is used to configure the application settings, including logging levels, allowed hosts, and Vega-specific settings such as database connection strings and API version.

Example configuration:

{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "VEGA": {
        "DBCONTEXT": {
            "CONNECTIONSTRING": "Data Source=test.db;",
            "PROVIDER": "SQLite"
        },
        "API": {
            "VERSION": "1.0-pre1",
            "OpenTelemetryOptions": {
                "Tracing": {
                    "EntityFramework": {
                        "LogStatement": false
                    }
                }
            },
            "DistributedCache": {
                "StateStoreName": "my-cache-store" // Replace with your Dapr state store component name
            }
        }
    }
}

Dapr Distributed Cache

This library includes an IDistributedCache implementation, DaprDistributedCache, that leverages a configured Dapr state store component.

Configuration

When Dapr is enabled (via VegaApiOptions.TurnOff.Dapr = false), the CreateVegaApi extension method automatically registers DaprDistributedCache as the singleton implementation for IDistributedCache.

The specific Dapr state store component to use can be configured via appsettings.json or environment variables.

appsettings.json Configuration

You can specify the Dapr state store component name within the VEGA configuration section:

{
    "VEGA": {
        // ... other VEGA settings
        "API": {
            // ... other API settings
            "DistributedCache": {
                "StateStoreName": "my-cache-store" // Replace with your Dapr state store component name
            }
        }
    }
}

If not specified, it defaults to using a Dapr state store named "statestore".

Dependencies

• Requires the Dapr.AspNetCore package.
• Requires a running Dapr sidecar with a configured state store component matching the StateStoreName.

VegaDbContext

The VegaDbContext class is the base class for all Vega DbContexts. It uses default environment variables for the connection string and database provider, and supports both in-memory and SQLite for testing. All other DbContexts should inherit from this class.

Parameters

• options: The options to be used by a DbContext.
• configuration: The configuration to be used for retrieving environment variables.
• logger: The logger to be used for logging information, warnings, and errors.

Exceptions

• ArgumentNullException: Thrown when the configuration is null.
• InvalidOperationException: Thrown when the configuration section 'VEGA:DBCONTEXT' is missing.

Remarks

The class supports multiple database providers:

• MSSQL: Uses Microsoft SQL Server as the database provider.
• SQLITE: Uses SQLite as the database provider.
• COCKROACHDB: Uses CockroachDB as the database provider.
• POSTGRESQL: Uses PostgreSQL as the database provider.
• InMemory: Uses an in-memory database for testing purposes when no provider is specified.

Configuring Database Providers

The VegaDbContext class supports multiple database providers. You can configure the desired provider and connection string in the appsettings.json file under the VEGA:DBCONTEXT section.

Supported Database Providers

1. Microsoft SQL Server (MSSQL)
2. SQLite
3. CockroachDB
4. PostgreSQL
5. InMemory (for testing purposes)

Configuration Examples

Microsoft SQL Server (MSSQL)

{
    "VEGA": {
        "DBCONTEXT": {
            "CONNECTIONSTRING": "Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;",
            "PROVIDER": "MSSQL"
        }
    }
}

SQLite

{
    "VEGA": {
        "DBCONTEXT": {
            "CONNECTIONSTRING": "Data Source=mydatabase.db;",
            "PROVIDER": "SQLite"
        }
    }
}

CockroachDB

{
    "VEGA": {
        "DBCONTEXT": {
            "CONNECTIONSTRING": "Host=myHost;Port=26257;Database=myDatabase;Username=myUsername;Password=myPassword;",
            "PROVIDER": "COCKROACHDB"
        }
    }
}

PostgreSQL

{
    "VEGA": {
        "DBCONTEXT": {
            "CONNECTIONSTRING": "Host=myHost;Port=5432;Database=myDatabase;Username=myUsername;Password=myPassword;",
            "PROVIDER": "POSTGRESQL"
        }
    }
}

InMemory (for testing purposes)

{
    "VEGA": {
        "DBCONTEXT": {
            "PROVIDER": "InMemory"
        }
    }
}

Environment Variables

You can also configure the database connection using environment variables. The environment variables should start with VEGA__DBCONTEXT__ followed by the property name in uppercase.

Example for PostgreSQL:

export VEGA__DBCONTEXT__PROVIDER=POSTGRESQL
export VEGA__DBCONTEXT__PGHOST=myHost
export VEGA__DBCONTEXT__PGPORT=5432
export VEGA__DBCONTEXT__PGDATABASE=myDatabase
export VEGA__DBCONTEXT__PGUSER=myUsername
export VEGA__DBCONTEXT__PGPASSWORD=myPassword

These configurations will be picked up by the VegaDbContext class during initialization.