-
Notifications
You must be signed in to change notification settings - Fork 4.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Preliminarily populate ACR README (#19992)
* Escape setting selector query params. * begin work on README * README updates * nits * Take PR suggestion Co-authored-by: Sean Kane <[email protected]> * pr fb Co-authored-by: Sean Kane <[email protected]>
- Loading branch information
1 parent
4498d32
commit 72f6636
Showing
1 changed file
with
88 additions
and
4 deletions.
There are no files selected for viewing
92 changes: 88 additions & 4 deletions
92
sdk/containerregistry/Azure.Containers.ContainerRegistry/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,30 +1,114 @@ | ||
| # Azure Container Registry client library for .NET | ||
|
|
||
| Azure Container Registry allows you to build, store, and manage container images and artifacts in a private registry for all types of container deployments. | ||
| 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 the repositories in a registry | ||
| - List the images or artifacts in a repository | ||
| - 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](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/containerregistry/Azure.Containers.ContainerRegistry) | Package (NuGet) | API reference documentation | [Product documentation](https://docs.microsoft.com//azure/container-registry) | ||
| [Source code][source] | [Package (NuGet)]<!--[package]--> | [API reference documentation]<!--[docs]--> | [REST API documentation][rest_docs] | [Product documentation][product_docs] | ||
|
|
||
| ## Getting started | ||
|
|
||
| ### Install the package | ||
|
|
||
| Install the Azure Container Registry client library for .NET with [NuGet][nuget]: | ||
|
|
||
| ```Powershell | ||
| dotnet add package Azure.Containers.ContainerRegistry --prerelease | ||
| ``` | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| You need an [Azure subscription][azure_sub] and a [Container Registry account][container_registry_docs] to use this package. | ||
|
|
||
| To create a new Container Registry, you can use the [Azure Portal][container_registry_create_portal], | ||
| [Azure PowerShell][container_registry_create_ps], or the [Azure CLI][container_registry_create_cli]. | ||
| Here's an example using the Azure CLI: | ||
|
|
||
| ```Powershell | ||
| az acr create --name MyContainerRegistry --resource-group MyResourceGroup --location westus --sku Basic | ||
| ``` | ||
|
|
||
| ### Authenticate the client | ||
|
|
||
| The [Azure Identity library][identity] provides easy Azure Active Directory support for authentication. | ||
|
|
||
| ```C# | ||
| // Create a ContainerRegistryClient that will authenticate through Active Directory | ||
| Uri registryUri = new Uri("https://MYCONTAINERREGISTRY.azurecr.io/"); | ||
| ContainerRegistryClient client = new ContainerRegistryClient(registryUri, new DefaultAzureCredential()); | ||
| ``` | ||
|
|
||
| ## Key concepts | ||
|
|
||
| A **registry** stores Docker images and [OCI Artifacts](https://opencontainers.org/). 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 manifests and tags, is referred to as a **repository**. | ||
|
|
||
| For more information please see [Container Registry Concepts](https://docs.microsoft.com/azure/container-registry/container-registry-concepts). | ||
|
|
||
| ### Thread safety | ||
|
|
||
| We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads. | ||
|
|
||
| ### Additional concepts | ||
| <!-- CLIENT COMMON BAR --> | ||
| [Client options](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) | | ||
| [Accessing the response](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#accessing-http-response-details-using-responset) | | ||
| [Long-running operations](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#consuming-long-running-operations-using-operationt) | | ||
| [Handling failures](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#reporting-errors-requestfailedexception) | | ||
| [Diagnostics](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md) | | ||
| [Mocking](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#mocking) | | ||
| [Client lifetime](https://devblogs.microsoft.com/azure-sdk/lifetime-management-and-thread-safety-guarantees-of-azure-sdk-net-clients/) | ||
| <!-- CLIENT COMMON BAR --> | ||
|
|
||
| ## Examples | ||
|
|
||
| <!-- Pending Sample Creation --> | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| All container registry service operations will throw a | ||
| [RequestFailedException][RequestFailedException] on failure. | ||
|
|
||
| ## Next steps | ||
|
|
||
| <!-- Pending Sample Creation --> | ||
|
|
||
| ## 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][cla]. | ||
|
|
||
| This project has adopted the [Microsoft Open Source Code of Conduct][coc]. | ||
| For more information see the [Code of Conduct FAQ][coc_faq] | ||
| or contact [[email protected]][coc_contact] with any | ||
| additional questions or comments. | ||
|
|
||
|  | ||
|
|
||
| <!-- LINKS --> | ||
| [source]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/containerregistry/Azure.Containers.ContainerRegistry/src | ||
| [package]: https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/ | ||
| [docs]: https://docs.microsoft.com/dotnet/api/azure.containers.containerregistry | ||
| [rest_docs]: https://docs.microsoft.com/rest/api/containerregistry/ | ||
| [product_docs]: https://docs.microsoft.com/azure/container-registry | ||
| [nuget]: https://www.nuget.org/ | ||
| [container_registry_docs]: https://docs.microsoft.com/azure/container-registry/container-registry-intro | ||
| [container_registry_create_ps]: https://docs.microsoft.com/azure/container-registry/container-registry-get-started-powershell | ||
| [container_registry_create_cli]: https://docs.microsoft.com/azure/container-registry/container-registry-get-started-azure-cli | ||
| [container_registry_create_portal]: https://docs.microsoft.com/azure/container-registry/container-registry-get-started-portal | ||
| [container_registry_concepts]: https://docs.microsoft.com/azure/container-registry/container-registry-concepts | ||
| [azure_cli]: https://docs.microsoft.com/cli/azure | ||
| [azure_sub]: https://azure.microsoft.com/free/ | ||
| [identity]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/identity/Azure.Identity/README.md | ||
| [RequestFailedException]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/core/Azure.Core/src/RequestFailedException.cs | ||
| [samples]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/containerregistry/Azure.Containers.ContainerRegistry/samples/ | ||
| [cla]: https://cla.microsoft.com | ||
| [coc]: https://opensource.microsoft.com/codeofconduct/ | ||
| [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ | ||
| [coc_contact]: mailto:[email protected] |