v14: Add async methods to Deploy interfaces

src/Umbraco.Core/Deploy/IContextCache.cs

@@ -24,6 +24,35 @@ public interface IContextCache
     /// </returns>
     T? GetOrCreate<T>(string key, Func<T?> factory);
 
+    /// <summary>
+    /// Gets an item from the context cache or creates and stores it using the specified <paramref name="key" />.
+    /// </summary>
+    /// <typeparam name="T">The type of the cached item.</typeparam>
+    /// <param name="key">The key of the cached item.</param>
+    /// <param name="factory">The factory method to create the item (if it doesn't exist yet).</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains the item.
+    /// </returns>
+    async Task<T?> GetOrCreateAsync<T>(string key, Func<Task<T?>> factory)
+    {
+        // TODO: Remove default implementation in v15
+        bool shouldCreate = false;
+        T? value = GetOrCreate<T>(key, () =>
+        {
+            shouldCreate = true;
+            return default;
+        });
+
+        if (shouldCreate)
+        {
+            // Only invoke and await if we need to create the value
+            value = await factory().ConfigureAwait(false);
+            Create(key, value);
+        }
+
+        return value;
+    }
+
     /// <summary>
     /// Clears all cached items on this context.
     /// </summary>

src/Umbraco.Core/Deploy/IDataTypeConfigurationConnector.cs

@@ -3,11 +3,11 @@
 namespace Umbraco.Cms.Core.Deploy;
 
 /// <summary>
-/// Defines methods that can convert data type configuration to / from an environment-agnostic string.
+/// Defines methods that can convert data type configuration to and from an environment-agnostic string.
 /// </summary>
 /// <remarks>
