Azure Container Registry Clientbibliothek für .NET – Version 1.1.0

Azure Container Registry ermöglicht Ihnen das Speichern und Verwalten von Containerimages und Artefakten in einer privaten Registrierung für alle Arten von Containerbereitstellungen.

Verwenden Sie die Clientbibliothek für Azure Container Registry für Folgendes:

• Auflisten von Images oder Artefakten in einer Registrierung
• Abrufen von Metadaten für Bilder und Artefakte, Repositorys und Tags
• Festlegen von Lese-/Schreib-/Löscheigenschaften für Registrierungselemente
• Löschen von Bildern und Artefakten, Repositorys und Tags

Quellcode | Paket (NuGet) | API-Referenzdokumentation | DOKUMENTATION | ZUR REST-APIProduktdokumentation

Erste Schritte

Zum Entwickeln von .NET-Anwendungscode, der eine Verbindung mit einer Azure Container Registry-Instanz herstellen kann, benötigen Sie die Bibliothek Azure.Containers.ContainerRegistry.

Installieren des Pakets

Installieren Sie die Azure Container Registry-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Containers.ContainerRegistry

Voraussetzungen

Sie benötigen ein Azure-Abonnement und einen Container Registry-Dienst instance, damit Ihre Anwendung eine Verbindung herstellen kann.

Um eine neue Container Registry zu erstellen, können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Hier ein Beispiel für das Erstellen einer neuen Registrierung mithilfe der Azure CLI:

az acr create --name myregistry --resource-group myresourcegroup --location westus --sku Basic

Authentifizieren des Clients

Damit Ihre Anwendung eine Verbindung mit der Registrierung herstellen kann, müssen Sie ein für die Authentifizierung geeignetes ContainerRegistryClient-Element erstellen. Die Azure Identity-Bibliothek erleichtert das Hinzufügen von Azure Active Directory-Unterstützung für die Authentifizierung von Azure SDK-Clients mit den entsprechenden Azure-Diensten.

Wenn Sie Ihre Anwendung lokal entwickeln und debuggen, können Sie Ihren eigenen Benutzer verwenden, um sich bei der Registrierung zu authentifizieren. Dazu können Sie den Benutzer mit der Azure CLI authentifizieren und Ihre Anwendung über diese Anwendung ausführen. Wenn Ihre Anwendung einen Client verwendet, der für die Authentifizierung mit DefaultAzureCredential erstellt wurde, wird die Authentifizierung bei der Registrierung am angegebenen Endpunkt ordnungsgemäß ausgeführt.

// Create a ContainerRegistryClient that will authenticate to your registry through Azure Active Directory
Uri endpoint = new Uri("https://myregistry.azurecr.io");
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
    new ContainerRegistryClientOptions()
    {
        Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
    });

Weitere Ansätze zur Authentifizierung mit DefaultAzureCredential, sowohl lokal als auch in Bereitstellungsumgebungen, finden Sie in der Azure Identity-INFODATEI. Informationen zum Herstellen einer Verbindung mit Registrierungen in nicht öffentlichen Azure-Clouds finden Sie in den folgenden Beispielen.

Weitere Informationen zur Verwendung von AAD mit Azure Container Registry finden Sie in der Authentifizierungsübersicht des Diensts.

Wichtige Begriffe

Eine Registrierung speichert Docker-Images und OCI-Artefakte. Ein Image oder Artefakt besteht aus einem Manifest und Ebenen. Das Manifest eines Bilds beschreibt die Ebenen, aus denen das Bild besteht, und wird durch den Digest eindeutig identifiziert. Ein Bild kann auch "getaggt" werden, um ihm einen lesbaren Alias zu verleihen. Einem Bild oder Artefakt können null oder mehr Tags zugeordnet sein, und jedes Tag identifiziert das Bild eindeutig. Eine Sammlung von Bildern, die denselben Namen haben, aber unterschiedliche Tags aufweisen, wird als Repository bezeichnet.

