Adding Snapshot References Feature

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/AzureAppConfigurationProvider.cs

@@ -3,6 +3,7 @@
 //
 using Azure;
 using Azure.Data.AppConfiguration;
+using Microsoft.Extensions.Configuration.AzureAppConfiguration.SnapshotReference;
 using Microsoft.Extensions.Configuration.AzureAppConfiguration.Extensions;
 using Microsoft.Extensions.Configuration.AzureAppConfiguration.Models;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
@@ -874,6 +875,31 @@ await CallWithRequestTracing(async () =>
 
                             foreach (ConfigurationSetting setting in page.Values)
                             {
+                                if (setting.ContentType == SnapshotReferenceConstants.ContentType)
+                                {
+                                    // Track snapshot reference usage for telemetry
+                                    if (_requestTracingEnabled && _requestTracingOptions != null)
+                                    {
+                                        _requestTracingOptions.UsesSnapshotReference = true;
+                                    }
+
+                                    SnapshotReference.SnapshotReference snapshotReference = SnapshotReferenceParser.Parse(setting);
+
+                                    Dictionary<string, ConfigurationSetting> resolvedSettings = await LoadSnapshotData(snapshotReference.SnapshotName, client, cancellationToken).ConfigureAwait(false);
+
+                                    if (_requestTracingEnabled && _requestTracingOptions != null)
+                                    {
+                                        _requestTracingOptions.UsesSnapshotReference = false;
+                                    }
+
+                                    foreach (KeyValuePair<string, ConfigurationSetting> resolvedSetting in resolvedSettings)
+                                    {
+                                        data[resolvedSetting.Key] = resolvedSetting.Value;
+                                    }
+
+                                    continue;
+                                }
+
                                 data[setting.Key] = setting;
 
                                 if (loadOption.IsFeatureFlagSelector)
@@ -899,37 +925,54 @@ await CallWithRequestTracing(async () =>
                 }
                 else
                 {
-                    ConfigurationSnapshot snapshot;
+                    Dictionary<string, ConfigurationSetting> resolvedSettings = await LoadSnapshotData(loadOption.SnapshotName, client, cancellationToken).ConfigureAwait(false);
 
-                    try
-                    {
-                        snapshot = await client.GetSnapshotAsync(loadOption.SnapshotName).ConfigureAwait(false);
-                    }
-                    catch (RequestFailedException rfe) when (rfe.Status == (int)HttpStatusCode.NotFound)
+                    foreach (KeyValuePair<string, ConfigurationSetting> resolvedSetting in resolvedSettings)
                     {
-                        throw new InvalidOperationException($"Could not find snapshot with name '{loadOption.SnapshotName}'.", rfe);
+                        data[resolvedSetting.Key] = resolvedSetting.Value;
                     }
+                }
+            }
 
-                    if (snapshot.SnapshotComposition != SnapshotComposition.Key)
-                    {
-                        throw new InvalidOperationException($"{nameof(snapshot.SnapshotComposition)} for the selected snapshot with name '{snapshot.Name}' must be 'key', found '{snapshot.SnapshotComposition}'.");
-                    }
+            return data;
+        }
 
-                    IAsyncEnumerable<ConfigurationSetting> settingsEnumerable = client.GetConfigurationSettingsForSnapshotAsync(
-                        loadOption.SnapshotName,
-                        cancellationToken);
+        private async Task<Dictionary<string, ConfigurationSetting>> LoadSnapshotData(string snapshotName, ConfigurationClient client, CancellationToken cancellationToken)
+        {
+            var resolvedSettings = new Dictionary<string, ConfigurationSetting>();
 
-                    await CallWithRequestTracing(async () =>
-                    {
-                        await foreach (ConfigurationSetting setting in settingsEnumerable.ConfigureAwait(false))
-                        {
-                            data[setting.Key] = setting;
-                        }
-                    }).ConfigureAwait(false);
-                }
+            Debug.Assert(!string.IsNullOrWhiteSpace(snapshotName));
+
+            ConfigurationSnapshot snapshot = null;
+
+            try
+            {
+                await CallWithRequestTracing(async () => snapshot = await client.GetSnapshotAsync(snapshotName, cancellationToken: cancellationToken).ConfigureAwait(false)).ConfigureAwait(false);
             }
