Add Legacy FileLocationOption for cache directory selection (#1117)

* Add FileLocationOption for cache directory selection

Introduces the FileLocationOption enum to allow selection between default and legacy cache directory locations. Updates AkavacheBuilder, IAkavacheBuilder, and related initialization methods to support this option. Adjusts cache directory resolution logic in both core and Sqlite3 extensions to respect the selected file location option.

* Add FileLocationOption support to AkavacheBuilder

AkavacheBuilder now accepts a FileLocationOption parameter to control cache directory selection. The SettingsCachePath property uses this option to determine whether to use the legacy or isolated cache directory. Exposes the selected FileLocationOption via a new property.

Author: ChrisPulman

src/Akavache.Core/AkavacheBuilderExtensions.cs

@@ -5,6 +5,8 @@
 
 #if NET6_0_OR_GREATER
 using System.Diagnostics.CodeAnalysis;
+using System.IO;
+
 #endif
 using System.IO.IsolatedStorage;
 using System.Reflection;
@@ -412,4 +414,129 @@ public static IAkavacheBuilder WithInMemory(this IAkavacheBuilder builder)
 
         return cachePath;
     }
+
+    /// <summary>
+    /// Gets the legacy cache directory.
+    /// </summary>
+    /// <param name="builder">The builder.</param>
+    /// <param name="cacheName">Name of the cache.</param>
+    /// <returns>The Legacy cache path.</returns>
+    /// <exception cref="System.ArgumentNullException">builder.</exception>
+    /// <exception cref="System.ArgumentException">
+    /// Cache name cannot be null or empty. - cacheName
+    /// or
+    /// Application name cannot be null or empty. - ApplicationName.
+    /// </exception>
+    public static string? GetLegacyCacheDirectory(this IAkavacheInstance builder, string cacheName)
+    {
+        if (builder == null)
+        {
+            throw new ArgumentNullException(nameof(builder));
+        }
+
+        if (string.IsNullOrWhiteSpace(cacheName))
+        {
+            throw new ArgumentException("Cache name cannot be null or empty.", nameof(cacheName));
+        }
+
+        if (string.IsNullOrWhiteSpace(builder.ApplicationName))
+        {
+            throw new ArgumentException("Application name cannot be null or empty.", nameof(builder.ApplicationName));
+        }
+
+#if ANDROID
+        switch (cacheName)
+        {
+            case "LocalMachine":
+                return Application.Context.CacheDir?.AbsolutePath;
+            case "Secure":
+                var path = Application.Context.FilesDir?.AbsolutePath;
+
+                if (path is null)
+                {
+                    return null;
+                }
+
+                var di = new DirectoryInfo(Path.Combine(path, "Secret"));
+                if (!di.Exists)
+                {
+                    di.CreateRecursive();
+                }
+
+                return di.FullName;
+            default:
+                // Use the cache directory for UserAccount and SettingsCache caches
+                return Application.Context.FilesDir?.AbsolutePath;
+        }
+#elif IOS || MACCATALYST
+        return cacheName switch
+        {
+            "LocalMachine" => (string)CreateAppDirectory(NSSearchPathDirectory.CachesDirectory, builder.ApplicationName, "BlobCache"),
+            "Secure" => (string)CreateAppDirectory(NSSearchPathDirectory.ApplicationSupportDirectory, builder.ApplicationName, "SecretCache"),
+            _ => (string)CreateAppDirectory(NSSearchPathDirectory.ApplicationSupportDirectory, builder.ApplicationName, "BlobCache"),
+        };
+#else
+        return cacheName switch
+        {
+            "LocalMachine" => Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), builder.ApplicationName, "BlobCache"),
+            "Secure" => Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), builder.ApplicationName, "SecretCache"),
+            _ => Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), builder.ApplicationName, "BlobCache"),
+        };
+#endif
+    }
+
+    internal static void CreateRecursive(this DirectoryInfo directoryInfo) =>
+        _ = directoryInfo.SplitFullPath().Aggregate((parent, dir) =>
+        {
+            var path = Path.Combine(parent, dir);
+
+            if (!Directory.Exists(path))
+            {
+                Directory.CreateDirectory(path);
+            }
+
+            return path;
+        });
+
+    internal static IEnumerable<string> SplitFullPath(this DirectoryInfo directoryInfo)
+    {
+        var root = Path.GetPathRoot(directoryInfo.FullName);
+        var components = new List<string>();
+        for (var path = directoryInfo.FullName; path != root && path is not null; path = Path.GetDirectoryName(path))
+        {
+            var filename = Path.GetFileName(path);
+            if (string.IsNullOrEmpty(filename))
+            {
+                continue;
+            }
+
+            components.Add(filename);
+        }
+
+        if (root is not null)
+        {
+            components.Add(root);
+        }
+
+        components.Reverse();
+        return components;
+    }
+
+#if IOS || MACCATALYST
+    private static string CreateAppDirectory(NSSearchPathDirectory targetDir, string applicationName, string subDir = "BlobCache")
+    {
+        using var fm = new NSFileManager();
+        var url = fm.GetUrl(targetDir, NSSearchPathDomain.All, null, true, out _) ?? throw new DirectoryNotFoundException();
+        var rp = url.RelativePath ?? throw new DirectoryNotFoundException();
+        var ret = Path.Combine(rp, applicationName, subDir);
+
+        var di = new DirectoryInfo(ret);
+        if (!di.Exists)
+        {
+            di.CreateRecursive();
+        }
+
+        return ret;
+    }
+#endif
 }

