AzLocal.Core 0.1.0-alpha.1

azlocal

Run a local Azure emulator for .NET development and automated tests. Work with blobs, test secrets, queues, and resource groups through the official Azure SDK clients, without an Azure subscription.

Packages

You need the .NET 10 SDK. The first planned testing release is 0.1.0-alpha.1. These commands work after that version is published.

Start the emulator

dotnet tool install --global azlocal --version 0.1.0-alpha.1
azlocal trust-cert
azlocal start
azlocal wait

The HTTPS endpoint is https://127.0.0.1:4566; Service Bus uses local AMQP on port 5672. Certificate trust depends on your operating system. Use azlocal status to check the host and azlocal stop to stop it.

Certificate setup

azlocal trust-cert runs dotnet dev-certs https --trust. Run it as the same user who starts the emulator and approve the trust prompt when requested. Verify with:

dotnet dev-certs https --check --trust

On Linux, run dotnet dev-certs https --trust --verbose and follow its trust-store instructions. Older certificates may not cover 127.0.0.1. A trust problem can cause wait to time out even when the host process is running. See the platform and CI HTTPS guide.

To change the HTTPS port, stop the host, run azlocal start --port 5001, and use azlocal wait --port 5001. Match that address in options.BaseUrl. The AMQP port is configured separately; see host configuration.

Connect your application

From your application project:

dotnet add package AzLocal.Client --version 0.1.0-alpha.1

Register clients in an ASP.NET Core application's Program.cs:

using AzLocal.Client;
using Azure.Storage.Blobs;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAzLocal(options =>
{
    options.BaseUrl = "https://127.0.0.1:4566";
    options.BlobAccountName = "myaccount";
    options.BlobContainerName = "uploads";
    options.KeyVaultName = "myvault";
    options.ServiceBusQueueName = "myqueue";
});
builder.Services.AddScoped<UploadService>();

var app = builder.Build();
app.MapPost("/uploads/{name}", async (
    string name, HttpRequest request, UploadService uploads,
    CancellationToken cancellationToken) =>
{
    await uploads.UploadAsync(name, request.Body, cancellationToken);
    return Results.Ok();
});
app.Run();

public sealed class UploadService(BlobContainerClient container)
{
    public async Task UploadAsync(
        string name, Stream content, CancellationToken cancellationToken)
    {
        await container.CreateIfNotExistsAsync(cancellationToken: cancellationToken);
        await container.GetBlobClient(name).UploadAsync(
            content, overwrite: true, cancellationToken: cancellationToken);
    }
}

SDK clients are singletons. Application services can be scoped or transient. The emulator must already be running; registration does not start the host.

Available services

These operations cover part of the Azure APIs. Managed identity returns test tokens. State can use memory, JSON snapshots, or SQLite. Old development blob data must be recreated after storage format changes.

Documentation and feedback

• Configuration, examples, and storage setup
• SDK compatibility and limitations
• Report an issue
• Release notes
• Setup troubleshooting and upgrades

azlocal is an independent project for local development and testing. It is not affiliated with Microsoft. Licensed under MIT.