Weitere Informationen finden Sie unter Konzepte der Containerregistrierung.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung zur Wiederverwendung von Clientinstanzen immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Die folgenden Codeausschnitte zeigen kurze Beispiele gängiger Entwicklerszenarien, die die ACR SDK-Bibliothek verwenden. Beachten Sie, dass jedes Beispiel davon ausgeht, dass eine REGISTRY_ENDPOINT Umgebungsvariable auf eine Zeichenfolge festgelegt ist, die das https:// Präfix und den Namen des Anmeldeservers enthält, z. B. "https://myregistry.azurecr.io"".

Synchronisierungsbeispiele

• Registrierungsvorgänge:
  • Auflisten von Repositorys
  • Listentags mit anonymem Zugriff
  • Festlegen von Artefakteigenschaften
  • Löschen von Images

Asynchrone Beispiele

• Registrierungsvorgänge:
  • Asynchrones Auflisten von Repositorys
  • Asynchrones Auflisten von Tags mit anonymem Zugriff
  • Asynchrones Festlegen von Artefakteigenschaften
  • Asynchrones Löschen von Images
• Blob- und Manifestvorgänge:
  • Hochladen von Bildern
  • Bilder herunterladen
  • Manifest löschen
  • Löschen eines Blobs

Erweiterte Authentifizierung

• Erstellen eines Clients, der sich bei einer Registrierung in einer nationalen Cloud authentifizieren kann

Registrierungsvorgänge

Diese Secion enthält ContainerRegistryClient Beispiele.

Auflisten von Repositorys

Durchlaufen Sie die Sammlung von Repositorys in der Registrierung:

// 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());

// Get the collection of repository names from the registry
Pageable<string> repositories = client.GetRepositoryNames();
foreach (string repository in repositories)
{
    Console.WriteLine(repository);
}

Listentags mit anonymem Zugriff

// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));

// Create a new ContainerRegistryClient for anonymous access
ContainerRegistryClient client = new ContainerRegistryClient(endpoint);

// Obtain a RegistryArtifact object to get access to image operations
RegistryArtifact image = client.GetArtifact("library/hello-world", "latest");

// List the set of tags on the hello_world image tagged as "latest"
Pageable<ArtifactTagProperties> tags = image.GetAllTagProperties();

// Iterate through the image's tags, listing the tagged alias for the image
Console.WriteLine($"{image.FullyQualifiedReference} has the following aliases:");
foreach (ArtifactTagProperties tag in tags)
{
    Console.WriteLine($"    {image.RegistryEndpoint.Host}/{image.RepositoryName}:{tag}");
}

Festlegen von Artefakteigenschaften

// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));

// Create a new ContainerRegistryClient and RegistryArtifact to access image operations
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
RegistryArtifact image = client.GetArtifact("library/hello-world", "latest");

// Set permissions on the v1 image's "latest" tag
image.UpdateTagProperties("latest", new ArtifactTagProperties()
{
    CanWrite = false,
    CanDelete = false
});

Löschen von Images

// 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());

// Iterate through repositories
Pageable<string> repositoryNames = client.GetRepositoryNames();
foreach (string repositoryName in repositoryNames)
{
    ContainerRepository repository = client.GetRepository(repositoryName);

    // Obtain the images ordered from newest to oldest
    Pageable<ArtifactManifestProperties> imageManifests =
        repository.GetAllManifestProperties(manifestOrder: ArtifactManifestOrder.LastUpdatedOnDescending);

    // Delete images older than the first three.
    foreach (ArtifactManifestProperties imageManifest in imageManifests.Skip(3))
    {
        RegistryArtifact image = repository.GetArtifact(imageManifest.Digest);
        Console.WriteLine($"Deleting image with digest {imageManifest.Digest}.");
        Console.WriteLine($"   Deleting the following tags from the image: ");
        foreach (var tagName in imageManifest.Tags)
        {
            Console.WriteLine($"        {imageManifest.RepositoryName}:{tagName}");
            image.DeleteTag(tagName);
        }
        image.Delete();
    }
}

