Add migration guides for KV certs and keys (#15147)

* Add migration guides for KV certs and secrets

Resolves #12108

* Add README links to MigrationGuide.md docs

For all services that currently have them.

sdk/eventhub/Azure.Messaging.EventHubs/README.md

@@ -12,7 +12,7 @@ The Azure Event Hubs client library allows for publishing and consuming of Azure
 
 - Receive events from one or more publishers, transform them to better meet the needs of your ecosystem, then publish the transformed events to a new stream for consumers to observe.
 
-[Source code](.) | [Package (NuGet)](https://www.nuget.org/packages/Azure.Messaging.EventHubs/) | [API reference documentation](https://aka.ms/azsdk-dotnet-eventhubs-docs) | [Product documentation](https://docs.microsoft.com/azure/event-hubs/)
+[Source code](.) | [Package (NuGet)](https://www.nuget.org/packages/Azure.Messaging.EventHubs/) | [API reference documentation](https://aka.ms/azsdk-dotnet-eventhubs-docs) | [Product documentation](https://docs.microsoft.com/azure/event-hubs/) | [Migration guide](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/MigrationGuide.md)
 
 ## Getting started
 

sdk/keyvault/Azure.Security.KeyVault.Certificates/README.md

@@ -3,7 +3,7 @@ Azure Key Vault is a cloud service that provides secure storage and automated ma
 
 The Azure Key Vault certificates client library enables programmatically managing certificates, offering methods to create, update, list, and delete certificates, policies, issuers, and contacts. The library also supports managing pending certificate operations and management of deleted certificates.
 
-[Source code][certificate_client_src] | [Package (NuGet)][certificate_client_nuget_package] | [API reference documentation][API_reference] | [Product documentation][keyvault_docs] | [Samples][certificate_client_samples]
+[Source code][certificate_client_src] | [Package (NuGet)][certificate_client_nuget_package] | [API reference documentation][API_reference] | [Product documentation][keyvault_docs] | [Samples][certificate_client_samples] | [Migration guide][migration_guide]
 
 ## Getting started
 
@@ -183,8 +183,8 @@ while (!operation.HasCompleted)
     operation.UpdateStatus();
 }
 
-DeletedCertificate secret = operation.Value;
-client.PurgeDeletedCertificate(secret.Name);
+DeletedCertificate certificate = operation.Value;
+client.PurgeDeletedCertificate(certificate.Name);
 ```
 
 ### Create a certificate asynchronously
@@ -222,8 +222,8 @@ DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync(
 // You only need to wait for completion if you want to purge or recover the certificate.
 await operation.WaitForCompletionAsync();
 
-DeletedCertificate secret = operation.Value;
-await client.PurgeDeletedCertificateAsync(secret.Name);
+DeletedCertificate certificate = operation.Value;
+await client.PurgeDeletedCertificateAsync(certificate.Name);
 ```
 
 ## Troubleshooting
@@ -311,7 +311,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [azure_cli]: https://docs.microsoft.com/cli/azure
 [certificate_client_class]: src/CertificateClient.cs
 [soft_delete]: https://docs.microsoft.com/azure/key-vault/key-vault-ovw-soft-delete
-[azure_identity]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/identity/Azure.Identity
+[azure_identity]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/identity/Azure.Identity#defaultazurecredential
 [keyvault_rest]: https://docs.microsoft.com/rest/api/keyvault/
 [secrets_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/keyvault/Azure.Security.KeyVault.Secrets
 [keys_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/keyvault/Azure.Security.KeyVault.Keys
@@ -321,5 +321,6 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md
 [contributing]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/CONTRIBUTING.md
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[migration_guide]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Certificates/MigrationGuide.md
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fkeyvault%2FAzure.Security.KeyVault.Certificates%2FREADME.png)

sdk/keyvault/Azure.Security.KeyVault.Certificates/tests/samples/SampleSnippets.cs

@@ -1,9 +1,12 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using Azure.Core.Pipeline;
 using Azure.Identity;
 using NUnit.Framework;
 using System;
+using System.IO;
+using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
 using Azure.Security.KeyVault.Tests;
@@ -141,8 +144,8 @@ public async Task DeleteAndPurgeCertificateAsync()
             // You only need to wait for completion if you want to purge or recover the certificate.
             await operation.WaitForCompletionAsync();
 
-            DeletedCertificate secret = operation.Value;
-            await client.PurgeDeletedCertificateAsync(secret.Name);
+            DeletedCertificate certificate = operation.Value;
+            await client.PurgeDeletedCertificateAsync(certificate.Name);
             #endregion
         }
 
@@ -161,9 +164,127 @@ public void DeleteAndPurgeCertificate()
                 operation.UpdateStatus();
             }
 
-            DeletedCertificate secret = operation.Value;
-            client.PurgeDeletedCertificate(secret.Name);
+            DeletedCertificate certificate = operation.Value;
+            client.PurgeDeletedCertificate(certificate.Name);
             #endregion
         }
