[Getting Started] Add reference app specification

[svrnm]

Contributes to the effort to rework our getting started guides

[kaylareopelle]

Great start! Thank you!

[tiffany76]

Took a quick copyedit first pass. Thanks!

[svrnm]

Apologies for the delay! I took some time today to incorporate your reviews and expand on the details, please take a look!

[tiffany76]

One question, but otherwise LGTM.

[martincostello]

Is this a hard requirement (must implies to me it is)? I get the argument for standardisation, but this is likely not idiomatic for a number of programming languages/frameworks (it's not for .NET/C#).

[svrnm]

So the thinking about this, is that we can demonstrate much better that if you have a library you only leverage the API and not the SDK. How is it not idiomatic for C# to put a functionality like that into a separate file? I would assume it works similar to java that you would create a Class that provides that functionality as service?

[martincostello]

By not idiomatic I mean files called app and lib. This reads as if it's mandating the file names.

If I were to write a simple idiomatic .NET application today to do a simple rolldice endpoint, I could do it like this in a single Program.cs file:

using System.Globalization;

var builder = WebApplication.CreateBuilder(args);

// Configure telemetry here, then...

var app = builder.Build();

app.MapGet("/rolldice/{player?}", (string? player, ILogger<Program> logger) =>
{
    var result = Random.Shared.Next(1, 7);

    if (string.IsNullOrEmpty(player))
    {
        logger.LogInformation("Anonymous player is rolling the dice: {result}", result);
    }
    else
    {
        logger.LogInformation("{player} is rolling the dice: {result}", player, result);
    }

    return result.ToString(CultureInfo.InvariantCulture);
});

app.Run();

This is essentially how we implemented rolldice in the .NET example in our grafana/docker-otel-lgtm repository.

If you still wanted the additional structure, then to be mostly-idiomatic you'd have something like this in .NET 6+:

- <App Directory>
|
|--> Program.cs - The entry-point to the application, needs to call and setup `App`.
|--> App.cs - The `App` class that sets up the webservice and defines the endpoints.
|--> Lib.cs - A weirdly-named (IMHO) class that provides the logic of the endpoint to roll the dice.
|--> Project.csproj - The project definition file.

With .NET 10, I could remove the need for the project file (Announcing dotnet run app.cs – A simpler way to start with C# and .NET 10) and at least change the name to app.cs, but I would still find lib.cs strange to find in a .NET project.

As the document is written right now, it seems overly-prescriptive to me. Rather, it would just talk about separating the HTTP handler code from the "business logic" as appropriate for the programming language/framework in question, rather than directing specific file names.

[svrnm]

It does not have to be "App.cs" or "Lib.cs" it can be something more meaningful in the context of your language.

The key point is that we separate the "library" that provides the dice rolling functionality from the "application" that consumes it. The business logic is super simple, that makes it awkward in most/all languages ... but it's here to demonstrate some concepts (separation of API & SDK, etc.)

So, if it makes more sense to call it "DiceRollService.cs" or "RollerMiddleware.cs" or whatever makes sense, and if "App.cs" is not necessary and it's functionality can be offloaded to "Program.cs" that's totally fine

[martincostello]

Cool, that basically fits with what I was getting at. I think the text as-written sounds like it's suggesting the files must be called that, rather than explaining what's wanted at a higher-level architectural/layout level.