Implement delete and recover LROs on CertificateClient

Fixes Azure#8009

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

@@ -1,5 +1,12 @@
 # Release History
 
+## 4.0.0-preview.7
+
+### Breaking changes
+
+- `CertificateClient.DeleteCertificate` has been renamed to `CertificateClient.StartDeleteCertificate` and now returns a `DeleteCertificateOperation` to track this long-running operation.
+- `CertificateClient.RecoverDeletedCertificate` has been renamed to `CertificateClient.StartRecoverDeletedCertificate` and now returns a `RecoverDeletedCertificateOperation` to track this long-running operation.
+
 ## 4.0.0-preview.6 (2019-11)
 
 ### Breaking changes

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

@@ -24,7 +24,18 @@ If you use the Azure CLI, replace `<your-resource-group-name>` and `<your-key-va
 az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
 ```
 
- #### Create/Get credentials
+### Authenticate the client
+In order to interact with the Key Vault service, you'll need to create an instance of the [CertificateClient][certificate_client_class] class. You would need a **vault url**, which you may see as "DNS Name" in the portal,
+ and **client secret credentials (client id, client secret, tenant id)** to instantiate a client object.
+
+Client secret credential authentication is being used in this getting started section but you can find more ways to authenticate with [Azure identity][azure_identity]. To use the `DefaultAzureCredential` provider shown below,
+or other credential providers provided with the Azure SDK, you should install the Azure.Identity package:
+
+```PowerShell
+Install-Package Azure.Identity
+```
+
+#### Create/Get credentials
 Use the [Azure CLI][azure_cli] snippet below to create/get client secret credentials.
 
  * Create a service principal and configure its access to Azure resources:
@@ -88,23 +99,22 @@ illustrated in the examples below.
 ## Examples
 The Azure.Security.KeyVault.Certificates package supports synchronous and asynchronous APIs.
 
