Rpic.Web.Extensions 0.2.0

Web Extensions - Retail Package Integration Concept (RPIC)

Introduction

The package is designed to be used in conjunction with the Retail Package Integration Concept (RPIC) and provides a set of utility classes and methods to simplify the integration of Retail Packages into .NET Web Applications and Web APIs.

Features include:

• Azure App Configration: Provides a simple way to access configuration settings stored in Azure App Configuration.
• Application Configuration: Provides a simple way to access configuration settings stored in appSettings.json.
• Logging: Provides a simple way to log messages to the console and Application Insights.
• Telemetry: Provides a simple way to log telemetry to Application Insights.
• Logging Middleware: Provides a simple way to log requests and responses to the console and Application Insights.
• Exception Handling Middleware: Provides a simple way to log exceptions to the console and Application Insights.
• JSON Serialization: Provides a simple way to serialize and deserialize JSON data.

Installation

Install the package from NuGet:

dotnet add package Rpic.Web.Extensions

Example Usage

The following example demonstrates how to use the extensions in a .NET Web API project.

using Rpic.Web.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register services with the dependency injection container
builder
    .ConfigureJson() // Configure JSON serialization    
    .AddConfigSection<ServiceConfiguration>("Service") // Add the service configuration
    .Services
        .AddLogger<Program>() // Configure logging
        .AddSwagger("rpic.picklist.v1.yaml") // Required for OpenAPI
        .ConfigureApplicationInsights() // Configure Application Insights
        .AddStoreInformationService() // Configure the store 
        //
        // Add further dependency injection for custom services here
        //
        .AddNewtonsoftJson(options => // Serialize enums as strings
        {
            options.SerializerSettings.Converters.Add(new Newtonsoft.Json.Converters.StringEnumConverter());
        });

var app = builder.Build();

// Configure the application
app
    .ConfigureSwagger() // Configure Swagger UI
    .HandleExceptions<ServiceException>( //Handle exceptions
        async (exception, context) =>
        {
            await exception.HandleException(context);
        }
    )
    .MapControllers();  // Configure routes for classes inheriting from ControllerBase in the /Controllers folder

app.Run();

To get the Swagger to generate from the XML comments and the OpenAPI specification, add the following to the .csproj file:

<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <GenerateDocumentationFile>true</GenerateDocumentationFile>
    </PropertyGroup>
    <Target Name="CopyOpenApiFiles" AfterTargets="Build">
        <Copy SourceFiles="..\..\..\..\api\rpic.picklist.v1.yaml" DestinationFolder="$(OutputPath)" />
    </Target>
</Project>

Configuration

If you are using Azure App Configuration then you will need to add the following configuration to your appsettings.json file:

{
  "AzureAppConfig": {
    "Endpoint": "Endpoint=https://configname.azconfig.io;Id=MYID;Secret=MYSECRET",
    "Franchisee": "Client1",
    "Region": "Region1",
    "Section": "MFT",
    "EnableFeatureFlags": true,
    "EnableRefreshCallback": true,
    "CacheExpiration": 10
    }
}

Details

• Endpoint: The Azure App Configuration endpoint. Can either be a URL or a connection string. If a URL is used, then authentication will use the managed identity of the Azure Container App Service.
• Franchisee: The Franchisee name. Used to segment the configuration settings between multiple Franchisee Azure subscriptions.
• Region: The Region name. Used to segment the configuration settings between multiple Regions.
• Section: The Section name. Used to segment the configuration settings between multiple services.
• EnableFeatureFlags: Enable or disable the feature flags.
• EnableRefreshCallback: Enable or disable the refresh callback. This will cause Azure App Configuration to call the service and force a configuration refresh should the configuration settings change.
• CacheExpiration: The cache expiration time in seconds.

Function Documentation

AddConfigSection<T>

public static WebApplicationBuilder AddConfigSection<T>(
    this WebApplicationBuilder builder,
    string sectionName) where T : class

Parameters

• builder: The WebApplicationBuilder object.
• sectionName: The name of the configuration section.

Returns

• WebApplicationBuilder: The updated WebApplicationBuilder object.

GetExceptionMessage

public static string GetExceptionMessage(this HttpStatusCode status, string objectName)

Parameters

• status: The status code.
• objectName: The name of the object type.

Returns

• string: The exception message based on the status code.

HandleExceptions<T>

public static WebApplication HandleExceptions<T>(this WebApplication app, Func<T, HttpContext, Task>? typeHandler = null)

Parameters

• app: The web application that raised the exception.
• typeHandler: Optional handler for specific exception type.

Returns

• WebApplication: The app for method chaining.

ToJson

public static string ToJson(this object obj)

Parameters

• obj: The object reference.

Returns

• string: The object as a JSON string.

ConfigureJson

public static WebApplicationBuilder ConfigureJson(this WebApplicationBuilder builder)

Parameters

• builder: The web application builder.

Returns

• WebApplicationBuilder: The updated WebApplicationBuilder object.

AddLogger<T>

public static IServiceCollection AddLogger<T>(this IServiceCollection services)

Parameters

• services: The IServiceCollection to add the services to.

Returns

• IServiceCollection: The modified IServiceCollection.

ConfigureApplicationInsights

public static IServiceCollection ConfigureApplicationInsights(this IServiceCollection services)

Parameters

• services: The IServiceCollection to add the services to.

Returns

• IServiceCollection: The modified IServiceCollection.

ConfigureSwagger

public static WebApplication ConfigureSwagger(this WebApplication app)

Parameters

• app: The WebApplication to configure Swagger for.

Returns

• WebApplication: The configured WebApplication.

AddSwagger

public static IServiceCollection AddSwagger(this IServiceCollection services, string filePath)

Parameters

• services: The services collection used to register Swagger.
• filePath: The relative path to the OpenAPI specification.

Returns

• IServiceCollection: The modified service collection.

AddSwagger

public static IServiceCollection AddSwagger(this IServiceCollection services, OpenApiInfo? info = null)

Parameters

• services: The IServiceCollection to add the Swagger configuration to.
• info: The OpenApiInfo to use for the Swagger documentation.

Returns

• IServiceCollection: The modified IServiceCollection.