src/Akavache.Core/CacheDatabase.cs

@@ -142,15 +142,14 @@ public static IObservable<Unit> Shutdown()
     /// </summary>
     /// <typeparam name="T">The serializer.</typeparam>
     /// <param name="applicationName">The application name for cache directories. If null, uses the current ApplicationName.</param>
+    /// <param name="fileLocationOption">The file location option.</param>
     /// <exception cref="InvalidOperationException">Failed to create AkavacheBuilder instance.</exception>
 #if NET6_0_OR_GREATER
-
     [RequiresUnreferencedCode("Serializers require types to be preserved for serialization.")]
-    public static void Initialize<T>(string? applicationName = null)
-#else
-    public static void Initialize<T>(string? applicationName = null)
 #endif
-       where T : ISerializer, new() => SetBuilder(CreateBuilder()
+    public static void Initialize<T>(string? applicationName = null, FileLocationOption fileLocationOption = FileLocationOption.Default)
+
+       where T : ISerializer, new() => SetBuilder(CreateBuilder(fileLocationOption)
             .WithApplicationName(applicationName)
             .WithSerializer<T>()
             .WithInMemoryDefaults()
@@ -163,15 +162,12 @@ public static void Initialize<T>(string? applicationName = null)
     /// <typeparam name="T">The serializer.</typeparam>
     /// <param name="configureSerializer">The Serializer configuration.</param>
     /// <param name="applicationName">The application name for cache directories. If null, uses the current ApplicationName.</param>
-    /// <exception cref="InvalidOperationException">Failed to create AkavacheBuilder instance.</exception>
+    /// <param name="fileLocationOption">The file location option.</param>
 #if NET6_0_OR_GREATER
-
     [RequiresUnreferencedCode("Serializers require types to be preserved for serialization.")]
-    public static void Initialize<T>(Func<T> configureSerializer, string? applicationName = null)
-#else
-    public static void Initialize<T>(Func<T> configureSerializer, string? applicationName = null)
 #endif
-       where T : ISerializer, new() => SetBuilder(CreateBuilder()
+    public static void Initialize<T>(Func<T> configureSerializer, string? applicationName = null, FileLocationOption fileLocationOption = FileLocationOption.Default)
+       where T : ISerializer, new() => SetBuilder(CreateBuilder(fileLocationOption)
             .WithApplicationName(applicationName)
             .WithSerializer(configureSerializer)
             .WithInMemoryDefaults()
@@ -183,22 +179,19 @@ public static void Initialize<T>(Func<T> configureSerializer, string? applicatio
     /// <typeparam name="T">The serializer.</typeparam>
     /// <param name="configure">An action to configure the Akavache builder.</param>
     /// <param name="applicationName">Name of the application.</param>
-    /// <exception cref="ArgumentNullException">configure.</exception>
+    /// <param name="fileLocationOption">The file location option.</param>
 #if NET6_0_OR_GREATER
-
     [RequiresUnreferencedCode("Serializers require types to be preserved for serialization.")]
-    public static void Initialize<T>(Action<IAkavacheBuilder> configure, string? applicationName = null)
-#else
-    public static void Initialize<T>(Action<IAkavacheBuilder> configure, string? applicationName = null)
 #endif
+    public static void Initialize<T>(Action<IAkavacheBuilder> configure, string? applicationName = null, FileLocationOption fileLocationOption = FileLocationOption.Default)
         where T : ISerializer, new()
     {
         if (configure == null)
         {
             throw new ArgumentNullException(nameof(configure));
         }
 
-        var builder = CreateBuilder()
+        var builder = CreateBuilder(fileLocationOption)
             .WithApplicationName(applicationName)
             .WithSerializer<T>();
 
@@ -214,22 +207,19 @@ public static void Initialize<T>(Action<IAkavacheBuilder> configure, string? app
     /// <param name="configureSerializer">The Serializer configuration.</param>
     /// <param name="configure">An action to configure the Akavache builder.</param>
     /// <param name="applicationName">Name of the application.</param>
-    /// <exception cref="ArgumentNullException">configure.</exception>
+    /// <param name="fileLocationOption">The file location option.</param>
 #if NET6_0_OR_GREATER
-
     [RequiresUnreferencedCode("Serializers require types to be preserved for serialization.")]
-    public static void Initialize<T>(Func<T> configureSerializer, Action<IAkavacheBuilder> configure, string? applicationName = null)
-#else
-    public static void Initialize<T>(Func<T> configureSerializer, Action<IAkavacheBuilder> configure, string? applicationName = null)
 #endif
+    public static void Initialize<T>(Func<T> configureSerializer, Action<IAkavacheBuilder> configure, string? applicationName = null, FileLocationOption fileLocationOption = FileLocationOption.Default)
         where T : ISerializer, new()
     {
         if (configure == null)
         {
             throw new ArgumentNullException(nameof(configure));
         }
 
-        var builder = CreateBuilder()
+        var builder = CreateBuilder(fileLocationOption)
             .WithApplicationName(applicationName)
             .WithSerializer(configureSerializer);
 
@@ -241,8 +231,11 @@ public static void Initialize<T>(Func<T> configureSerializer, Action<IAkavacheBu
     /// <summary>
     /// Creates a new Akavache builder for configuration.
     /// </summary>
-    /// <returns>A new Akavache builder instance.</returns>
-    public static IAkavacheBuilder CreateBuilder() => new AkavacheBuilder();
+    /// <param name="fileLocationOption">The file location option.</param>
+    /// <returns>
+    /// A new Akavache builder instance.
+    /// </returns>
+    public static IAkavacheBuilder CreateBuilder(FileLocationOption fileLocationOption = FileLocationOption.Default) => new AkavacheBuilder(fileLocationOption);
 
     /// <summary>
     /// Internal method to set the builder instance. Used by the builder pattern.

src/Akavache.Core/Core/AkavacheBuilder.cs

@@ -18,10 +18,12 @@ internal class AkavacheBuilder : IAkavacheBuilder
 {
     private static readonly object _lock = new();
     private string? _settingsCachePath;
+    private FileLocationOption _fileLocationOption;
 
     [SuppressMessage("ExecutingAssembly.Location", "IL3000:String may be null", Justification = "Handled.")]
-    public AkavacheBuilder()
+    public AkavacheBuilder(FileLocationOption fileLocationOption = FileLocationOption.Default)
     {
+        _fileLocationOption = fileLocationOption;
         try
         {
             ExecutingAssemblyName = ExecutingAssembly.FullName!.Split(',')[0];
@@ -73,7 +75,11 @@ public string? SettingsCachePath
             // Lazy computation to ensure ApplicationName is properly set via WithApplicationName()
             if (_settingsCachePath == null)
             {
-                _settingsCachePath = this.GetIsolatedCacheDirectory("SettingsCache");
+                _settingsCachePath = _fileLocationOption switch
+                {
+                    FileLocationOption.Legacy => this.GetLegacyCacheDirectory("SettingsCache"),
+                    _ => this.GetIsolatedCacheDirectory("SettingsCache"),
+                };
             }
 
             return _settingsCachePath;
@@ -119,6 +125,14 @@ public string? SettingsCachePath
     /// </value>
     public string? SerializerTypeName { get; internal set; }
 
+    /// <summary>
+    /// Gets the file location option.
+    /// </summary>
+    /// <value>
+    /// The file location option.
+    /// </value>
+    public FileLocationOption FileLocationOption => _fileLocationOption;
+
     internal static Dictionary<string, IBlobCache?>? BlobCaches { get; set; } = [];
 
     internal static Dictionary<string, ISettingsStorage?>? SettingsStores { get; set; } = [];

src/Akavache.Core/Core/FileLocationOption.cs

@@ -0,0 +1,22 @@
+// Copyright (c) 2025 .NET Foundation and Contributors. All rights reserved.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for full license information.
+
+namespace Akavache.Core
+{
+    /// <summary>
+    /// File Location Option.
+    /// </summary>
+    public enum FileLocationOption
+    {
+        /// <summary>
+        /// Use the default location for the platform.
+        /// </summary>
+        Default,
+        /// <summary>
+        /// Use the legacy location, if available on the platform.
+        /// </summary>
+        Legacy,
+    }
+}

src/Akavache.Core/IAkavacheBuilder.cs

@@ -3,6 +3,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for full license information.
 
+using Akavache.Core;
 #if NET6_0_OR_GREATER
 using System.Diagnostics.CodeAnalysis;
 #endif
@@ -14,6 +15,14 @@ namespace Akavache;
 /// </summary>
 public interface IAkavacheBuilder : IAkavacheInstance
 {
+    /// <summary>
+    /// Gets the file location option.
+    /// </summary>
+    /// <value>
+    /// The file location option.
+    /// </value>
+    FileLocationOption FileLocationOption { get; }
+
     /// <summary>
     /// Sets the application name for cache directory paths.
     /// </summary>

src/Akavache.Sqlite3/AkavacheBuilderExtensions.cs

@@ -150,7 +150,12 @@ private static SqliteBlobCache CreateSqliteCache(string name, IAkavacheBuilder b
         // Validate cache name to prevent path traversal attacks
         var validatedName = SecurityUtilities.ValidateCacheName(name, nameof(name));
 
-        var directory = builder.GetIsolatedCacheDirectory(validatedName);
+        // Determine the cache directory
+        var directory = builder.FileLocationOption switch
+        {
+            FileLocationOption.Legacy => builder.GetLegacyCacheDirectory(validatedName),
+            _ => builder.GetIsolatedCacheDirectory(validatedName),
+        };
         if (string.IsNullOrWhiteSpace(directory))
         {
             throw new InvalidOperationException("Failed to determine a valid cache directory.");