{"id":2641,"date":"2023-05-12T07:59:01","date_gmt":"2023-05-12T14:59:01","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=2641"},"modified":"2023-05-12T07:59:01","modified_gmt":"2023-05-12T14:59:01","slug":"announcing-the-new-azure-container-registry-libraries","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/announcing-the-new-azure-container-registry-libraries\/","title":{"rendered":"Announcing the new Azure Container Registry libraries"},"content":{"rendered":"

We’re pleased to announce that version 1.1.0 of the Azure Container Registry (ACR) libraries for .NET, Java, JavaScript\/TypeScript, and Python are now generally available. A Go library is currently available as a preview<\/a>; the stable release is expected later this year.<\/p>\n

Our new libraries follow our modern Azure SDK Guidelines<\/a>, meaning that you can expect an idiomatic, consistent, approachable, diagnosable, and dependable library experience. These libraries use the language-specific Azure Core packages, which handle requests, errors, and credentials.<\/p>\n

ACR<\/a> is a private registry service that allows you to create, store, and manage container images and related artifacts. It’s compatible with Docker and Open Container Initiative (OCI) images and artifacts, which means you can use it with your existing container development and deployment pipelines. If you need to build container images on demand, you can use ACR Tasks.<\/p>\n

New features<\/h2>\n

One of the most significant improvements in this version of the ACR library is the ability to upload and download images to ACR. Previously, version 1.0 only allowed developers to list repositories and images, get and update metadata, and delete them.<\/p>\n

Library availability<\/h2>\n

The new ACR libraries can be downloaded from each language’s preferred package manager.<\/p>\n\n\n\n\n\n\n\n\n
Language<\/th>\nPackage<\/th>\nCommand<\/th>\nProject<\/th>\nGet started<\/th>\n<\/tr>\n<\/thead>\n
.NET<\/td>\nNuGet<\/a><\/td>\ndotnet add package Azure.Containers.ContainerRegistry<\/code><\/td>\nlink<\/a><\/td>\nlink<\/a><\/td>\n<\/tr>\n
Java<\/td>\nJava<\/a><\/td>\nAdd to POM.xml file<\/a><\/td>\nlink<\/a><\/td>\nlink<\/a><\/td>\n<\/tr>\n
JavaScript\/TypeScript<\/td>\nnpm<\/a><\/td>\nnpm install @azure\/container-registry<\/code><\/td>\nlink<\/a><\/td>\nlink<\/a><\/td>\n<\/tr>\n
Python<\/td>\nPyPI<\/a><\/td>\npip install azure-containerregistry<\/code><\/td>\nlink<\/a><\/td>\nlink<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Code samples<\/h2>\n

The following samples illustrate how to upload and download OCI and Docker images to an ACR instance using the ACR library for .NET.<\/p>\n

Samples are also available for Java<\/a>, TypeScript<\/a>\/JavaScript<\/a>, and Python<\/a>.<\/p>\n

Create a client<\/h3>\n

Create a ContainerRegistryContentClient<\/code> for the registry, passing the repository, credentials, and client options.<\/p>\n

\/\/ Get the service endpoint from the environment\r\nUri endpoint = new(Environment.GetEnvironmentVariable(\"REGISTRY_ENDPOINT\"));\r\n\r\nstring repository = \"sample-oci-image\";\r\nstring tag = \"demo\";\r\n\r\n\/\/ Create a new ContainerRegistryContentClient\r\nContainerRegistryContentClient client = new(endpoint, repository, new DefaultAzureCredential());<\/code><\/pre>\n
Upload an OCI image<\/h3>\n
To upload an OCI image, upload its config file, layers, and manifest. In this sample, the manifest is updated with information about each file associated with the image, and then uploaded as a final step.<\/p>\n
\/\/ Create a manifest to list files in this image\r\nOciImageManifest manifest = new(schemaVersion: 2);\r\n\r\n\/\/ Upload a config file\r\nBinaryData config = BinaryData.FromString(\"Sample config\");\r\nUploadRegistryBlobResult uploadConfigResult = await client.UploadBlobAsync(config);\r\n\r\n\/\/ Update manifest with config info\r\nmanifest.Configuration = new OciDescriptor()\r\n{\r\n  Digest = uploadConfigResult.Digest,\r\n  SizeInBytes = uploadConfigResult.SizeInBytes,\r\n  MediaType = \"application\/vnd.oci.image.config.v1+json\"\r\n};\r\n\r\n\/\/ Upload a layer file\r\nBinaryData layer = BinaryData.FromString(\"Sample layer\");\r\nUploadRegistryBlobResult uploadLayerResult = await client.UploadBlobAsync(layer);\r\n\r\n\/\/ Update manifest with layer info\r\nmanifest.Layers.Add(new OciDescriptor()\r\n{\r\n  Digest = uploadLayerResult.Digest,\r\n  SizeInBytes = uploadLayerResult.SizeInBytes,\r\n  MediaType = \"application\/vnd.oci.image.layer.v1.tar\"\r\n});\r\n\r\n\/\/ Finally, upload the manifest file\r\nawait client.SetManifestAsync(manifest, tag);<\/code><\/pre>\n
Download an OCI image<\/h3>\n
To download an OCI image, first download its manifest. The manifest describes the files that need to be downloaded to pull the full image.<\/p>\n
\/\/ Download the manifest to obtain the list of files in the image\r\nGetManifestResult result = await client.GetManifestAsync(tag);\r\nOciImageManifest manifest = result.Manifest.ToObjectFromJson<OciImageManifest>();\r\n\r\nstring manifestFile = Path.Combine(path, \"manifest.json\");\r\n\r\nusing (FileStream stream = File.Create(manifestFile))\r\n{\r\n  await result.Manifest.ToStream().CopyToAsync(stream);\r\n}\r\n\r\n\/\/ Download and write out the config\r\nDownloadRegistryBlobResult configBlob = await client.DownloadBlobContentAsync(manifest.Configuration.Digest);\r\nstring configFile = Path.Combine(path, \"config.json\");\r\n\r\nusing (FileStream stream = File.Create(configFile))\r\n{\r\n  await configBlob.Content.ToStream().CopyToAsync(stream);\r\n}\r\n\r\n\/\/ Download and write out the layers\r\nforeach (OciDescriptor layerInfo in manifest.Layers)\r\n{\r\n  string layerFile = Path.Combine(path, TrimSha(layerInfo.Digest));\r\n  using (FileStream stream = File.Create(layerFile))\r\n  {\r\n    await client.DownloadBlobToAsync(layerInfo.Digest, stream);\r\n  }\r\n}\r\n\r\nstatic string TrimSha(string digest)\r\n{\r\n  int index = digest.IndexOf(':');\r\n  if (index > -1)\r\n  {\r\n    return digest.Substring(index + 1);\r\n  }\r\n  return digest;\r\n}<\/code><\/pre>\n
Upload a custom manifest type<\/h3>\n
To upload an image with a custom manifest type, pass the ManifestMediaType<\/code> to the UploadManifest<\/code> method.<\/p>\n
\/\/ Create a manifest file in the Docker v2 Manifest List format\r\ndynamic manifestList = new\r\n{\r\n  schemaVersion = 2,\r\n  mediaType = \"application\/vnd.docker.distribution.manifest.list.v2+json\",\r\n  manifests = new[]\r\n  {\r\n    new\r\n    {\r\n      digest = \"sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4\",\r\n      mediaType = ManifestMediaType.DockerManifest.ToString(),\r\n      platform = new {\r\n        architecture = ArtifactArchitecture.Amd64.ToString(),\r\n        os = ArtifactOperatingSystem.Linux.ToString()\r\n      }\r\n    }\r\n  }\r\n};\r\n\r\n\/\/ Finally, upload the manifest file\r\nBinaryData content = BinaryData.FromObjectAsJson(manifestList);\r\nawait client.SetManifestAsync(content, tag: \"sample\", ManifestMediaType.DockerManifestList);<\/code><\/pre>\n
Download a manifest of an unknown type<\/h3>\n
If you’re downloading a manifest where the media type isn’t known ahead of time, check the MediaType<\/code> property returned on the DownloadManifestResult<\/code> to determine the type.<\/p>\n
GetManifestResult result = await client.GetManifestAsync(\"sample\");\r\nif (result.MediaType == \"application\/vnd.docker.distribution.manifest.list.v2+json\")\r\n{\r\n  Console.WriteLine(\"Manifest is a Docker manifest list.\");\r\n}\r\nelse if (result.MediaType == \"application\/vnd.oci.image.index.v1+json\")\r\n{\r\n  Console.WriteLine(\"Manifest is an OCI index.\");\r\n}<\/code><\/pre>\n
Delete a manifest<\/h3>\n
A manifest can be deleted as shown in the following example. It’s also possible to delete a full image using the ContainerRegistryClient<\/code> as shown in a separate example<\/a>.<\/p>\n
GetManifestResult manifestResult = await client.GetManifestAsync(tag);\r\nawait client.DeleteManifestAsync(manifestResult.Digest);<\/code><\/pre>\n
Delete a blob<\/h3>\n
A blob can be deleted as shown in the following example. It’s also possible to delete a full image using the ContainerRegistryClient<\/code> as shown in a separate example<\/a>.<\/p>\n
GetManifestResult result = await client.GetManifestAsync(tag);\r\nOciImageManifest manifest = result.Manifest.ToObjectFromJson<OciImageManifest>();\r\n\r\nforeach (OciDescriptor layerInfo in manifest.Layers)\r\n{\r\n  await client.DeleteBlobAsync(layerInfo.Digest);\r\n}<\/code><\/pre>\n
Learn more<\/h2>\n
We hope this article was a useful introduction to the new and improved ACR libraries and how you can use them today to build and ship rich experiences.<\/p>\n
To learn more and to get started, see these links to our official documentation:<\/p>\n