Skip to content

Commit

Permalink
.Net: Add internal copy of [Experimental] (#3503)
Browse files Browse the repository at this point in the history
### Motivation and Context

The C# compiler now supports an ExperimentalAttribute. It ships in .NET
8, but the compiler respects any version of the attribute with the
appropriate name and shape, including one built into an assembly as
internal. Anything marked as [Experimental] then triggers a warning at
usage sites, forcing the usage to acknowledge the experimental nature of
the thing being consumed by either being marked [Experimental] itself or
by suppressing the warning via NoWarn or a pragma directive.

This commit adds a copy of the attribute as internal, and uses it on all
of the Microsoft.SemanticKernel.Experimental.Orchestration.Flow
assembly, as it's obviously intended to be experimental. We can
subsequentally mark anything as [Experimental] that isn't ready to be
declared stable for the 1.0 release.

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄
  • Loading branch information
stephentoub committed Nov 15, 2023
1 parent ca09459 commit 6e374b7
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 0 deletions.
Expand Up @@ -21,6 +21,8 @@
using Microsoft.SemanticKernel.Plugins.Web.Bing;
using NCalcPlugins;

#pragma warning disable SKEXP0001 // This is an experimental feature.

/**
* This example shows how to use FlowOrchestrator to execute a given flow with interaction with client.
*/
Expand Down
6 changes: 6 additions & 0 deletions dotnet/src/Experimental/Orchestration.Flow/AssemblyInfo.cs
@@ -0,0 +1,6 @@
// Copyright (c) Microsoft. All rights reserved.

using System.Diagnostics.CodeAnalysis;

// This assembly is currently experimental.
[assembly: Experimental("SKEXP0001")]
@@ -0,0 +1,59 @@
// Copyright (c) Microsoft. All rights reserved.

// This is a copy of:
// https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs
// made internal rather than public.

namespace System.Diagnostics.CodeAnalysis;

#if !NET8_0_OR_GREATER
/// <summary>
/// Indicates that an API is experimental and it may change in the future.
/// </summary>
/// <remarks>
/// This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental
/// feature is used. Authors can use this attribute to ship preview features in their assemblies.
/// </remarks>
[AttributeUsage(AttributeTargets.Assembly |
AttributeTargets.Module |
AttributeTargets.Class |
AttributeTargets.Struct |
AttributeTargets.Enum |
AttributeTargets.Constructor |
AttributeTargets.Method |
AttributeTargets.Property |
AttributeTargets.Field |
AttributeTargets.Event |
AttributeTargets.Interface |
AttributeTargets.Delegate, Inherited = false)]
internal sealed class ExperimentalAttribute : Attribute
{
/// <summary>
/// Initializes a new instance of the <see cref="ExperimentalAttribute"/> class, specifying the ID that the compiler will use
/// when reporting a use of the API the attribute applies to.
/// </summary>
/// <param name="diagnosticId">The ID that the compiler will use when reporting a use of the API the attribute applies to.</param>
public ExperimentalAttribute(string diagnosticId)
{
this.DiagnosticId = diagnosticId;
}

/// <summary>
/// Gets the ID that the compiler will use when reporting a use of the API the attribute applies to.
/// </summary>
/// <value>The unique diagnostic ID.</value>
/// <remarks>
/// The diagnostic ID is shown in build output for warnings and errors.
/// <para>This property represents the unique ID that can be used to suppress the warnings or errors, if needed.</para>
/// </remarks>
public string DiagnosticId { get; }

/// <summary>
/// Gets or sets the URL for corresponding documentation.
/// The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID.
/// </summary>
/// <value>The format string that represents a URL to corresponding documentation.</value>
/// <remarks>An example format string is <c>https://contoso.com/obsoletion-warnings/{0}</c>.</remarks>
public string? UrlFormat { get; set; }
}
#endif

0 comments on commit 6e374b7

Please sign in to comment.