Quickstart: Azure confidential ledger client library for .NET

Article
01/30/2024

Get started with the Azure confidential ledger client library for .NET. Azure confidential ledger is a new and highly secure service for managing sensitive data records. Based on a permissioned blockchain model, Azure confidential ledger offers unique data integrity advantages. These include immutability, making the ledger append-only, and tamper proofing, to ensure all records are kept intact.

In this quickstart, you learn how to create entries in an Azure confidential ledger using the .NET client library

Azure confidential ledger client library resources:

API reference documentation | Library source code | Package (NuGet)

Prerequisites

An Azure subscription - create one for free
.NET Core 3.1 SDK or later
Azure CLI

You also need a running confidential ledger, and a registered user with the Administrator privileges. You can create a confidential ledger (and an administrator) using the Azure portal, the Azure CLI, or Azure PowerShell.

Setup

Create new .NET console app

In a command shell, run the following command to create a project named acl-app:
```
dotnet new console --name acl-app
```
Change to the newly created acl-app directory, and run the following command to build the project:
```
dotnet build
```
The build output should contain no warnings or errors.
```
Build succeeded.
 0 Warning(s)
 0 Error(s)
```

Install the package

Install the Confidential Ledger client library for .NET with [NuGet][client_nuget_package]:

dotnet add package Azure.Security.ConfidentialLedger --version 1.0.0

For this quickstart, you also need to install the Azure SDK client library for Azure Identity:

dotnet add package Azure.Identity

Object model

The Azure confidential ledger client library for .NET allows you to create an immutable ledger entry in the service. The Code examples section shows how to create a write to the ledger and retrieve the transaction ID.

Code examples

Add directives

Add the following directives to the top of Program.cs:

using System;
using Azure.Core;
using Azure.Identity;
using Azure.Security.ConfidentialLedger;
using Azure.Security.ConfidentialLedger.Certificate;

Authenticate and create a client

In this quickstart, logged in user is used to authenticate to Azure confidential ledger, which is preferred method for local development. The name of your confidential ledger is expanded to the key vault URI, in the format "https://<your-confidential-ledger-name>.confidential-ledger.azure.com". This example is using 'DefaultAzureCredential()' class from Azure Identity Library, which allows to use the same code across different environments with different options to provide identity.

credential = DefaultAzureCredential()

Write to the confidential ledger

You can now write to the confidential ledger with the PostLedgerEntry method.

Operation postOperation = ledgerClient.PostLedgerEntry(
    waitUntil: WaitUntil.Completed,
    RequestContent.Create(
        new { contents = "Hello world!" }));

Get transaction ID

The PostLedgerEntry method returns an object that contains the transaction of the entry you just wrote to the confidential ledger. To get the transaction ID, access the "Id" value:

string transactionId = postOperation.Id;
Console.WriteLine($"Appended transaction with Id: {transactionId}");

Read from the confidential ledger

With a transaction ID, you can also read from the confidential ledger using the GetLedgerEntry method:

Response ledgerResponse = ledgerClient.GetLedgerEntry(transactionId, collectionId);

string entryContents = JsonDocument.Parse(ledgerResponse.Content)
    .RootElement
    .GetProperty("entry")
    .GetProperty("contents")
    .GetString();

Console.WriteLine(entryContents);

Test and verify

In the console directly, execute the following command to run the app.

dotnet run

Sample code

using System;
using Azure.Core;
using Azure.Identity;
using Azure.Security.ConfidentialLedger;
using Azure.Security.ConfidentialLedger.Certificate;
    
namespace acl_app
{
    class Program
    {
        static Task Main(string[] args)
        {

            // Replace with the name of your confidential ledger

            const string ledgerName = "myLedger";
            var ledgerUri = $"https://{ledgerName}.confidential-ledger.azure.com";

            // Create a confidential ledger client using the ledger URI and DefaultAzureCredential

            var ledgerClient = new ConfidentialLedgerClient(new Uri(ledgerUri), new DefaultAzureCredential());

            // Write to the ledger

            Operation postOperation = ledgerClient.PostLedgerEntry(
                waitUntil: WaitUntil.Completed,
                RequestContent.Create(
                    new { contents = "Hello world!" }));
            
            // Access the transaction ID of the ledger write

            string transactionId = postOperation.Id;
            Console.WriteLine($"Appended transaction with Id: {transactionId}");


            // Use the transaction ID to read from the ledger

            Response ledgerResponse = ledgerClient.GetLedgerEntry(transactionId, collectionId);

            string entryContents = JsonDocument.Parse(ledgerResponse.Content)
                .RootElement
                .GetProperty("entry")
                .GetProperty("contents")
                .GetString();

            Console.WriteLine(entryContents);

        }
    }
}

Next steps

To learn more about Azure confidential ledger and how to integrate it with your apps, see the following articles:

Share via