Providers

FlexBase provides unified abstractions for external service providers, enabling you to switch implementations without changing application code. All providers follow consistent patterns for configuration, usage, and error handling.

Available Providers

Communication Providers

Provider Type	Description	Use Cases
AI Providers	LLM chat, embeddings, streaming	RAG, semantic search, content generation
Email Providers	Transactional and templated emails	Notifications, password resets, receipts
Message Providers	SMS, push, chat platforms	Verification codes, alerts, notifications

AI Providers

Connect to multiple AI/LLM services with one interface:

Provider	Best For	Features
Azure OpenAI	Enterprise, compliance	GPT-4o, embeddings, SLA
OpenAI	Latest models	GPT-4o, o1, latest features
Anthropic Claude	Long context, analysis	200K context, reasoning
Google Gemini	Multimodal	Text, images, competitive pricing
Ollama	Local/offline	Privacy, no API costs

// Works with ANY AI provider
public class ChatService
{
    private readonly IFlexAIProvider _aiProvider;  // Could be OpenAI, Claude, Ollama, etc.
    
    public async Task<string> AskAsync(string question)
    {
        return await _aiProvider.ChatAsync(question);
    }
}

Email Providers

Send emails through multiple services:

Provider	Best For	Features
Console	Development	No real emails, console output
SMTP	Standard servers	Office 365, Gmail, custom
SMTP + Templates	Branded emails	Built-in templates, variables
SendGrid	Transactional	Delivery tracking, analytics

// Works with ANY email provider
public class NotificationService
{
    private readonly IFlexEmailProvider _emailProvider;
    
    public async Task SendWelcomeAsync(string email, string name)
    {
        await _emailProvider.SendTemplatedAsync(
            to: email,
            templateId: "welcome",
            templateData: new Dictionary<string, object>
            {
                ["userName"] = name,
                ["loginUrl"] = "https://app.example.com"
            }
        );
    }
}

Message Providers

Send messages across multiple channels:

Channel	Use Cases	Providers
SMS	Verification codes, alerts	Twilio, AWS SNS
Push	Mobile notifications	Firebase, AWS SNS
WhatsApp	Customer support	Twilio
Slack/Teams	Internal alerts	Native APIs
Console	Development	Testing

// Multi-channel messaging
public class AlertService
{
    private readonly IFlexTextMessageProvider _messageProvider;

	public AlertService(IFlexTextMessageProvider messageProvider)
		=> _messageProvider = messageProvider;
    
    public async Task SendAlertAsync(User user, string message)
    {
        // SMS
        if (!string.IsNullOrEmpty(user.PhoneNumber))
        {
            await _messageProvider.SendSmsAsync(user.PhoneNumber, message);
        }
        
        // Push notification
        if (!string.IsNullOrEmpty(user.DeviceToken))
        {
            await _messageProvider.SendPushAsync(
                user.DeviceToken,
                "Alert",
                message
            );
        }
    }
}

Common Patterns

Automatic Setup via Flex Studio

Providers are automatically added to your application through Flex Studio. When you add a provider:

1. Provider files are created in Infrastructure/Providers/{YourApplication}.DataStoreProviders/{Category}/{Provider}/

2. NuGet package is referenced automatically

3. Default configuration is added to Application/EndPoints/{YourApplication}.EndPoint.CommonConfigs/AppSettings/{Category}/{Provider}.json

4. README documentation is included in the provider folder

You can find all provider files, configuration examples, and documentation in the generated infrastructure folder.

Configuration

Providers use the IOptions pattern. Configuration files are automatically created when you add providers via Flex Studio:

{
    "FlexBase": {
      "AI": {
        "OpenAI": {
          "ApiKey": "<store-in-secrets>",
          "DefaultChatModel": "gpt-4o"
        }
      },
      "Providers": {
        "Email": {
          "Smtp": {
            "Host": "smtp.office365.com",
            "Port": 587,
            "Username": "[email protected]",
            "Password": "<store-in-secrets>"
          }
        },
        "Message": {
          "Console": {
            "DefaultChannel": "Sms"
          }
        }
      }
    }
}

Configuration files are located at:

• Application/EndPoints/{YourApplication}.EndPoint.CommonConfigs/AppSettings/AI/{Provider}.json

• Application/EndPoints/{YourApplication}.EndPoint.CommonConfigs/AppSettings/Email/{Provider}.json

• Application/EndPoints/{YourApplication}.EndPoint.CommonConfigs/AppSettings/Message/{Provider}.json

Dependency Injection

After adding providers via Flex Studio, register only the provider in Program.cs (the generated queries/handlers/plugins are auto-wired by Flex):

