Eagerly load services

[slang25]

📝 Description

This PR adds the ability to eagerly load services in localstack.
Related Issue(s):

• Closes Feature Request: Eager loading services #7

🔄 Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🧹 Code cleanup/refactoring
• ⚡ Performance improvement
• 🧪 Test improvements

🎯 Aspire Compatibility

• Compatible with .NET Aspire 9.x
• Supports both .NET 8.0 and .NET 9.0
• Follows Aspire.Hosting.AWS patterns
• Works with existing AWS integrations

🧪 Testing

How has this been tested?

• Unit tests added/updated
• Integration tests added/updated
• Manual testing with playground examples
• Tested with LocalStack container
• Tested across multiple .NET versions
• Tested auto-configure (UseLocalStack())
• Tested manual configuration (WithReference())

Test Environment:

• LocalStack Version:
• .NET Aspire Version: 9.4.0
• .NET Versions Tested: 9.0.302
• Operating Systems: macOS

📚 Documentation

• Code is self-documenting with clear naming
• XML documentation comments added/updated
• README.md updated (if needed)
• Playground examples updated (if needed)
• Breaking changes documented

✅ Code Quality Checklist

• Code follows project coding standards
• No new analyzer warnings introduced
• All tests pass locally
• No merge conflicts
• Branch is up to date with target branch
• Commit messages follow Conventional Commits

🔍 Additional Notes

Breaking Changes:
If this is a breaking change, describe the impact and migration path for users.

Performance Impact:
Describe any performance implications of these changes.

Dependencies:
List any new dependencies or version changes.

🎯 Reviewer Focus Areas

Please pay special attention to:

• Security implications
• Performance impact
• Breaking changes
• Test coverage
• Documentation completeness
• Aspire integration patterns
• LocalStack compatibility

📸 Screenshots/Examples

If applicable, add screenshots or code examples showing the changes in action.

// Example usage in AppHost
var builder = DistributedApplication.CreateBuilder(args);

var localstack = builder.AddLocalStack(configureContainer: container =>
        {
            container.EagerLoadedServices = [AwsService.Sqs];
        });

builder.Build().Run();

---

By submitting this pull request, I confirm that:

• I have read and agree to the project's Code of Conduct
• I understand that this contribution may be subject to the .NET Foundation CLA
• My contribution is licensed under the same terms as the project (MIT License)

[slang25]

Unrelated change, just spotted the doc comments refer to an option that doesn't exist

[slang25]

Help me here, I think I should delete most of this method and use what you already have with LocalStackConnectionStringAvailableCallback, but not sure the right way to reuse that here.

[slang25]

The changes in this file is to allow inline creation of DistributedApplicationTestingBuilder, without a separate AppHost project.

[Blind-Striker]