Asynchrones Auflisten von Repositorys

Die asynchronen APIs sind mit ihren synchronen Entsprechungen identisch, aber Methoden enden mit dem standardmäßigen .NET -Suffix "Async" und geben einen Task zurück.

// 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());

// Get the collection of repository names from the registry
AsyncPageable<string> repositories = client.GetRepositoryNamesAsync();
await foreach (string repository in repositories)
{
    Console.WriteLine(repository);
}

Asynchrones Auflisten von Tags mit anonymem Zugriff

// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));

// Create a new ContainerRegistryClient for anonymous access
ContainerRegistryClient client = new ContainerRegistryClient(endpoint);

// Obtain a RegistryArtifact object to get access to image operations
RegistryArtifact image = client.GetArtifact("library/hello-world", "latest");

// List the set of tags on the hello_world image tagged as "latest"
AsyncPageable<ArtifactTagProperties> tags = image.GetAllTagPropertiesAsync();

// Iterate through the image's tags, listing the tagged alias for the image
Console.WriteLine($"{image.FullyQualifiedReference} has the following aliases:");
await foreach (ArtifactTagProperties tag in tags)
{
    Console.WriteLine($"    {image.RegistryEndpoint.Host}/{image.RepositoryName}:{tag}");
}

Asynchrones Festlegen von Artefakteigenschaften

// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));

// Create a new ContainerRegistryClient and RegistryArtifact to access image operations
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
RegistryArtifact image = client.GetArtifact("library/hello-world", "v1");

// Set permissions on the image's "latest" tag
await image.UpdateTagPropertiesAsync("latest", new ArtifactTagProperties()
{
    CanWrite = false,
    CanDelete = false
});

Asynchrones Löschen von Images

// 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());

// Iterate through repositories
AsyncPageable<string> repositoryNames = client.GetRepositoryNamesAsync();
await foreach (string repositoryName in repositoryNames)
{
    ContainerRepository repository = client.GetRepository(repositoryName);

    // Obtain the images ordered from newest to oldest
    AsyncPageable<ArtifactManifestProperties> imageManifests =
        repository.GetAllManifestPropertiesAsync(manifestOrder: ArtifactManifestOrder.LastUpdatedOnDescending);

    // Delete images older than the first three.
    await foreach (ArtifactManifestProperties imageManifest in imageManifests.Skip(3))
    {
        RegistryArtifact image = repository.GetArtifact(imageManifest.Digest);
        Console.WriteLine($"Deleting image with digest {imageManifest.Digest}.");
        Console.WriteLine($"   Deleting the following tags from the image: ");
        foreach (var tagName in imageManifest.Tags)
        {
            Console.WriteLine($"        {imageManifest.RepositoryName}:{tagName}");
            await image.DeleteTagAsync(tagName);
        }
        await image.DeleteAsync();
    }
}

Blob- und Manifestvorgänge

Dieser Abschnitt enthält Beispiele für ContainerRegistryContentClient das Hochladen und Herunterladen von Bildern.

Erstellen Sie zunächst einen Blobclient.

// Get the service endpoint from the environment
Uri endpoint = new(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));

string repository = "sample-oci-image";
string tag = "demo";

// Create a new ContainerRegistryContentClient
ContainerRegistryContentClient client = new(endpoint, repository, new DefaultAzureCredential());

Hochladen von Bildern

Zum Hochladen eines vollständigen Bilds müssen einzelne Ebenen und Konfigurationen hochgeladen werden. Danach können wir ein Manifest hochladen, das ein Bild oder Artefakt beschreibt, und ihm ein Tag zuweisen.

// Create a manifest to list files in this image
OciImageManifest manifest = new(schemaVersion: 2);

// Upload a config file
BinaryData config = BinaryData.FromString("Sample config");
UploadRegistryBlobResult uploadConfigResult = await client.UploadBlobAsync(config);