// AI provider
builder.Services.AddFlexOpenAI(builder.Configuration);

// Email provider
builder.Services.AddFlexSmtpEmailProvider(builder.Configuration);

// Message provider
builder.Services.AddFlexConsoleMessageProvider(builder.Configuration);

Multiple Providers

Use keyed services (.NET 8+) for multiple providers:

// Register multiple AI providers
builder.Services.AddKeyedSingleton<IFlexAIProvider>("openai", (sp, _) =>
    new FlexOpenAIProvider(Configuration["OpenAI:ApiKey"]!));

builder.Services.AddKeyedSingleton<IFlexAIProvider>("local", (sp, _) =>
    new OllamaProvider());

// Use in service
public class AIService
{
    private readonly IFlexAIProvider _cloud;
    private readonly IFlexAIProvider _local;

    public AIService(
        [FromKeyedServices("openai")] IFlexAIProvider cloud,
        [FromKeyedServices("local")] IFlexAIProvider local)
    {
        _cloud = cloud;
        _local = local;
    }

    public async Task<string> ProcessAsync(string input, bool useLocal = false)
    {
        var provider = useLocal ? _local : _cloud;
        return await provider.ChatAsync(input);
    }
}

Provider-Agnostic Benefits

1. Easy Testing

Use console/mock providers during development:

// Development
builder.Services.AddFlexConsoleEmailProvider();
builder.Services.AddFlexConsoleMessageProvider();

// Production
builder.Services.AddFlexSmtpEmailProvider();
builder.Services.AddTwilioMessageProvider();

2. Cost Optimization

Switch providers based on cost or features:

public class CostOptimizedService
{
    private readonly IFlexAIProvider _cloudProvider;   // GPT-4o for complex
    private readonly IFlexAIProvider _localProvider;   // Ollama for simple

    public async Task<string> ProcessAsync(string input)
    {
        if (IsComplexQuery(input))
        {
            return await _cloudProvider.ChatAsync(input);
        }
        else
        {
            return await _localProvider.ChatAsync(input);  // Free!
        }
    }
}

3. Vendor Independence

Avoid vendor lock-in - switch providers with configuration:

// Application code stays the same
public class MyService
{
    private readonly IFlexAIProvider _ai;
    private readonly IFlexEmailProvider _email;
    
    // Works with ANY provider implementation
}

Error Handling

All providers follow consistent error patterns:

public async Task<bool> SendWithErrorHandlingAsync()
{
    try
    {
        var result = await _provider.SendAsync(message);
        
        if (!result.IsSuccess)
        {
            _logger.LogError("Operation failed: {Error}", result.ErrorMessage);
            
            // Handle specific error codes
            switch (result.ErrorCode)
            {
                case "RATE_LIMITED":
                    await Task.Delay(TimeSpan.FromSeconds(5));
                    return await SendWithErrorHandlingAsync();  // Retry
                
                case "INVALID_INPUT":
                    return false;  // Don't retry
                
                default:
                    throw new Exception(result.ErrorMessage);
            }
        }
        
        return true;
    }
    catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.Unauthorized)
    {
        _logger.LogError("Invalid credentials");
        throw;
    }
}

Best Practices

1. Use Console Providers in Development

if (builder.Environment.IsDevelopment())
{
    builder.Services.AddFlexConsoleEmailProvider();
    builder.Services.AddFlexConsoleMessageProvider();
    builder.Services.AddSingleton<IFlexAIProvider>(new OllamaProvider());
}
else
{
    builder.Services.AddFlexSmtpEmailProvider(/* production config */);
    builder.Services.AddTwilioMessageProvider(/* production config */);
    builder.Services.AddSingleton<IFlexAIProvider>(new FlexOpenAIProvider(/* production config */));
}

2. Validate Configuration on Startup

// In Program.cs after building
using var scope = app.Services.CreateScope();

var aiProvider = scope.ServiceProvider.GetRequiredService<IFlexAIProvider>();
if (!await aiProvider.TestConnectionAsync())
{
    throw new InvalidOperationException("AI provider not configured correctly");
}

var emailProvider = scope.ServiceProvider.GetRequiredService<IFlexEmailProvider>();
if (!await emailProvider.TestConnectionAsync())
{
    throw new InvalidOperationException("Email provider not configured correctly");
}

3. Implement Retry Logic

