Skip to content

Replace [Obsolete] with [Experimental] attributes #1487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed

Replace [Obsolete] with [Experimental] attributes #1487

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1ebd68b
Replaced use of [Obsolete] to mark preview functionality with the [Re…
WhitWaldo Mar 17, 2025
126be52
Replaced use of [Experimental] attribute with [RequiresPreviewFeatures]
WhitWaldo Mar 17, 2025
64a420d
Swapped over all [RequiresPreviewFeature] attributes to use [Experime…
WhitWaldo Mar 18, 2025
330d697
Removed all unused usings following switch to [Experimental]
WhitWaldo Mar 18, 2025
13c0786
Updated solution to use [Experimental] attribute instead of [Obsolete…
WhitWaldo Mar 27, 2025
b842896
Inadvertently added several projects from other branches to this one
WhitWaldo Mar 27, 2025
dd6d164
Updated to reflect shift to experimental
WhitWaldo Mar 27, 2025
3ab103f
Disabled experimental warnings via file-level pragma statements
WhitWaldo Mar 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion daprdocs/content/en/dotnet-sdk-docs/dotnet-client/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,13 +230,14 @@ await foreach (var items in subscribeConfigurationResponse.Source.WithCancellati

```csharp
using System;
using System.Runtime.Versioning;
using Dapr.Client;

namespace LockService
{
class Program
{
[Obsolete("Distributed Lock API is in Alpha, this can be removed once it is stable.")]
[RequiresPreviewFeatures("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
Copy link
Collaborator

@philliphoff philliphoff Mar 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Experimental("...")]?

static async Task Main(string[] args)
{
var daprLockName = "lockstore";
Expand Down
7 changes: 3 additions & 4 deletions examples/Client/DistributedLock/Controllers/BindingController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
using System;
using System.Diagnostics.CodeAnalysis;
using System.Linq;
using System.Text.Json;
using System.Threading.Tasks;
Expand All @@ -24,8 +25,7 @@ public BindingController(DaprClient client, ILogger<BindingController> logger)
this.appId = Environment.GetEnvironmentVariable("APP_ID");
}

[HttpPost("cronbinding")]
[Obsolete]
[Experimental("DAPR10001")]
public async Task<IActionResult> HandleBindingEvent()
{
logger.LogInformation($"Received binding event on {appId}, scanning for work.");
Expand All @@ -47,8 +47,7 @@ public async Task<IActionResult> HandleBindingEvent()
return Ok();
}


[Obsolete]
[Experimental("DAPR10001")]
private async Task AttemptToProcessFile(string fileName)
{
// Locks are Disposable and will automatically unlock at the end of a 'using' statement.
Expand Down
44 changes: 21 additions & 23 deletions src/Dapr.Client/DaprClient.cs
View file
Open in desktop

Large diffs are not rendered by default.

40 changes: 16 additions & 24 deletions src/Dapr.Client/DaprClientGrpc.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,17 @@
// limitations under the License.
// ------------------------------------------------------------------------

using Dapr.Common.Extensions;

namespace Dapr.Client;

using System;
using System.Buffers;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Json;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
Expand Down Expand Up @@ -1664,8 +1662,7 @@ public override async Task<UnsubscribeConfigurationResponse> UnsubscribeConfigur
#region Cryptography

/// <inheritdoc />
[Obsolete(
"The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
Copy link
Collaborator

@philliphoff philliphoff Mar 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of suggestions:

  • Use a common constant for each ID to make changes simpler and allow for documentation
  • Use a different ID for each "category" or "area" in which the experimental APIs reside (e.g. storage vs. encryption vs. jobs) so that developers can opt into (i.e. suppress warnings) certain APIs without having to opt into every API.

Copy link
Contributor Author

@WhitWaldo WhitWaldo Mar 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@philliphoff Have you seen much guidance around this front? Following your suggestion, I've been thinking about it and I'm inclined towards "DAPR-WORKFLOW-001". We don't have much in the way of analyzers or other constants like this yet so definitely want consistency, so should I drop the hyphens altogether or keep them here for readability?

Copy link
Contributor Author

@WhitWaldo WhitWaldo Mar 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apparently hyphens are not allowed, so assume the same for underscores instead, e.g. "DAPR_WORKFLOW_001".

public override async Task<ReadOnlyMemory<byte>> EncryptAsync(string vaultResourceName,
ReadOnlyMemory<byte> plaintextBytes, string keyName, EncryptionOptions encryptionOptions,
CancellationToken cancellationToken = default)
Expand All @@ -1685,8 +1682,7 @@ public override async Task<ReadOnlyMemory<byte>> EncryptAsync(string vaultResour
}

/// <inheritdoc />
[Obsolete(
"The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override async Task<IAsyncEnumerable<ReadOnlyMemory<byte>>> EncryptAsync(string vaultResourceName,
Stream plaintextStream,
string keyName, EncryptionOptions encryptionOptions, CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -1787,8 +1783,7 @@ private async IAsyncEnumerable<ReadOnlyMemory<byte>> RetrieveEncryptedStreamAsyn
}

/// <inheritdoc />
[Obsolete(
"The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override async Task<IAsyncEnumerable<ReadOnlyMemory<byte>>> DecryptAsync(string vaultResourceName,
Stream ciphertextStream, string keyName,
DecryptionOptions decryptionOptions, CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -1819,8 +1814,7 @@ public override async Task<IAsyncEnumerable<ReadOnlyMemory<byte>>> DecryptAsync(
}

/// <inheritdoc />
[Obsolete(
"The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override Task<IAsyncEnumerable<ReadOnlyMemory<byte>>> DecryptAsync(string vaultResourceName,
Stream ciphertextStream, string keyName, CancellationToken cancellationToken = default) =>
DecryptAsync(vaultResourceName, ciphertextStream, keyName, new DecryptionOptions(),
Expand Down Expand Up @@ -1883,8 +1877,7 @@ private async IAsyncEnumerable<ReadOnlyMemory<byte>> RetrieveDecryptedStreamAsyn
}

/// <inheritdoc />
[Obsolete(
"The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override async Task<ReadOnlyMemory<byte>> DecryptAsync(string vaultResourceName,
ReadOnlyMemory<byte> ciphertextBytes, string keyName, DecryptionOptions decryptionOptions,
CancellationToken cancellationToken = default)
Expand All @@ -1904,8 +1897,7 @@ public override async Task<ReadOnlyMemory<byte>> DecryptAsync(string vaultResour
}

/// <inheritdoc />
[Obsolete(
"The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override async Task<ReadOnlyMemory<byte>> DecryptAsync(string vaultResourceName,
ReadOnlyMemory<byte> ciphertextBytes, string keyName, CancellationToken cancellationToken = default) =>
await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
Expand All @@ -1914,7 +1906,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
#region Subtle Crypto Implementation

///// <inheritdoc/>
//[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
//[Experimental("DAPR10001")]
//public override async Task<(string Name, string PublicKey)> GetKeyAsync(string vaultResourceName, string keyName, Autogenerated.SubtleGetKeyRequest.Types.KeyFormat keyFormat,
// CancellationToken cancellationToken = default)
//{
Expand Down Expand Up @@ -1943,7 +1935,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
//}

///// <inheritdoc/>
//[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
//[Experimental("DAPR10001")]
//public override async Task<(byte[] CipherTextBytes, byte[] AuthenticationTag)> EncryptAsync(string vaultResourceName, byte[] plainTextBytes, string algorithm,
// string keyName, byte[] nonce, byte[] associatedData, CancellationToken cancellationToken = default)
//{
Expand Down Expand Up @@ -1979,7 +1971,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
//}

///// <inheritdoc/>
//[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
//[Experimental("DAPR10001")]
//public override async Task<byte[]> DecryptAsync(string vaultResourceName, byte[] cipherTextBytes, string algorithm, string keyName, byte[] nonce, byte[] tag,
// byte[] associatedData, CancellationToken cancellationToken = default)
//{
Expand Down Expand Up @@ -2015,7 +2007,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
//}

///// <inheritdoc/>
//[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
//[Experimental("DAPR10001")]
//public override async Task<(byte[] WrappedKey, byte[] AuthenticationTag)> WrapKeyAsync(string vaultResourceName, byte[] plainTextKey, string keyName,
// string algorithm, byte[] nonce, byte[] associatedData, CancellationToken cancellationToken = default)
//{
Expand Down Expand Up @@ -2051,7 +2043,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
//}

///// <inheritdoc/>
//[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
//[Experimental("DAPR10001")]
//public override async Task<byte[]> UnwrapKeyAsync(string vaultResourceName, byte[] wrappedKey, string algorithm,
// string keyName, byte[] nonce, byte[] tag, byte[] associatedData, CancellationToken cancellationToken = default)
//{
Expand Down Expand Up @@ -2088,7 +2080,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
//}

///// <inheritdoc/>
//[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
//[Experimental("DAPR10001")]
//public override async Task<byte[]> SignAsync(string vaultResourceName, byte[] digest, string algorithm, string keyName, CancellationToken cancellationToken = default)
//{
// ArgumentVerifier.ThrowIfNullOrEmpty(vaultResourceName, nameof(vaultResourceName));
Expand Down Expand Up @@ -2121,7 +2113,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
//}

///// <inheritdoc/>
//[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
//[Experimental("DAPR10001")]
//public override async Task<bool> VerifyAsync(string vaultResourceName, byte[] digest, byte[] signature,
// string algorithm, string keyName, CancellationToken cancellationToken = default)
//{
Expand Down Expand Up @@ -2163,7 +2155,7 @@ await DecryptAsync(vaultResourceName, ciphertextBytes, keyName,
#region Distributed Lock API

/// <inheritdoc/>
[Obsolete]
[Experimental("DAPR10001")]
public async override Task<TryLockResponse> Lock(
string storeName,
string resourceId,
Expand Down Expand Up @@ -2203,7 +2195,7 @@ public async override Task<TryLockResponse> Lock(
}

/// <inheritdoc/>
[Obsolete]
[Experimental("DAPR10001")]
public async override Task<UnlockResponse> Unlock(
string storeName,
string resourceId,
Expand Down
3 changes: 2 additions & 1 deletion src/Dapr.Client/TryLockResponse.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,15 @@
// ------------------------------------------------------------------------

using System;
using System.Diagnostics.CodeAnalysis;
using System.Threading.Tasks;

namespace Dapr.Client
{
/// <summary>
/// Class representing the response from a Lock API call.
/// </summary>
[Obsolete("This API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public sealed class TryLockResponse : IAsyncDisposable
{
/// <summary>
Expand Down
8 changes: 4 additions & 4 deletions src/Dapr.Jobs/DaprJobsClient.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
// limitations under the License.
// ------------------------------------------------------------------------

using System.Diagnostics.CodeAnalysis;
using Dapr.Jobs.Models;
using Dapr.Jobs.Models.Responses;

Expand Down Expand Up @@ -45,8 +46,7 @@ public abstract class DaprJobsClient : IDisposable
/// <param name="repeats">The optional number of times the job should be triggered.</param>
/// <param name="ttl">Represents when the job should expire. If both this and DueTime are set, TTL needs to represent a later point in time.</param>
/// <param name="cancellationToken">Cancellation token.</param>
[Obsolete(
"The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public abstract Task ScheduleJobAsync(string jobName, DaprJobSchedule schedule,
ReadOnlyMemory<byte>? payload = null, DateTimeOffset? startingFrom = null, int? repeats = null,
DateTimeOffset? ttl = null,
Expand All @@ -58,15 +58,15 @@ public abstract Task ScheduleJobAsync(string jobName, DaprJobSchedule schedule,
/// <param name="jobName">The jobName of the job.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>The details comprising the job.</returns>
[Obsolete("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public abstract Task<DaprJobDetails> GetJobAsync(string jobName, CancellationToken cancellationToken = default);

/// <summary>
/// Deletes the specified job.
/// </summary>
/// <param name="jobName">The jobName of the job.</param>
/// <param name="cancellationToken">Cancellation token.</param>
[Obsolete("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public abstract Task DeleteJobAsync(string jobName, CancellationToken cancellationToken = default);

internal static KeyValuePair<string, string>? GetDaprApiTokenHeader(string apiToken)
Expand Down
7 changes: 4 additions & 3 deletions src/Dapr.Jobs/DaprJobsGrpcClient.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
// limitations under the License.
// ------------------------------------------------------------------------

using System.Diagnostics.CodeAnalysis;
using Dapr.Common;
using Dapr.Jobs.Models;
using Dapr.Jobs.Models.Responses;
Expand Down Expand Up @@ -68,7 +69,7 @@ internal DaprJobsGrpcClient(
/// <param name="repeats">The optional number of times the job should be triggered.</param>
/// <param name="ttl">Represents when the job should expire. If both this and DueTime are set, TTL needs to represent a later point in time.</param>
/// <param name="cancellationToken">Cancellation token.</param>
[Obsolete("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override async Task ScheduleJobAsync(string jobName, DaprJobSchedule schedule,
ReadOnlyMemory<byte>? payload = null, DateTimeOffset? startingFrom = null, int? repeats = null,
DateTimeOffset? ttl = null,
Expand Down Expand Up @@ -150,7 +151,7 @@ public override async Task ScheduleJobAsync(string jobName, DaprJobSchedule sche
/// <param name="jobName">The name of the job.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>The details comprising the job.</returns>
[Obsolete("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override async Task<DaprJobDetails> GetJobAsync(string jobName, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace(jobName))
Expand Down Expand Up @@ -198,7 +199,7 @@ public override async Task<DaprJobDetails> GetJobAsync(string jobName, Cancellat
/// <param name="jobName">The name of the job.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns></returns>
[Obsolete("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public override async Task DeleteJobAsync(string jobName, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace(jobName))
Expand Down
5 changes: 3 additions & 2 deletions src/Dapr.Jobs/Extensions/DaprSerializationExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
// limitations under the License.
// ------------------------------------------------------------------------

using System.Diagnostics.CodeAnalysis;
using System.Text;
using System.Text.Json;
using Dapr.Jobs.Models;
Expand Down Expand Up @@ -39,7 +40,7 @@ public static class DaprJobsSerializationExtensions
/// <param name="jsonSerializerOptions">Optional JSON serialization options.</param>
/// <param name="ttl">Represents when the job should expire. If both this and DueTime are set, TTL needs to represent a later point in time.</param>
/// <param name="cancellationToken">Cancellation token.</param>
[Obsolete("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public static async Task ScheduleJobWithPayloadAsync(this DaprJobsClient client, string jobName, DaprJobSchedule schedule,
object payload, DateTime? startingFrom = null, int? repeats = null, JsonSerializerOptions? jsonSerializerOptions = null, DateTimeOffset? ttl = null,
CancellationToken cancellationToken = default)
Expand All @@ -64,7 +65,7 @@ public static async Task ScheduleJobWithPayloadAsync(this DaprJobsClient client,
/// <param name="repeats">The optional number of times the job should be triggered.</param>
/// <param name="ttl">Represents when the job should expire. If both this and DueTime are set, TTL needs to represent a later point in time.</param>
/// <param name="cancellationToken">Cancellation token.</param>
[Obsolete("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]
[Experimental("DAPR10001")]
public static async Task ScheduleJobWithPayloadAsync(this DaprJobsClient client, string jobName, DaprJobSchedule schedule,
string payload, DateTime? startingFrom = null, int? repeats = null, DateTimeOffset? ttl = null,
CancellationToken cancellationToken = default)
Expand Down
Loading