List secret versions in Key Vault migration guide (Azure#39994)

* List secret versions in Key Vault migration guide * Add new section to ToC
azure-sdk · Nov 14, 2023 · 559c8c8 · 559c8c8
1 parent c9b204f
commit 559c8c8
Show file tree

Hide file tree

Showing 3 changed files with 77 additions and 0 deletions.
diff --git a/sdk/keyvault/Azure.Security.KeyVault.Secrets/MigrationGuide.md b/sdk/keyvault/Azure.Security.KeyVault.Secrets/MigrationGuide.md
@@ -14,6 +14,7 @@ Familiarity with the `Microsoft.Azure.KeyVault` library is assumed. For those ne
   - [Setting secrets](#setting-secrets)
   - [Getting secrets](#getting-secrets)
   - [Listing secrets](#listing-secrets)
+  - [Listing secret versions](#listing-secret-versions)
   - [Deleting secrets](#deleting-secrets)
   - [Managing shared access signatures](#managing-shared-access-signatures)
 - [Additional samples](#additional-samples)
@@ -187,6 +188,45 @@ foreach (SecretProperties item in client.GetPropertiesOfSecrets())
 }
 ```
 
+### Listing secret versions
+
+Previously in `Microsoft.Azure.KeyVault`, you could list secret versions' properties using the `KeyVaultClient` and a specific Key Vault endpoint:
+
+```C# Snippet:Microsoft_Azure_KeyVault_Secrets_Snippets_MigrationGuide_ListSecretVersions
+IPage<SecretItem> page = await client.GetSecretVersionsAsync("https://myvault.vault.azure.net", "secret-name");
+foreach (SecretItem item in page)
+{
+    SecretIdentifier secretId = item.Identifier;
+    SecretBundle secret = await client.GetSecretAsync(secretId.Vault, secretId.Name, secretId.Version);
+}
+
+while (page.NextPageLink != null)
+{
+    page = await client.GetSecretVersionsNextAsync(page.NextPageLink);
+    foreach (SecretItem item in page)
+    {
+        SecretIdentifier secretId = item.Identifier;
+        SecretBundle secret = await client.GetSecretAsync(secretId.Vault, secretId.Name, secretId.Version);
+    }
+}
+```
+
+Now in `Azure.Security.KeyVault.Secrets`, you list secret versions' properties in the Key Vault you specified when constructing the `SecretClient`. This returns an enumerable that enumerates all secret versions across any number of pages. If you want to enumerate pages, call the `AsPages` method on the returned enumerable.
+
+```C# Snippet:Azure_Security_KeyVault_Secrets_Snippets_MigrationGuide_ListSecretVersions
+// List all secrets asynchronously.
+await foreach (SecretProperties item in client.GetPropertiesOfSecretVersionsAsync("secret-name"))
+{
+    KeyVaultSecret secret = await client.GetSecretAsync(item.Name, item.Version);
+}
+
+// List all secrets synchronously.
+foreach (SecretProperties item in client.GetPropertiesOfSecretVersions("secret-name"))
+{
+    KeyVaultSecret secret = client.GetSecret(item.Name, item.Version);
+}
+```
+
 ### Deleting secrets
 
 Previously in `Microsoft.Azure.KeyVault`, you could delete a secret using the `KeyVaultClient` and a specific Key Vault endpoint:

diff --git a/sdk/keyvault/Azure.Security.KeyVault.Secrets/tests/samples/SampleSnippets.cs b/sdk/keyvault/Azure.Security.KeyVault.Secrets/tests/samples/SampleSnippets.cs
@@ -251,6 +251,22 @@ private async Task MigrationGuide()
                 #endregion Snippet:Azure_Security_KeyVault_Secrets_Snippets_MigrationGuide_ListSecrets
             }
 
+            {
+                #region Snippet:Azure_Security_KeyVault_Secrets_Snippets_MigrationGuide_ListSecretVersions
+                // List all secrets asynchronously.
+                await foreach (SecretProperties item in client.GetPropertiesOfSecretVersionsAsync("secret-name"))
+                {
+                    KeyVaultSecret secret = await client.GetSecretAsync(item.Name, item.Version);
+                }
+
+                // List all secrets synchronously.
+                foreach (SecretProperties item in client.GetPropertiesOfSecretVersions("secret-name"))
+                {
+                    KeyVaultSecret secret = client.GetSecret(item.Name, item.Version);
+                }
+                #endregion Snippet:Azure_Security_KeyVault_Secrets_Snippets_MigrationGuide_ListSecretVersions
+            }
+
             {
                 #region Snippet:Azure_Security_KeyVault_Secrets_Snippets_MigrationGuide_DeleteSecret
                 // Delete the secret.

diff --git a/sdk/keyvault/Azure.Security.KeyVault.Secrets/tests/samples/Track1Snippets.cs b/sdk/keyvault/Azure.Security.KeyVault.Secrets/tests/samples/Track1Snippets.cs
@@ -65,6 +65,27 @@ private static async Task Track1MigrationGuide()
                 #endregion Snippet:Microsoft_Azure_KeyVault_Secrets_Snippets_MigrationGuide_ListSecrets
             }
 
+            {
+                #region Snippet:Microsoft_Azure_KeyVault_Secrets_Snippets_MigrationGuide_ListSecretVersions
+                IPage<SecretItem> page = await client.GetSecretVersionsAsync("https://myvault.vault.azure.net", "secret-name");
+                foreach (SecretItem item in page)
+                {
+                    SecretIdentifier secretId = item.Identifier;
+                    SecretBundle secret = await client.GetSecretAsync(secretId.Vault, secretId.Name, secretId.Version);
+                }
+
+                while (page.NextPageLink != null)
+                {
+                    page = await client.GetSecretVersionsNextAsync(page.NextPageLink);
+                    foreach (SecretItem item in page)
+                    {
+                        SecretIdentifier secretId = item.Identifier;
+                        SecretBundle secret = await client.GetSecretAsync(secretId.Vault, secretId.Name, secretId.Version);
+                    }
+                }
+                #endregion Snippet:Microsoft_Azure_KeyVault_Secrets_Snippets_MigrationGuide_ListSecretVersions
+            }
+
             {
                 #region Snippet:Microsoft_Azure_KeyVault_Secrets_Snippets_MigrationGuide_DeleteSecret
                 // Delete the secret.