public async Task<T> ExecuteWithRetryAsync<T>(
    Func<Task<T>> operation,
    int maxRetries = 3)
{
    for (int attempt = 1; attempt <= maxRetries; attempt++)
    {
        try
        {
            return await operation();
        }
        catch (Exception ex) when (attempt < maxRetries)
        {
            _logger.LogWarning(
                "Attempt {Attempt}/{Max} failed: {Error}",
                attempt, maxRetries, ex.Message
            );
            
            await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
        }
    }
    
    throw new InvalidOperationException("All retry attempts failed");
}

4. Monitor and Log

public async Task<string> MonitoredChatAsync(string message)
{
    var stopwatch = Stopwatch.StartNew();
    
    try
    {
        var response = await _aiProvider.ChatAsync(message);
        
        _logger.LogInformation(
            "AI chat completed in {ElapsedMs}ms. Provider: {Provider}, Tokens: {Tokens}",
            stopwatch.ElapsedMilliseconds,
            _aiProvider.Provider,
            response.Usage?.TotalTokens
        );
        
        return response.Message.Content;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "AI chat failed after {ElapsedMs}ms", stopwatch.ElapsedMilliseconds);
        throw;
    }
}

Integration Examples

AI + Vector Store (RAG)

public class RAGService
{
    private readonly IFlexAIProvider _aiProvider;
    private readonly IFlexVectorStore _vectorStore;

    public async Task<string> AskAsync(string question)
    {
        // 1. Generate embedding
        var queryEmbedding = await _aiProvider.EmbedAsync(question);

        // 2. Search vector store
        var results = await _vectorStore.SearchAsync(queryEmbedding, topK: 5);

        // 3. Build context
        var context = string.Join("\n\n", results.Select(r => r.Content));

        // 4. Get AI response
        return await _aiProvider.ChatAsync($"Context: {context}\n\nQuestion: {question}");
    }
}

Email + Message (Multi-Channel Notifications)

public class NotificationService
{
    private readonly IFlexEmailProvider _emailProvider;
    private readonly IFlexTextMessageProvider _messageProvider;

    public NotificationService(IFlexEmailProvider emailProvider, IFlexTextMessageProvider messageProvider)
    {
        _emailProvider = emailProvider;
        _messageProvider = messageProvider;
    }

    public async Task NotifyUserAsync(User user, string message)
    {
        var tasks = new List<Task>();

        // Email
        if (!string.IsNullOrEmpty(user.Email))
        {
            tasks.Add(_emailProvider.SendAsync(user.Email, "Notification", message));
        }

        // SMS
        if (!string.IsNullOrEmpty(user.PhoneNumber))
        {
            tasks.Add(_messageProvider.SendSmsAsync(user.PhoneNumber, message));
        }

        // Push
        if (!string.IsNullOrEmpty(user.DeviceToken))
        {
            tasks.Add(_messageProvider.SendPushAsync(user.DeviceToken, "Notification", message));
        }

        await Task.WhenAll(tasks);
    }
}

Advanced Usage Examples

AI Providers

AI providers enable seamless integration with various LLM services. Below is an example of using an AI provider for generating responses:

public class AIResponseService
{
    private readonly IFlexAIProvider _aiProvider;

    public AIResponseService(IFlexAIProvider aiProvider)
    {
        _aiProvider = aiProvider;
    }

    public async Task<string> GenerateResponseAsync(string prompt)
    {
        return await _aiProvider.ChatAsync(prompt);
    }
}

Email Providers

Email providers support sending templated and transactional emails. Below is an example:

public class EmailNotificationService
{
    private readonly IFlexEmailProvider _emailProvider;

    public EmailNotificationService(IFlexEmailProvider emailProvider)
    {
        _emailProvider = emailProvider;
    }

    public async Task SendPasswordResetAsync(string email, string resetLink)
    {
        await _emailProvider.SendTemplatedAsync(
            to: email,
            templateId: "password_reset",
            templateData: new Dictionary<string, object>
            {
                ["resetLink"] = resetLink
            }
        );
    }
}

Message Providers

Message providers allow sending SMS, push notifications, and more. Below is an example:

public class SmsService
{
    private readonly IFlexTextMessageProvider _messageProvider;

    public SmsService(IFlexTextMessageProvider messageProvider)
    {
        _messageProvider = messageProvider;
    }

    public async Task SendVerificationCodeAsync(string phoneNumber, string code)
    {
        await _messageProvider.SendAsync(new FlexTextMessage
        {
            Channel = FlexMessageChannel.Sms,
			Recipients = new List<string> { phoneNumber },
            Content = $"Your verification code is {code}."
        });
    }
}

See Also

• Data Stores - Vector, search, document stores

• Relational Databases - EF Core and Dapper

• AI Providers Details - Complete AI provider documentation

• Email Providers Details - Complete email provider documentation

• Message Providers Details - Complete message provider documentation