-/// Configuration may contain values such as content identifiers, that would be local
-/// to one environment, and need to be converted in order to be deployed.
+/// Configuration may contain values such as content identifiers, that would be local to one environment, and need to be converted in order to be deployed.
+/// It can also contain references to other deployable artifacts, that need to be tracked as dependencies.
 /// </remarks>
 public interface IDataTypeConfigurationConnector
 {
@@ -28,8 +28,24 @@ public interface IDataTypeConfigurationConnector
     /// <returns>
     /// The artifact configuration value.
     /// </returns>
+    [Obsolete("Use ToArtifactAsync() instead. This method will be removed in a future version.")]
     string? ToArtifact(IDataType dataType, ICollection<ArtifactDependency> dependencies, IContextCache contextCache);
 
+    /// <summary>
+    /// Gets the artifact configuration value corresponding to a data type configuration and gather dependencies.
+    /// </summary>
+    /// <param name="dataType">The data type.</param>
+    /// <param name="dependencies">The dependencies.</param>
+    /// <param name="contextCache">The context cache.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains the artifact configuration value.
+    /// </returns>
+    Task<string?> ToArtifactAsync(IDataType dataType, ICollection<ArtifactDependency> dependencies, IContextCache contextCache, CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => Task.FromResult(ToArtifact(dataType, dependencies, contextCache)); // TODO: Remove default implementation in v15
+#pragma warning restore CS0618 // Type or member is obsolete
+
     /// <summary>
     /// Gets the data type configuration corresponding to an artifact configuration value.
     /// </summary>
@@ -39,5 +55,21 @@ public interface IDataTypeConfigurationConnector
     /// <returns>
     /// The data type configuration.
     /// </returns>
+    [Obsolete("Use FromArtifactAsync() instead. This method will be removed in a future version.")]
     IDictionary<string, object> FromArtifact(IDataType dataType, string? configuration, IContextCache contextCache);
+
+    /// <summary>
+    /// Gets the data type configuration corresponding to an artifact configuration value.
+    /// </summary>
+    /// <param name="dataType">The data type.</param>
+    /// <param name="configuration">The artifact configuration value.</param>
+    /// <param name="contextCache">The context cache.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains the data type configuration.
+    /// </returns>
+    Task<IDictionary<string, object>> FromArtifactAsync(IDataType dataType, string? configuration, IContextCache contextCache, CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => Task.FromResult(FromArtifact(dataType, configuration, contextCache)); // TODO: Remove default implementation in v15
+#pragma warning restore CS0618 // Type or member is obsolete
 }

src/Umbraco.Core/Deploy/IFileSource.cs

@@ -17,6 +17,7 @@ public interface IFileSource
     /// <para>Returns null if no content could be read.</para>
     /// <para>The caller should ensure that the stream is properly closed/disposed.</para>
     /// </remarks>
+    [Obsolete("Use GetFileStreamAsync() instead. This method will be removed in a future version.")]
     Stream GetFileStream(StringUdi udi);
 
     /// <summary>
@@ -43,6 +44,7 @@ public interface IFileSource
     /// <remarks>
     /// Returns null if no content could be read.
     /// </remarks>
+    [Obsolete("Use GetFileContentAsync() instead. This method will be removed in a future version.")]
     string GetFileContent(StringUdi udi);
 
     /// <summary>
@@ -65,6 +67,7 @@ public interface IFileSource
     /// <returns>
     /// The length of the file, or -1 if the file does not exist.
     /// </returns>
+    [Obsolete("Use GetFileLengthAsync() instead. This method will be removed in a future version.")]
     long GetFileLength(StringUdi udi);
 
     /// <summary>
@@ -83,6 +86,7 @@ public interface IFileSource
     /// <param name="udis">The UDIs of the files to get.</param>
     /// <param name="continueOnFileNotFound">A flag indicating whether to continue if a file isn't found or to stop and throw a FileNotFoundException.</param>
     /// <param name="fileTypes">A collection of file types which can store the files.</param>
+    [Obsolete("Use GetFilesAsync() instead. This method will be removed in a future version.")]
     void GetFiles(IEnumerable<StringUdi> udis, bool continueOnFileNotFound, IFileTypeCollection fileTypes);
 
     /// <summary>

src/Umbraco.Core/Deploy/IFileType.cs

@@ -20,6 +20,7 @@ public interface IFileType
     /// <returns>
     /// The stream.
     /// </returns>
+    [Obsolete("Use GetStreamAsync() instead. This method will be removed in a future version.")]
     Stream GetStream(StringUdi udi);
 
     /// <summary>
@@ -55,6 +56,7 @@ public interface IFileType
     /// </summary>
     /// <param name="udi">The UDI.</param>
     /// <param name="stream">The stream.</param>
+    [Obsolete("Use SetStreamAsync() instead. This method will be removed in a future version.")]
     void SetStream(StringUdi udi, Stream stream);
 
     /// <summary>

src/Umbraco.Core/Deploy/IImageSourceParser.cs

@@ -17,8 +17,27 @@ public interface IImageSourceParser
     /// <remarks>
     /// Turns src="/media/..." into src="umb://media/..." and adds the corresponding udi to the dependencies.
     /// </remarks>
+    [Obsolete("Use ToArtifactAsync() instead. This method will be removed in a future version.")]
     string ToArtifact(string value, ICollection<Udi> dependencies, IContextCache contextCache);
 
+    /// <summary>
+    /// Parses an Umbraco property value and produces an artifact property value.
+    /// </summary>
+    /// <param name="value">The property value.</param>
+    /// <param name="dependencies">A list of dependencies.</param>
+    /// <param name="contextCache">The context cache.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains the parsed value.
+    /// </returns>
+    /// <remarks>
+    /// Turns src="/media/..." into src="umb://media/..." and adds the corresponding udi to the dependencies.
+    /// </remarks>
+    Task<string> ToArtifactAsync(string value, ICollection<Udi> dependencies, IContextCache contextCache, CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => Task.FromResult(ToArtifact(value, dependencies, contextCache)); // TODO: Remove default implementation in v15
+#pragma warning restore CS0618 // Type or member is obsolete
+
     /// <summary>
     /// Parses an artifact property value and produces an Umbraco property value.
     /// </summary>
@@ -30,5 +49,23 @@ public interface IImageSourceParser
     /// <remarks>
     /// Turns umb://media/... into /media/....
     /// </remarks>
+    [Obsolete("Use FromArtifactAsync() instead. This method will be removed in a future version.")]
     string FromArtifact(string value, IContextCache contextCache);
+
+    /// <summary>
+    /// Parses an artifact property value and produces an Umbraco property value.
+    /// </summary>
+    /// <param name="value">The artifact property value.</param>
+    /// <param name="contextCache">The context cache.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains the parsed value.
+    /// </returns>
+    /// <remarks>
+    /// Turns umb://media/... into /media/....
+    /// </remarks>
+    Task<string> FromArtifactAsync(string value, IContextCache contextCache, CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => Task.FromResult(FromArtifact(value, contextCache)); // TODO: Remove default implementation in v15
+#pragma warning restore CS0618 // Type or member is obsolete
 }

src/Umbraco.Core/Deploy/ILocalLinkParser.cs

@@ -15,11 +15,29 @@ public interface ILocalLinkParser
     /// The parsed value.
     /// </returns>
     /// <remarks>
-    /// Turns {{localLink:1234}} into {{localLink:umb://{type}/{id}}} and adds the corresponding udi to the
-    /// dependencies.
+    /// Turns {{localLink:1234}} into {{localLink:umb://{type}/{id}}} and adds the corresponding udi to the dependencies.
     /// </remarks>
+    [Obsolete("Use ToArtifactAsync() instead. This method will be removed in a future version.")]
     string ToArtifact(string value, ICollection<Udi> dependencies, IContextCache contextCache);
 
+    /// <summary>
+    /// Parses an Umbraco property value and produces an artifact property value.
+    /// </summary>
+    /// <param name="value">The property value.</param>
+    /// <param name="dependencies">A list of dependencies.</param>
+    /// <param name="contextCache">The context cache.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains the parsed value.
+    /// </returns>
+    /// <remarks>
+    /// Turns {{localLink:1234}} into {{localLink:umb://{type}/{id}}} and adds the corresponding udi to the dependencies.
+    /// </remarks>
+    Task<string> ToArtifactAsync(string value, ICollection<Udi> dependencies, IContextCache contextCache, CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => Task.FromResult(ToArtifact(value, dependencies, contextCache)); // TODO: Remove default implementation in v15
+#pragma warning restore CS0618 // Type or member is obsolete
+
     /// <summary>
     /// Parses an artifact property value and produces an Umbraco property value.
     /// </summary>
@@ -31,5 +49,23 @@ public interface ILocalLinkParser
     /// <remarks>
     /// Turns {{localLink:umb://{type}/{id}}} into {{localLink:1234}}.
     /// </remarks>
+    [Obsolete("Use FromArtifactAsync() instead. This method will be removed in a future version.")]
     string FromArtifact(string value, IContextCache contextCache);
+
+    /// <summary>
+    /// Parses an artifact property value and produces an Umbraco property value.
+    /// </summary>
+    /// <param name="value">The artifact property value.</param>
+    /// <param name="contextCache">The context cache.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains the parsed value.
+    /// </returns>
+    /// <remarks>
+    /// Turns {{localLink:umb://{type}/{id}}} into {{localLink:1234}}.
+    /// </remarks>
+    Task<string> FromArtifactAsync(string value, IContextCache contextCache, CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => Task.FromResult(FromArtifact(value, contextCache)); // TODO: Remove default implementation in v15
+#pragma warning restore CS0618 // Type or member is obsolete
 }