+            catch (RequestFailedException rfe) when (rfe.Status == (int)HttpStatusCode.NotFound)
+            {
 
-            return data;
+                return resolvedSettings; // Return empty dictionary if snapshot not found
+            }
+
+            if (snapshot.SnapshotComposition != SnapshotComposition.Key)
+            {
+                throw new InvalidOperationException(string.Format(ErrorMessages.SnapshotInvalidComposition, nameof(snapshot.SnapshotComposition), snapshot.Name, snapshot.SnapshotComposition));
+            }
+
+            IAsyncEnumerable<ConfigurationSetting> settingsEnumerable = client.GetConfigurationSettingsForSnapshotAsync(
+                snapshotName,
+                cancellationToken);
+
+            await CallWithRequestTracing(async () =>
+            {
+                await foreach (ConfigurationSetting setting in settingsEnumerable.WithCancellation(cancellationToken).ConfigureAwait(false))
+                {
+                    resolvedSettings[setting.Key] = setting;
+                }
+            }).ConfigureAwait(false);
+
+            return resolvedSettings;
         }
 
         private async Task<Dictionary<KeyValueIdentifier, ConfigurationSetting>> LoadKeyValuesRegisteredForRefresh(
@@ -969,7 +1012,33 @@ private async Task<Dictionary<KeyValueIdentifier, ConfigurationSetting>> LoadKey
                 if (watchedKv != null)
                 {
                     watchedIndividualKvs[watchedKeyLabel] = new ConfigurationSetting(watchedKv.Key, watchedKv.Value, watchedKv.Label, watchedKv.ETag);
-                    existingSettings[watchedKey] = watchedKv;
+
+                    if (watchedKv.ContentType == SnapshotReferenceConstants.ContentType)
+                    {
+                        // Track snapshot reference usage for telemetry
+                        if (_requestTracingEnabled && _requestTracingOptions != null)
+                        {
+                            _requestTracingOptions.UsesSnapshotReference = true;
+                        }
+
+                        SnapshotReference.SnapshotReference snapshotReference = SnapshotReferenceParser.Parse(watchedKv);
+
+                        Dictionary<string, ConfigurationSetting> resolvedSettings = await LoadSnapshotData(snapshotReference.SnapshotName, client, cancellationToken).ConfigureAwait(false);
+
+                        if (_requestTracingEnabled && _requestTracingOptions != null)
+                        {
+                            _requestTracingOptions.UsesSnapshotReference = false;
+                        }
+
+                        foreach (KeyValuePair<string, ConfigurationSetting> resolvedSetting in resolvedSettings)
+                        {
+                            existingSettings[resolvedSetting.Key] = resolvedSetting.Value;
+                        }
+                    }
+                    else
+                    {
+                        existingSettings[watchedKey] = watchedKv;
+                    }
                 }
             }
 
@@ -1034,7 +1103,8 @@ await CallWithRequestTracing(
                     logInfoBuilder.AppendLine(LogHelper.BuildKeyValueSettingUpdatedMessage(change.Key));
                     keyValueChanges.Add(change);
 
-                    if (kvWatcher.RefreshAll)
+                    // If the watcher is set to refresh all, or the content type matches the snapshot reference content type then refresh all
+                    if (kvWatcher.RefreshAll || watchedKv.ContentType == SnapshotReferenceConstants.ContentType)
                     {
                         return true;
                     }

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/Constants/ErrorMessages.cs

@@ -10,5 +10,9 @@ internal class ErrorMessages
         public const string FeatureFlagInvalidJsonProperty = "Invalid property '{0}' for feature flag. Key: '{1}'. Found type: '{2}'. Expected type: '{3}'.";
         public const string FeatureFlagInvalidFormat = "Invalid json format for feature flag. Key: '{0}'.";
         public const string InvalidKeyVaultReference = "Invalid Key Vault reference.";
+        public const string SnapshotReferenceInvalidFormat = "Invalid snapshot reference format for key '{0}' (label: '{1}').";
+        public const string SnapshotReferenceInvalidJsonProperty = "Invalid snapshot reference format for key '{0}' (label: '{1}'). The '{2}' property must be a string value, but found {3}.";
+        public const string SnapshotReferencePropertyMissing = "Invalid snapshot reference format for key '{0}' (label: '{1}'). The '{2}' property is required.";
+        public const string SnapshotInvalidComposition = "{0} for the selected snapshot with name '{1}' must be 'key', found '{2}'.";
     }
 }

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/Constants/RequestTracingConstants.cs

@@ -33,7 +33,7 @@ internal class RequestTracingConstants
         public const string LoadBalancingEnabledTag = "LB";
         public const string AIConfigurationTag = "AI";
         public const string AIChatCompletionConfigurationTag = "AICC";
-
+        public const string SnapshotReferenceTag = "SnapshotRef";
         public const string SignalRUsedTag = "SignalR";
         public const string FailoverRequestTag = "Failover";
         public const string PushRefreshTag = "PushRefresh";

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/RequestTracingOptions.cs

@@ -3,6 +3,7 @@
 //
 using Microsoft.Extensions.Configuration.AzureAppConfiguration.Extensions;
 using Microsoft.Extensions.Configuration.AzureAppConfiguration.FeatureManagement;
+using Microsoft.Extensions.Configuration.AzureAppConfiguration.SnapshotReference;
 using System.Net.Mime;
 using System.Text;
 
@@ -87,6 +88,11 @@ internal class RequestTracingOptions
         /// </summary>
         public bool UsesAIChatCompletionConfiguration { get; set; } = false;
 
+        /// <summary>
+        /// Flag to indicate whether any key-value uses snapshot references.
+        /// </summary>
+        public bool UsesSnapshotReference { get; set; } = false;
+
         /// <summary>
         /// Resets the AI configuration tracing flags.
         /// </summary>