// Update manifest with config info
manifest.Configuration = new OciDescriptor()
{
    Digest = uploadConfigResult.Digest,
    SizeInBytes = uploadConfigResult.SizeInBytes,
    MediaType = "application/vnd.oci.image.config.v1+json"
};

// Upload a layer file
BinaryData layer = BinaryData.FromString("Sample layer");
UploadRegistryBlobResult uploadLayerResult = await client.UploadBlobAsync(layer);

// Update manifest with layer info
manifest.Layers.Add(new OciDescriptor()
{
    Digest = uploadLayerResult.Digest,
    SizeInBytes = uploadLayerResult.SizeInBytes,
    MediaType = "application/vnd.oci.image.layer.v1.tar"
});

// Finally, upload the manifest file
await client.SetManifestAsync(manifest, tag);

Bilder herunterladen

Um ein vollständiges Image herunterzuladen, müssen wir das Manifest herunterladen und dann einzelne Ebenen und die Konfiguration herunterladen.

// Download the manifest to obtain the list of files in the image
GetManifestResult result = await client.GetManifestAsync(tag);
OciImageManifest manifest = result.Manifest.ToObjectFromJson<OciImageManifest>();

string manifestFile = Path.Combine(path, "manifest.json");
using (FileStream stream = File.Create(manifestFile))
{
    await result.Manifest.ToStream().CopyToAsync(stream);
}

// Download and write out the config
DownloadRegistryBlobResult configBlob = await client.DownloadBlobContentAsync(manifest.Configuration.Digest);

string configFile = Path.Combine(path, "config.json");
using (FileStream stream = File.Create(configFile))
{
    await configBlob.Content.ToStream().CopyToAsync(stream);
}

// Download and write out the layers
foreach (OciDescriptor layerInfo in manifest.Layers)
{
    string layerFile = Path.Combine(path, TrimSha(layerInfo.Digest));
    using (FileStream stream = File.Create(layerFile))
    {
        await client.DownloadBlobToAsync(layerInfo.Digest, stream);
    }
}

static string TrimSha(string digest)
{
    int index = digest.IndexOf(':');
    if (index > -1)
    {
        return digest.Substring(index + 1);
    }

    return digest;
}

Manifest löschen

GetManifestResult manifestResult = await client.GetManifestAsync(tag);
await client.DeleteManifestAsync(manifestResult.Digest);

Löschen eines Blobs

GetManifestResult result = await client.GetManifestAsync(tag);
OciImageManifest manifest = result.Manifest.ToObjectFromJson<OciImageManifest>();

foreach (OciDescriptor layerInfo in manifest.Layers)
{
    await client.DeleteBlobAsync(layerInfo.Digest);
}

Erweiterte Authentifizierung

Authentifizieren in einer nationalen Cloud

Um sich bei einer Registrierung in einer nationalen Cloud zu authentifizieren, müssen Sie die folgenden Ergänzungen zu Ihrer Clientkonfiguration vornehmen:

• Legen Sie die AuthorityHost in den Anmeldeinformationen oder über die Umgebungsvariable AZURE_AUTHORITY_HOST fest.
• Festlegen des in AudienceContainerRegistryClientOptions

// Create a ContainerRegistryClient that will authenticate through AAD in the China national cloud
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
ContainerRegistryClient client = new ContainerRegistryClient(endpoint,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
        {
            AuthorityHost = AzureAuthorityHosts.AzureChina
        }),
    new ContainerRegistryClientOptions()
    {
        Audience = ContainerRegistryAudience.AzureChina
    });

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Nächste Schritte

• Gehen Sie mit Azure.Containers.ContainerRegistry und unseren Beispielen weiter.
• Sehen Sie sich eine Demo oder ein ausführliches Tauchvideo an.
• Erfahren Sie mehr über den Azure Container Registry-Dienst.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. 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. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.