In this PR (#9), I added some new useful helpers to the Aspire.Hosting.LocalStack.Integration.Tests project and also reorganized the Lambda playground tests. Thought this might be helpful for you as well.

[slang25]

I've decided that this is simple enough to not warrant a "playground" project and just create these builders inline

[Blind-Striker]

Hey @slang25, thanks for the PR! I'm a bit swamped this week, so I likely won't be able to take a look for another 2–3 days. I'll review it and get back to your questions as soon as I can. Really appreciate your contribution 🙏

[Blind-Striker]

Hey @slang25 ,

First off, thanks again for the effort 🙏 The eager-loading capability is genuinely useful. I went through your PR in detail and also poked around Aspire’s health-check docs a bit: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/health-checks

Based on that, I’ve got a few architectural suggestions that I think will make this even cleaner and easier to evolve:

• Centralize lazy/eager logic in LocalStackHealthCheck. Since we already have a LocalStackHealthCheck class, let’s keep the eager vs. lazy concerns inside that class, independent from the containerOptions.EagerLoadedServices.Count == 0 toggle. It’s the same endpoint we’re hitting either way; the difference is just which specific services we probe under eager mode. This keeps the behavior in one place.
• Instead of creating HttpClient manually, we can register a named client via Aspire’s DI and utilize HttpClientFactory.
• Probably we don't need to anything under LocalStackConnectionStringAvailableCallback. From my local testing, the HealthCheckRegistration factory is invoked once endpoints are allocated, so we probably don’t need to do anything special in LocalStackConnectionStringAvailableCallback.

I drafted something like this:

    private static IResourceBuilder<LocalStackResource> ConfigureHealthCheck(
        IDistributedApplicationBuilder builder,
        IResourceBuilder<LocalStackResource> resourceBuilder,
        string[]? serviceNames)
    {
        var healthCheckName = $"{resourceBuilder.Resource.Name}_health";
        var endpoint = resourceBuilder.Resource.GetEndpoint(LocalStackResource.PrimaryEndpointName);

        builder.Services.AddHealthChecks().Add(new HealthCheckRegistration(
            healthCheckName,
            sp =>
            {
                // At this point, the endpoint should be allocated
                if (!endpoint.IsAllocated)
                {
 // I'm not super sure about throwing an exception here
                    throw new InvalidOperationException($"LocalStack endpoint '{LocalStackResource.PrimaryEndpointName}' not yet allocated.");
                }
                var httpClientFactory = sp.GetRequiredService<IHttpClientFactory>();
                var healthCheckUrl = $"{endpoint.Url}/_localstack/health";

                // The health check decides internally whether to do lazy or eager checking
                return new LocalStackHealthCheck(
                    httpClientFactory,
                    healthCheckUrl,
                    serviceNames);
            },
            failureStatus: null,
           tags: new[] { "localstack", /* maybe "eager"/"lazy" */ }));

        // Associate the health check with the resource
        return resourceBuilder.WithHealthCheck(healthCheckName);
    }

[Blind-Striker]

Let’s avoid instantiating HttpClient directly here. Instead, inject IHttpClientFactory via the constructor.

See my general comment: #8 (comment)

[Blind-Striker]

Consider a fail-fast approach here. We can invert the condition and return early to improve readability.

[Blind-Striker]

Somewhere after IsSuccessStatusCode, we could handle it like this:

// LAZY LOADING MODE: No specific services to check
if (services is null || services.Length == 0) 
{
    return HealthCheckResult.Healthy("LocalStack is healthy");
}

That way, the lazy-loading case is explicitly covered.

Alternatively, instead of relying on the services array, it might be more robust to pass an explicit Lazy/Eager mode flag into the LocalStackHealthCheck class, so the behavior is intentional and less dependent on state.

[Blind-Striker]

Let’s drop this block altogether, since both lazy and eager cases will be handled directly inside LocalStackHealthCheck

[Blind-Striker]

Somewhere around here we can register our HttpClient:

builder.Services.AddHttpClient("localstack");

It might be cleaner to avoid using a magic string maybe move "localstack" into a constant. I’m not entirely sure which approach is better here, but leaning toward a constant for clarity.

[Blind-Striker]

Just nitpicking here. It would also be useful to handle cases like:

catch (HttpRequestException ex)
{
    return HealthCheckResult.Unhealthy("LocalStack health check failed: network error", ex);
}
catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
{
    return HealthCheckResult.Unhealthy("LocalStack health check timed out", ex);
}

This way we can capture network errors and timeouts explicitly, making the health check more easier to diagnose.

[Blind-Striker]

See my general comment: #8 (comment)

[Blind-Striker]

In this PR (#9), I added some new useful helpers to the Aspire.Hosting.LocalStack.Integration.Tests project and also reorganized the Lambda playground tests. Thought this might be helpful for you as well.

[Blind-Striker]

I don’t have a definitive solution for this right now, but I do think we should document this feature somewhere. Not sure if the README is the best place for it. Open to suggestions, though!

[Blind-Striker]

I think setting the env variables here is reasonable. That said, there’s a subtle edge case:

Inside AddLocalStack we already have:

// Add any additional environment variables
foreach (var (key, value) in containerOptions.AdditionalEnvironmentVariables)
{
    resourceBuilder = resourceBuilder.WithEnvironment(key, value);
}

If the same env variables are passed in both places, I’m not sure which one would win, probably the ones added last, but it’s not obvious.

I don’t have a perfect solution right now, but a couple of future options could be:

• Dropping AdditionalEnvironmentVariables entirely and consolidating everything into containerOptions.
• Adding a validation step to detect overlapping variables and warn/fail early.

The first approach might be too restrictive, so I’m leaning toward the validation idea as a safer middle ground.

Either way, I don’t think we need to solve this in this PR, I’m not expecting that. I just wanted to share this thought for future consideration.

[Blind-Striker]

Hey @slang25 👋

Just wanted to check in on this PR, I really appreciate the effort you’ve already put into it 🙌

I added some review comments a few days ago, but I completely understand if you have other priorities at the moment. I’m planning to cut a new release soon, and since this is a great addition, I’d love to include it.

If you’re short on time, I can take it from here and finish up the remaining changes based on your implementation. You’ve already done the heavy lifting. Of course, I’ll keep your commits and full credit.

No pressure at all, though. Just let me know what works best for you! 😊