@@ -125,7 +131,8 @@ public bool UsesAnyTracingFeature()
             return IsLoadBalancingEnabled ||
                 IsSignalRUsed ||
                 UsesAIConfiguration ||
-                UsesAIChatCompletionConfiguration;
+                UsesAIChatCompletionConfiguration ||
+                UsesSnapshotReference;
         }
 
         /// <summary>
@@ -176,6 +183,16 @@ public string CreateFeaturesString()
                 sb.Append(RequestTracingConstants.AIChatCompletionConfigurationTag);
             }
 
+            if (UsesSnapshotReference)
+            {
+                if (sb.Length > 0)
+                {
+                    sb.Append(RequestTracingConstants.Delimiter);
+                }
+
+                sb.Append(RequestTracingConstants.SnapshotReferenceTag);
+            }
+
             return sb.ToString();
         }
     }

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/SnapshotReference/JsonFields.cs

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+namespace Microsoft.Extensions.Configuration.AzureAppConfiguration.SnapshotReference
+{
+    internal static class JsonFields
+    {
+        public const string SnapshotName = "snapshot_name";
+    }
+}

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/SnapshotReference/SnapshotReference.cs

@@ -0,0 +1,11 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+
+namespace Microsoft.Extensions.Configuration.AzureAppConfiguration.SnapshotReference
+{
+    internal class SnapshotReference
+    {
+        public string SnapshotName { get; set; }
+    }
+}

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/SnapshotReference/SnapshotReferenceConstants.cs

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+namespace Microsoft.Extensions.Configuration.AzureAppConfiguration.SnapshotReference
+{
+    internal class SnapshotReferenceConstants
+    {
+        public const string ContentType = "application/json; profile=\"https://azconfig.io/mime-profiles/snapshot-ref\"; charset=utf-8";
+    }
+}

src/Microsoft.Extensions.Configuration.AzureAppConfiguration/SnapshotReference/SnapshotReferenceParser.cs

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using Azure.Data.AppConfiguration;
+using System;
+using System.Text.Json;
+
+namespace Microsoft.Extensions.Configuration.AzureAppConfiguration.SnapshotReference
+{
+    /// <summary>
+    /// Provides parsing functionality for snapshot reference configuration settings.
+    /// </summary>
+    internal static class SnapshotReferenceParser
+    {
+        /// <summary>
+        /// Parses a snapshot name from a configuration setting containing snapshot reference JSON.
+        /// </summary>
+        /// <param name="setting">The configuration setting containing the snapshot reference JSON.</param>
+        /// <returns>The snapshot reference containing a valid, non-empty snapshot name.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when the setting is null.</exception>
+        /// <exception cref="FormatException">Thrown when the setting contains invalid JSON, invalid snapshot reference format, or empty/whitespace snapshot name.</exception>
+        public static SnapshotReference Parse(ConfigurationSetting setting)
+        {
+            if (setting == null)
+            {
+                throw new ArgumentNullException(nameof(setting));
+            }
+
+            if (string.IsNullOrWhiteSpace(setting.Value))
+            {
+                throw new FormatException(string.Format(ErrorMessages.SnapshotReferenceInvalidFormat, setting.Key, setting.Label));
+            }
+
+            try
+            {
+                var reader = new Utf8JsonReader(System.Text.Encoding.UTF8.GetBytes(setting.Value));
+
+                if (reader.Read() && reader.TokenType != JsonTokenType.StartObject)
+                {
+                    throw new FormatException(string.Format(ErrorMessages.SnapshotReferenceInvalidFormat, setting.Key, setting.Label));
+                }
+
+                while (reader.Read() && reader.TokenType != JsonTokenType.EndObject)
+                {
+                    if (reader.TokenType != JsonTokenType.PropertyName)
+                    {
+                        continue;
+                    }
+
+                    if (reader.GetString() == JsonFields.SnapshotName)
+                    {
+                        if (reader.Read() && reader.TokenType == JsonTokenType.String)
+                        {
+                            string snapshotName = reader.GetString();
+                            if (string.IsNullOrWhiteSpace(snapshotName))
+                            {
+                                throw new FormatException(string.Format(ErrorMessages.SnapshotReferenceInvalidFormat, setting.Key, setting.Label));
+                            }
+
+                            return new SnapshotReference { SnapshotName = snapshotName };
+                        }
+
+                        throw new FormatException(string.Format(ErrorMessages.SnapshotReferenceInvalidJsonProperty, setting.Key, setting.Label, JsonFields.SnapshotName, reader.TokenType));
+                    }
+
+                    // Skip unknown properties
+                    reader.Skip();
+                }
+
+                throw new FormatException(string.Format(ErrorMessages.SnapshotReferencePropertyMissing, setting.Key, setting.Label, JsonFields.SnapshotName));
+            }
+            catch (JsonException jsonEx)
+            {
+                throw new FormatException(string.Format(ErrorMessages.SnapshotReferenceInvalidFormat, setting.Key, setting.Label), jsonEx);
+            }
+        }
+    }
+}