Skip to content

Azurite

Azurite is an open-source emulator for Azure Blob, Queue and Table storage that provides a local environment for developing and testing Azure Storage applications.

Add the following dependency to your project file:

NuGet
1
dotnet add package Testcontainers.Azurite

You can start an Azurite container instance from any .NET application. Here, we create different container instances and pass them to the base test class. This allows us to test different configurations.

1
2
3
4
5
6
7
8
[UsedImplicitly]
public sealed class AzuriteDefaultConfiguration : AzuriteContainerTest
{
    public AzuriteDefaultConfiguration()
        : base(new AzuriteBuilder(TestSession.GetImageFromDockerfile()).Build())
    {
    }
}

This example uses xUnit.net's IAsyncLifetime interface to manage the lifecycle of the container. The container is started in the InitializeAsync method before the test method runs, ensuring that the environment is ready for testing. After the test completes, the container is removed in the DisposeAsync method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
public async ValueTask InitializeAsync()
{
    await _azuriteContainer.StartAsync()
        .ConfigureAwait(false);
}

public async ValueTask DisposeAsync()
{
    await DisposeAsyncCore()
        .ConfigureAwait(false);

    GC.SuppressFinalize(this);
}

[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public async Task EstablishesBlobServiceConnection()
{
    // Given
    var options = new BlobClientOptions(BlobClientOptions.ServiceVersion.V2025_11_05);
    options.Transport = _transport;

    var client = new BlobServiceClient(_azuriteContainer.GetConnectionString(), options);

    // When
    var properties = await client.GetPropertiesAsync(TestContext.Current.CancellationToken)
        .ConfigureAwait(true);

    // Then
    Assert.False(HasError(properties));
    Assert.Equal(_scheme, new Uri(_azuriteContainer.GetBlobEndpoint()).Scheme);
    Assert.Equal(_azuriteContainer.GetConnectionString(), _azuriteContainer.GetConnectionString(ConnectionMode.Host));
}

[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public async Task EstablishesQueueServiceConnection()
{
    // Given
    var options = new QueueClientOptions(QueueClientOptions.ServiceVersion.V2025_11_05);
    options.Transport = _transport;

    var client = new QueueServiceClient(_azuriteContainer.GetConnectionString(), options);

    // When
    var properties = await client.GetPropertiesAsync(TestContext.Current.CancellationToken)
        .ConfigureAwait(true);

    // Then
    Assert.False(HasError(properties));
    Assert.Equal(_scheme, new Uri(_azuriteContainer.GetQueueEndpoint()).Scheme);
}

[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public async Task EstablishesTableServiceConnection()
{
    // Given
    var options = new TableClientOptions();
    options.Transport = _transport;

    var client = new TableServiceClient(_azuriteContainer.GetConnectionString(), options);

    // When
    var properties = await client.GetPropertiesAsync(TestContext.Current.CancellationToken)
        .ConfigureAwait(true);

    // Then
    Assert.False(HasError(properties));
    Assert.Equal(_scheme, new Uri(_azuriteContainer.GetTableEndpoint()).Scheme);
}

The test example uses the following NuGet dependencies:

1
2
3
4
5
6
7
<PackageReference Include="Microsoft.NET.Test.Sdk"/>
<PackageReference Include="coverlet.collector"/>
<PackageReference Include="xunit.runner.visualstudio"/>
<PackageReference Include="xunit.v3"/>
<PackageReference Include="Azure.Data.Tables"/>
<PackageReference Include="Azure.Storage.Blobs"/>
<PackageReference Include="Azure.Storage.Queues"/>

To execute the tests, use the command dotnet test from a terminal.

Tip

For the complete source code of this example and additional information, please refer to our test projects.

Access Azurite

Gets the Azurite connection string
1
string connectionString = _azuriteContainer.GetConnectionString();
Gets the Blob, Queue and Table endpoints
1
2
3
string blobEndpoint = _azuriteContainer.GetBlobEndpoint();
string queueEndpoint = _azuriteContainer.GetQueueEndpoint();
string tableEndpoint = _azuriteContainer.GetTableEndpoint();

Configure SSL

To enable HTTPS, use the following container builder method to configure Azurite with an SSL certificate and private key. The connection string and the Blob, Queue and Table endpoints then use the https scheme:

1
2
3
4
5
6
7
8
[UsedImplicitly]
public sealed class AzuriteSslConfiguration : AzuriteContainerTest
{
    public AzuriteSslConfiguration()
        : base(new AzuriteBuilder(TestSession.GetImageFromDockerfile()).WithSsl(CertificateFilePath, CertificateKeyFilePath).Build(), true)
    {
    }
}

Note

Please ensure that both the certificate and private key are provided in PEM format.

The client must trust the server certificate. In this example, the Azure client validates the SSL certificate against the CA certificate that signed it. The transport is assigned to the client options, as shown in the usage example:

1
2
3
4
5
6
7
8
9
_caCertificate = X509CertificateLoader.LoadCertificateFromFile(CaCertificateFilePath);

var httpMessageHandler = new SocketsHttpHandler();
httpMessageHandler.SslOptions.CertificateChainPolicy = new X509ChainPolicy();
httpMessageHandler.SslOptions.CertificateChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
httpMessageHandler.SslOptions.CertificateChainPolicy.CustomTrustStore.Add(_caCertificate);
httpMessageHandler.SslOptions.CertificateChainPolicy.RevocationMode = X509RevocationMode.NoCheck;

_transport = new HttpClientTransport(httpMessageHandler);

Enable in-memory persistence

By default, Azurite persists its data to disk. If your tests do not need the data after the container stops, use the following configuration to keep it in memory instead:

1
2
3
4
5
6
7
8
[UsedImplicitly]
public sealed class AzuriteInMemoryConfiguration : AzuriteContainerTest
{
    public AzuriteInMemoryConfiguration()
        : base(new AzuriteBuilder(TestSession.GetImageFromDockerfile()).WithInMemoryPersistence().Build())
    {
    }
}

The in-memory storage is limited to 50% of the total memory of the container by default. To set a different limit, pass the limit in megabytes to WithInMemoryPersistence.