-The following section provides several code snippets using the [above created](#create-certificateclient) `client`, covering some of the most
-common Azure Key Vault certificates service related tasks:
+The following section provides several code snippets using the [above created](#create-certificateclient) `client`, covering some of the most common Azure Key Vault certificate service related tasks:
 
-### Sync Examples
-This section contains code snippets covering common tasks:
-* [Create a Certificate](#create-a-certificate)
-* [Retrieve a Certificate](#retrieve-a-certificate)
-* [Update an existing Certificate](#update-an-existing-certificate)
-* [Delete a Certificate](#delete-a-certificate)
-* [List Certificates](#list-certificates)
+### Sync examples
+* [Create a certificate](#create-a-certificate)
+* [Retrieve a certificate](#retrieve-a-certificate)
+* [Update an existing certificate](#update-an-existing-certificate)
+* [List certificates](#list-certificates)
+* [Delete a certificate](#delete-a-certificate)
 
-### Async Examples
+### Async examples
 * [Create a certificate asynchronously](#create-a-certificate-asynchronously)
 * [List certificates asynchronously](#list-certificates-asynchronously)
+* [Delete a certificate asynchronously](#delete-a-certificate-asynchronously)
 
-### Create a Certificate
-`StartCreateCertificate` creates a Certificate to be stored in the Azure Key Vault. If a certificate with
+### Create a certificate
+`StartCreateCertificate` creates a Certificate to be stored in the Azure Key Vault. If a certificate with 
 the same name already exists, then a new version of the certificate is created.
 When creating the certificate the user can specify the policy which controls the certificate lifetime. If no policy is specified the default policy will be used. The `StartCreateCertificate` operation returns a `CertificateOperation`. The following example creates a self signed certificate with the default policy.
 
@@ -113,17 +123,20 @@ When creating the certificate the user can specify the policy which controls the
 CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);
 
 // You can await the completion of the create certificate operation.
+// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
 while (!operation.HasCompleted)
 {
-    operation.UpdateStatus();
+    Thread.Sleep(2000);
 
-    Thread.Sleep(TimeSpan.FromSeconds(1));
+    operation.UpdateStatus();
 }
+
+KeyVaultCertificateWithPolicy certificate = operation.Value;
 ```
 
 > NOTE: Depending on the certificate issuer and validation methods, certificate creation and signing can take an indeterministic amount of time. Users should only wait on certificate operations when the operation can be reasonably completed in the scope of the application, such as with self signed certificates or issuers with well known response times.
 
-### Retrieve a Certificate
+### Retrieve a certificate
 `GetCertificateWithPolicy` retrieves the latest version of a certificate stored in the Key Vault along with its `CertificatePolicy`.
 
 ```C# Snippet:RetrieveCertificate
@@ -140,30 +153,13 @@ KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPo
 `UpdateCertificate` updates a certificate stored in the Key Vault.
 
 ```C# Snippet:UpdateCertificate
-CertificateProperties certificateProperties = new CertificateProperties(certificate.Id)
-{
-    Tags =
-    {
-        ["key1"] = "value1"
-    }
-};
+CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
+certificateProperties.Tags["key1"] = "value1";
 
 KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);
 ```
 
-### Delete a Certificate
-`DeleteCertificate` deletes all versions of a certificate stored in the Key Vault. When [soft-delete][soft_delete]
-is not enabled for the Key Vault, this operation permanently deletes the certificate. If soft delete is enabled the certificate is marked for deletion and can be optionally purged or recovered up until its scheduled purge date.
-
-```C# Snippet:DeleteCertificate
-DeletedCertificate deleteCert = client.DeleteCertificate("MyCertificate");
-
-Console.WriteLine(deleteCert.ScheduledPurgeDate);
-
-client.PurgeDeletedCertificate(deleteCert.Name);
-```
-
-### List Certificates
+### List certificates
 `GetCertificates` enumerates the certificates in the vault, returning select properties of the
 certificate. Sensitive fields of the certificate will not be returned. This operation
 requires the certificates/list permission.
@@ -177,20 +173,41 @@ foreach (CertificateProperties certificateProperties in allCertificates)
 }
 ```
 
+### Delete a certificate
+`DeleteCertificate` deletes all versions of a certificate stored in the Key Vault. When [soft-delete][soft_delete] 
+is not enabled for the Key Vault, this operation permanently deletes the certificate. If soft delete is enabled the certificate is marked for deletion and can be optionally purged or recovered up until its scheduled purge date.
+
+```C# Snippet:DeleteAndPurgeCertificate
+DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");
+
+// You only need to wait for completion if you want to purge or recover the secret.
+// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
+while (!operation.HasCompleted)
+{
+    Thread.Sleep(2000);
+
+    operation.UpdateStatus();
+}
+
+DeletedCertificate secret = operation.Value;
+client.PurgeDeletedCertificate(secret.Name);
+```
+
 ### Create a certificate asynchronously
 The asynchronous APIs are identical to their synchronous counterparts, but return with the typical "Async" suffix for asynchronous methods and return a `Task`.
 
+This example creates a certificate in the Key Vault with the specified optional arguments.
+
 ```C# Snippet:CreateCertificateAsync
 // Create a certificate. This starts a long running operation to create and sign the certificate.
 CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);
 
-// You can  the completion of the create certificate operation.
+// You can await the completion of the create certificate operation.
 KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();
 ```
 
 ### List certificates asynchronously
-Listing certificates does not rely on awaiting the `GetPropertiesOfSecretsAsync` method, but returns an `AsyncPageable<SecretProperties>` that
-you can use with the `await foreach` statement:
+Listing certificate does not rely on awaiting the `GetPropertiesOfCertificatesAsync` method, but returns an `AsyncPageable<CertificateProperties>` that you can use with the `await foreach` statement:
 
 ```C# Snippet:ListCertificatesAsync
 AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();
@@ -201,6 +218,20 @@ await foreach (CertificateProperties certificateProperties in allCertificates)
 }
 ```
 
+### Delete a certificate asynchronously
+When deleting a certificate asynchronously before you purge it, you can await the `WaitForCompletionAsync` method on the operation.
+By default, this loops indefinitely but you can cancel it by passing a `CancellationToken`.
+
+```C# Snippet:DeleteAndPurgeCertificateAsync
+DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");
+
+// You only need to wait for completion if you want to purge or recover the secret.
+await operation.WaitForCompletionAsync();
+
+DeletedCertificate secret = operation.Value;
+await client.PurgeDeletedCertificateAsync(secret.Name);
+```
+
 ## Troubleshooting
 
 ### General

sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md

@@ -74,7 +74,15 @@ while (!newCertOp.HasCompleted)
 The certificate is no longer needed, so delete it from the Key Vault.
 
 ```C# Snippet:CertificatesSample1DeleteCertificate
-client.DeleteCertificate(certName);
+DeleteCertificateOperation operation = client.StartDeleteCertificate(certName);
+
+// To ensure certificate is deleted on server side.
+while (!operation.HasCompleted)
+{
+    Thread.Sleep(2000);
+
+    operation.UpdateStatus();
+}
 ```
 
 ## Source

sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample2_GetCertificates.md

@@ -83,8 +83,17 @@ The certificates are no longer needed.
 You need to delete them from the Key Vault.
 
 ```C# Snippet:CertificatesSample2DeleteCertificates
-client.DeleteCertificate(certName1);
-client.DeleteCertificate(certName2);
+DeleteCertificateOperation operation1 = client.StartDeleteCertificate(certName1);
+DeleteCertificateOperation operation2 = client.StartDeleteCertificate(certName2);
+
+// To ensure certificates are deleted on server side.
+while (!operation1.HasCompleted || !operation2.HasCompleted)
+{
+    Thread.Sleep(2000);
+
+    operation1.UpdateStatus();
+    operation2.UpdateStatus();
+}
 ```
 
 ## Listing deleted certificates