This document provides a step-by-step guide for monitoring the Vogen project in a production environment. It covers essential logging practices and diagnostic reporting mechanisms implemented within the codebase.

Logging Configuration

Monitoring the application starts with setting up a logging system. The Vogen project uses the default .NET logging framework. To enable logging, follow the steps below:

1. Add NuGet Packages: Include the necessary NuGet package references in your project:

   dotnet add package Microsoft.Extensions.Logging
   dotnet add package Microsoft.Extensions.Logging.Console
   

2. Configure Logger: Set up the logging configuration in your application:

   using Microsoft.Extensions.Logging;
   
   using var loggerFactory = LoggerFactory.Create(builder =>
   {
       builder.AddConsole();
   });
   
   ILogger logger = loggerFactory.CreateLogger<YourClassName>(); // Replace with your class name
   

3. Log Messages: Utilize the logger to log important messages throughout the application:

   logger.LogInformation("Application starting...");
   

Diagnostic Reporting

Vogen monitors potential issues during compilation via diagnostics. This section outlines how diagnostics are reported during the build process.

Report User Constructors Errors

The following function checks for user-defined constructors in value objects and reports them as diagnostics:

private static bool ReportErrorsForAnyUserConstructors(SourceProductionContext context, INamedTypeSymbol voSymbolInformation)
{
    bool reported = false;
    ImmutableArray allConstructors = voSymbolInformation.Constructors;

    foreach (IMethodSymbol? eachConstructor in allConstructors)
    {
        if (eachConstructor.IsImplicitlyDeclared) continue;
        context.ReportDiagnostic(DiagnosticsCatalogue.CannotHaveUserConstructors(eachConstructor));
        reported = true;
    }

    return reported;
}

Configuration Building

When building configurations from attributes, errors may occur. These are logged as diagnostics:

AttributeData voAttribute = target.DataForAttributes[0];

var localBuildResult = BuildConfigurationFromAttributes.TryBuildFromValueObjectAttribute(voAttribute);
foreach (var diagnostic in localBuildResult.Diagnostics)
{
    context.ReportDiagnostic(diagnostic);
}

VogenConfiguration? localConfig = localBuildResult.ResultingConfiguration;

if (localConfig is null)
{
    return null;
}

Capture and Report Global Configuration Errors

Errors from global configuration builds are also reported:

VogenConfigurationBuildResult buildResult = globalConfigBuildResult.IsDefaultOrEmpty
    ? VogenConfigurationBuildResult.Null
    : globalConfigBuildResult.ElementAt(0);
    
foreach (var diagnostic in buildResult.Diagnostics)
{
    spc.ReportDiagnostic(diagnostic);
}

VogenConfiguration? globalConfig = buildResult.ResultingConfiguration;
internalDiags.RecordGlobalConfig(globalConfig);

Monitoring Execution

During execution, it’s crucial to monitor how the application handles diagnostics, especially under various conditions. The following snippet showcases how to structure tests for these functionalities:

public class GenerationPermutationTests
{
    private readonly ITestOutputHelper _logger;

    public GenerationPermutationTests(ITestOutputHelper logger) => _logger = logger;

    [Fact]
    public Task It_does_not_write_diagnostics_if___ProduceDiagnostics_class_is_not_present_anywhere()
    {
        return RunTest(
            """
            using System;
            using Vogen;

            namespace MyNamespace;

            class TestClass
            {
                // Your test implementation here.
            }
            """);
    }
}

Conclusion

Effective monitoring of the Vogen project in production involves proper logging and reporting of diagnostics. By setting up the logging framework and implementing rigorous diagnostic reporting mechanisms, developers can ensure that potential issues are captured and addressed swiftly. The code examples provided serve as a guide for integrating these practices into your production environment.

This documentation is based on the insights from Vogen’s source code and relevant files.