+
+        [Ignore("Used only for the migration guide")]
+        private async Task MigrationGuide()
+        {
+            #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_Create
+            CertificateClient client = new CertificateClient(
+                new Uri("https://myvault.vault.azure.net"),
+                new DefaultAzureCredential());
+            #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_Create
+
+            #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateWithOptions
+            using (HttpClient httpClient = new HttpClient())
+            {
+                CertificateClientOptions options = new CertificateClientOptions
+                {
+                    Transport = new HttpClientTransport(httpClient)
+                };
+
+                //@@CertificateClient client = new CertificateClient(
+                /*@@*/ CertificateClient _ = new CertificateClient(
+                    new Uri("https://myvault.vault.azure.net"),
+                    new DefaultAzureCredential(),
+                    options);
+            }
+            #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateWithOptions
+
+            #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateCustomPolicy
+            CertificatePolicy policy = new CertificatePolicy("issuer-name", "CN=customdomain.com")
+            {
+                ContentType = CertificateContentType.Pkcs12,
+                KeyType = CertificateKeyType.Rsa,
+                ReuseKey = true,
+                KeyUsage =
+                {
+                    CertificateKeyUsage.CrlSign,
+                    CertificateKeyUsage.DataEncipherment,
+                    CertificateKeyUsage.DigitalSignature,
+                    CertificateKeyUsage.KeyEncipherment,
+                    CertificateKeyUsage.KeyAgreement,
+                    CertificateKeyUsage.KeyCertSign
+                },
+                ValidityInMonths = 12,
+                LifetimeActions =
+                {
+                    new LifetimeAction(CertificatePolicyAction.AutoRenew)
+                    {
+                        DaysBeforeExpiry = 90,
+                    }
+                }
+            };
+            #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateSelfSignedPolicy
+
+            #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateSelfSignedPolicy
+            //@@CertificatePolicy policy = CertificatePolicy.Default;
+            /*@@*/ policy = CertificatePolicy.Default;
+            #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateSelfSignedPolicy
+
+            {
+                #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateCertificate
+                // Start certificate creation.
+                // Depending on the policy and your business process, this could even take days for manual signing.
+                CertificateOperation createOperation = await client.StartCreateCertificateAsync("certificate-name", policy);
+                KeyVaultCertificateWithPolicy certificate = await createOperation.WaitForCompletionAsync(TimeSpan.FromSeconds(20), CancellationToken.None);
+
+                // If you need to restart the application you can recreate the operation and continue awaiting.
+                createOperation = new CertificateOperation(client, "certificate-name");
+                certificate = await createOperation.WaitForCompletionAsync(TimeSpan.FromSeconds(20), CancellationToken.None);
+                #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_CreateCertificate
+            }
+
+            {
+                #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_ImportCertificate
+                byte[] cer = File.ReadAllBytes("certificate.pfx");
+                ImportCertificateOptions importCertificateOptions = new ImportCertificateOptions("certificate-name", cer)
+                {
+                    Policy = policy
+                };
+
+                KeyVaultCertificateWithPolicy certificate = await client.ImportCertificateAsync(importCertificateOptions);
+                #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_ImportCertificate
+            }
+
+            {
+                #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_ListCertificates
+                // List all certificates asynchronously.
+                await foreach (CertificateProperties item in client.GetPropertiesOfCertificatesAsync())
+                {
+                    KeyVaultCertificateWithPolicy certificate = await client.GetCertificateAsync(item.Name);
+                }
+
+                // List all certificates synchronously.
+                foreach (CertificateProperties item in client.GetPropertiesOfCertificates())
+                {
+                    KeyVaultCertificateWithPolicy certificate = client.GetCertificate(item.Name);
+                }
+                #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_ListCertificates
+            }
+
+            {
+                #region Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_DeleteCertificate
+                // Delete the certificate.
+                DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync("certificate-name");
+
+                // Purge or recover the deleted certificate if soft delete is enabled.
+                if (deleteOperation.Value.RecoveryId != null)
+                {
+                    // Deleting a certificate does not happen immediately. Wait for the certificate to be deleted.
+                    DeletedCertificate deletedCertificate = await deleteOperation.WaitForCompletionAsync();
+
+                    // Purge the deleted certificate.
+                    await client.PurgeDeletedCertificateAsync(deletedCertificate.Name);
+
+                    // You can also recover the deleted certificate using StartRecoverDeletedCertificateAsync,
+                    // which returns RecoverDeletedCertificateOperation you can await like DeleteCertificateOperation above.
+                }
+                #endregion Snippet:Azure_Security_KeyVault_Certificates_Snippets_MigrationGuide_DeleteCertificate
+            }
+        }
     }
 }