Azure Container Registry client library for .NET
Azure Container Registry allows you to store and manage container images and artifacts in a private registry for all types of container deployments.
Use the client library for Azure Container Registry to:
- List images or artifacts in a registry
- Obtain metadata for images and artifacts, repositories and tags
- Set read/write/delete properties on registry items
- Delete images and artifacts, repositories and tags
Source code | [Package (NuGet)] | [API reference documentation] | REST API documentation | Product documentation
Getting started
Install the package
Install the Azure Container Registry client library for .NET with NuGet:
dotnet add package Azure.Containers.ContainerRegistry --prerelease
Prerequisites
You need an Azure subscription and a Container Registry account to use this package.
To create a new Container Registry, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:
az acr create --name MyContainerRegistry --resource-group MyResourceGroup --location westus --sku Basic
Authenticate the client
The Azure Identity library provides easy Azure Active Directory support for authentication.
// Create a ContainerRegistryClient that will authenticate through Active Directory
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
Note that these samples assume you have a REGISTRY_ENDPOINT
environment variable set, which is the URL including the name of the login server and the https://
prefix.
For more information on using AAD with Azure Container Registry, please see the service's Authentication Overview.
Key concepts
A registry stores Docker images and OCI Artifacts. An image or artifact consists of a manifest and layers. An image's manifest describes the layers that make up the image, and is uniquely identified by its digest. An image can also be "tagged" to give it a human-readable alias. An image or artifact can have zero or more tags associated with it, and each tag uniquely identifies the image. A collection of images that share the same name but have different tags, is referred to as a repository.
For more information please see Container Registry Concepts.
Thread safety
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation to reuse client instances is always safe, even across threads.
Additional concepts
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
Examples
Sync examples
Async examples
List repositories
Iterate through the collection of repositories in the registry.
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
// Perform an operation
Pageable<string> repositories = client.GetRepositories();
foreach (string repository in repositories)
{
Console.WriteLine(repository);
}
List repositories asynchronously
The asynchronous APIs are identical to their synchronous counterparts, but methods end with the standard .NET "Async" suffix and return a Task.
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
// Perform an operation
AsyncPageable<string> repositories = client.GetRepositoriesAsync();
await foreach (string repository in repositories)
{
Console.WriteLine(repository);
}
Troubleshooting
All container registry service operations will throw a RequestFailedException on failure.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create an invalid ContainerRepositoryClient
string fakeRepositoryName = "doesnotexist";
ContainerRepositoryClient client = new ContainerRepositoryClient(endpoint, fakeRepositoryName, new DefaultAzureCredential());
try
{
client.GetProperties();
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
Console.WriteLine("Repository wasn't found.");
}
You can also easily enable console logging if you want to dig deeper into the requests you're making against the service.
Next steps
- Go further with Azure.Containers.ContainerRegistry and our samples
- Watch a demo or deep dive video
- Read more about the Azure Container Registry service
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.