TabuLynx.Core 0.7.0

TabuLynx.Core

The foundational library for the TabuLynx ecosystem, providing core abstractions, interfaces, and utilities for building applications that interact with Analysis Services Tabular Models, Power BI datasets, SSAS, and Microsoft Fabric.

✨ Features

• Core Abstractions: Essential interfaces (IQueryExecutor, IConnection) for building TabuLynx applications
• Configuration Management: Strongly-typed configuration with TabuLynxOptions for connection settings
• Dependency Injection: Built-in support for .NET dependency injection with validation
• Host Builder Pattern: Simplified application bootstrapping with TabuLynxHost
• Multi-Platform Support: Foundation for connecting to Power BI, SSAS, and Microsoft Fabric
• Azure Authentication: Built-in support for Azure AD authentication parameters
• Validation: Automatic configuration validation with data annotations

📦 Installation

dotnet add package TabuLynx.Core

🏗️ Dependencies

This package provides foundational functionality and depends on:

• Microsoft.Extensions.DependencyInjection (9.0.0) - Dependency injection container
• Microsoft.Extensions.Configuration (9.0.4) - Configuration abstraction
• Microsoft.Extensions.Options.ConfigurationExtensions (9.0.4) - Options pattern integration
• Microsoft.Extensions.Options.DataAnnotations (9.0.4) - Configuration validation
• .NET 8.0 - Latest .NET runtime

Note: TabuLynx.Core provides the foundation that other TabuLynx packages build upon. You'll typically use this alongside packages like TabuLynx.Query.Executor or TabuLynx.Model.Extractor.

🚀 Quick Start

1. Basic Configuration

appsettings.json:

{
  "TabuLynx": {
    "ConnectionString": "Provider=MSOLAP;Data Source=localhost:12345;"
  }
}

Console Application:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using TabuLynx.Core.Configuration;
using TabuLynx.Core.Interfaces;
using TabuLynx.Core.Connection;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var services = new ServiceCollection();

// Configure TabuLynx options
services.Configure<TabuLynxOptions>(configuration.GetSection("TabuLynx"));

// Register core services
services.AddSingleton<IConnection, TabuLynxConnection>();

var serviceProvider = services.BuildServiceProvider();

// Use the connection
var connection = serviceProvider.GetRequiredService<IConnection>();
Console.WriteLine($"Connection: {connection.ConnectionString}");

2. Using TabuLynxHost Builder

using TabuLynx.Core.Hosting;
using TabuLynx.Core.Interfaces;
using Microsoft.Extensions.DependencyInjection;

var host = TabuLynxHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration(config =>
    {
        config.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);
    })
    .ConfigureServices((context, services) =>
    {
        // TabuLynxOptions are automatically configured and validated
        services.AddSingleton<IConnection, TabuLynxConnection>();
        
        // Add other TabuLynx services here
        // services.AddAdomdQueryExecutorForLocalPowerBI();
        // services.AddDmvModelExtractor();
    })
    .Build();

var connection = host.Services.GetRequiredService<IConnection>();

3. ASP.NET Core Integration

using TabuLynx.Core.Configuration;
using TabuLynx.Core.Interfaces;
using TabuLynx.Core.Connection;

var builder = WebApplication.CreateBuilder(args);

// Configure TabuLynx
builder.Services.Configure<TabuLynxOptions>(
    builder.Configuration.GetSection("TabuLynx"));

// Register core services
builder.Services.AddSingleton<IConnection, TabuLynxConnection>();

var app = builder.Build();

app.MapGet("/connection", (IConnection connection) =>
{
    return Results.Ok(new
    {
        HasConnectionString = !string.IsNullOrEmpty(connection.ConnectionString),
        HasTenantId = !string.IsNullOrEmpty(connection.TenantId),
        HasClientId = !string.IsNullOrEmpty(connection.ClientId)
    });
});

app.Run();

⚙️ Configuration Options

The TabuLynxOptions class supports comprehensive configuration for different scenarios:

Configuration Examples

Local Power BI Desktop:

{
  "TabuLynx": {
    "ConnectionString": "Provider=MSOLAP;Data Source=localhost:{port};"
  }
}

SSAS Server with Windows Authentication:

{
  "TabuLynx": {
    "ConnectionString": "Provider=MSOLAP;Data Source=your-server;Initial Catalog=your-database;Integrated Security=SSPI;"
  }
}

Microsoft Fabric / Power BI Premium:

{
  "TabuLynx": {
    "ConnectionString": "Provider=MSOLAP;Data Source=powerbi://api.powerbi.com/v1.0/myorg/your-workspace;Initial Catalog=your-dataset;",
    "TenantId": "your-tenant-id",
    "ClientId": "your-app-client-id",
    "ClientSecret": "your-app-client-secret"
  }
}

🔧 Core Interfaces

IQueryExecutor

Defines the contract for executing queries against Analysis Services:

public interface IQueryExecutor
{
    Task<string> ExecuteQueryAsync(string query);
    Task<List<Dictionary<string, object>>> ExecuteQueryWithDictionaryResultsAsync(string query);
}

Usage:

// Implemented by TabuLynx.Query.Executor package
var result = await queryExecutor.ExecuteQueryAsync("EVALUATE ROW(\"Hello\", \"World\")");
var dictResults = await queryExecutor.ExecuteQueryWithDictionaryResultsAsync("SELECT * FROM $SYSTEM.TMSCHEMA_TABLES");

IConnection

Provides connection configuration and authentication details:

public interface IConnection
{
    string ConnectionString { get; set; }
    string TenantId { get; set; }
    string ClientId { get; set; }
    string ClientSecret { get; set; }
    string Scope { get; set; }
}

Usage:

public class CustomService
{
    private readonly IConnection _connection;
    
    public CustomService(IConnection connection)
    {
        _connection = connection;
    }
    
    public void DoSomething()
    {
        var connectionString = _connection.ConnectionString;
        // Use connection details...
    }
}

🏗️ Building TabuLynx Applications

Complete Application Example

using TabuLynx.Core.Hosting;
using TabuLynx.Core.Interfaces;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

// Create and configure host
var host = TabuLynxHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration(config =>
    {
        config.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);
        config.AddEnvironmentVariables();
    })
    .ConfigureServices((context, services) =>
    {
        // Add logging
        services.AddLogging(builder => builder.AddConsole());
        
        // Core TabuLynx services (automatically configured)
        services.AddSingleton<IConnection, TabuLynxConnection>();
        
        // Add other TabuLynx packages
        // services.AddAdomdQueryExecutorForLocalPowerBI();
        // services.AddDmvModelExtractor();
        
        // Add your custom services
        services.AddTransient<MyDataService>();
    })
    .Build();

// Use services
var dataService = host.Services.GetRequiredService<MyDataService>();
await dataService.ProcessDataAsync();

public class MyDataService
{
    private readonly IConnection _connection;
    private readonly ILogger<MyDataService> _logger;
    
    public MyDataService(IConnection connection, ILogger<MyDataService> logger)
    {
        _connection = connection;
        _logger = logger;
    }
    
    public async Task ProcessDataAsync()
    {
        _logger.LogInformation("Processing data with connection: {ConnectionString}", 
            _connection.ConnectionString);
        
        // Your business logic here
    }
}

Environment-Specific Configuration

public void ConfigureTabuLynx(IServiceCollection services, IConfiguration configuration)
{
    var environment = configuration["Environment"];
    
    // Configure based on environment
    switch (environment?.ToLower())
    {
        case "development":
            services.Configure<TabuLynxOptions>(options =>
            {
                options.ConnectionString = "Provider=MSOLAP;Data Source=localhost:12345;";
            });
            break;
            
        case "production":
            services.Configure<TabuLynxOptions>(configuration.GetSection("TabuLynx"));
            break;
    }
    
    services.AddSingleton<IConnection, TabuLynxConnection>();
}

🔍 Advanced Usage

Custom Connection Implementation

public class CustomConnection : IConnection
{
    public string ConnectionString { get; set; } = "";
    public string TenantId { get; set; } = "";
    public string ClientId { get; set; } = "";
    public string ClientSecret { get; set; } = "";
    public string Scope { get; set; } = "";
    
    public CustomConnection(IConfiguration configuration)
    {
        // Custom configuration logic
        ConnectionString = configuration.GetConnectionString("TabuLynx") ?? "";
        // ... other custom initialization
    }
}

// Register custom implementation
services.AddSingleton<IConnection, CustomConnection>();

Configuration Validation

using System.ComponentModel.DataAnnotations;

// Custom validation for TabuLynxOptions
services.PostConfigure<TabuLynxOptions>(options =>
{
    if (string.IsNullOrWhiteSpace(options.ConnectionString))
    {
        throw new ValidationException("ConnectionString is required");
    }
    
    // Cloud scenarios require authentication details
    if (options.ConnectionString.Contains("powerbi://") && 
        (string.IsNullOrWhiteSpace(options.TenantId) || 
         string.IsNullOrWhiteSpace(options.ClientId)))
    {
        throw new ValidationException("Cloud connections require TenantId and ClientId");
    }
});

🛠️ Troubleshooting

Common Issues

Configuration Not Found: Ensure your appsettings.json has the correct TabuLynx section:

{
  "TabuLynx": {
    "ConnectionString": "your-connection-string"
  }
}

Validation Errors: Check that required configuration values are provided based on your target platform.

DI Registration Order: Register TabuLynx.Core services before other TabuLynx packages that depend on them.

🎯 Integration with Other TabuLynx Packages

TabuLynx.Core serves as the foundation for:

• TabuLynx.Query.Executor: Query execution against Analysis Services
• TabuLynx.Model.Extractor: Model metadata extraction
• TabuLynx.Discovery.PowerBI: Power BI instance discovery

Example complete setup:

services.Configure<TabuLynxOptions>(configuration.GetSection("TabuLynx"));
services.AddSingleton<IConnection, TabuLynxConnection>();           // Core
services.AddAdomdQueryExecutorForLocalPowerBI();                   // Query.Executor
services.AddDmvModelExtractor();                                   // Model.Extractor

🤝 Contributing

Contributions, issues, and feature requests are welcome! Please feel free to check the issues page.

📄 License

This project is licensed under the terms specified in the LICENSE file.