Attributes.cs

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using System;
using System.ComponentModel;
using System.Diagnostics.CodeAnalysis;
using System.Runtime.InteropServices;

namespace WinRT
{
    [EditorBrowsable(EditorBrowsableState.Never)]
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public        
#endif
    sealed class ProjectedRuntimeClassAttribute : Attribute
    {
        public ProjectedRuntimeClassAttribute(string defaultInterfaceProp)
        {
            DefaultInterfaceProperty = defaultInterfaceProp;
        }

        public ProjectedRuntimeClassAttribute(Type defaultInterface)
        {
            DefaultInterface = defaultInterface;
        }

        public string DefaultInterfaceProperty { get; }
        public Type DefaultInterface { get; }
    }

#if NET
    [Obsolete("This attribute is only used for the .NET Standard 2.0 projections.")]
#endif
    [EditorBrowsable(EditorBrowsableState.Never)]
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public        
#endif
    sealed class ObjectReferenceWrapperAttribute : Attribute
    {
        public ObjectReferenceWrapperAttribute(string objectReferenceField)
        {
            ObjectReferenceField = objectReferenceField;
        }

        public string ObjectReferenceField { get; }
    }

    /// <summary>
    /// When applied to a type, designates to WinRT.Runtime that this type represents a type defined in WinRT metadata.
    /// </summary>
    [EditorBrowsable(EditorBrowsableState.Never)]
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Delegate | AttributeTargets.Struct | AttributeTargets.Enum, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public        
#endif 
    sealed class WindowsRuntimeTypeAttribute : Attribute
    {
        public WindowsRuntimeTypeAttribute(string sourceMetadata = null)
        {
            SourceMetadata = sourceMetadata;
        }

        public WindowsRuntimeTypeAttribute(string sourceMetadata, string guidSignature)
            :this(sourceMetadata)
        {
            GuidSignature = guidSignature;
        }

        public string SourceMetadata { get; }
        public string GuidSignature { get; }
    }

    /// <summary>
    /// When applied to a type, it specifies the provided type, if one is provided, is the ABI helper type for this type.
    /// </summary>
    [EditorBrowsable(EditorBrowsableState.Never)]
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Delegate | AttributeTargets.Struct | AttributeTargets.Enum, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class WindowsRuntimeHelperTypeAttribute : Attribute
    {
        // Indicates no associated helper types (i.e. blittable types).
        public WindowsRuntimeHelperTypeAttribute()
        {
        }

        public WindowsRuntimeHelperTypeAttribute(
#if NET
            [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods | DynamicallyAccessedMemberTypes.PublicFields)]
#endif
            Type helperType)
        {
            HelperType = helperType;
        }

#if NET
        [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods | DynamicallyAccessedMemberTypes.PublicFields)]
#endif
        public Type HelperType { get; }
    }

#if NET

    /// <summary>
    /// An interface implemented by types used with <see cref="WinRTExposedTypeAttribute"/> to provide vtable entries for the annotated type.
    /// Types implementing this interface can supply precomputed vtable entries to ensure WinRT marshalling can work with trimming and AOT.
    /// </summary>
    /// <remarks>
    /// This interface is primarily meant to be used by types provided by CsWinRT, or generated at compile time by its source generators.
    /// However, it is possible to implement it manually as well, to support advanced scenarios where further customization was needed.
    /// </remarks>
#if EMBED
    internal
#else
    public
#endif
    interface IWinRTExposedTypeDetails
    {
        /// <summary>
        /// Gets the array of <see cref="ComWrappers.ComInterfaceEntry"/> values representing vtable entries to expose to native code.
        /// </summary>
        /// <returns>The vtable entries to expose to native code for the annotated type.</returns>
        ComWrappers.ComInterfaceEntry[] GetExposedInterfaces();
    }

    /// <summary>
    /// An attribute that allows associating an <see cref="IWinRTExposedTypeDetails"/> implementation type with an annotated type.
    /// </summary>
    /// <remarks>
    /// This attribute is usually automatically generated by the CsWinRT AOT generator, for all types implementing WinRT interfaces
    /// or deriving from a WinRT exposed type. However, it is also possible to use this manually to further customize the behavior.
    /// When that is the case, the AOT generator will detect the presence of this attribute and skip processing that type.
    /// </remarks>
#if !NET8_0_OR_GREATER
    [EditorBrowsable(EditorBrowsableState.Never)]
#endif
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Delegate | AttributeTargets.Struct | AttributeTargets.Enum, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class WinRTExposedTypeAttribute : Attribute
    {
        /// <summary>
        /// Creates a new <see cref="WinRTExposedTypeAttribute"/> instance.
        /// </summary>
        /// <remarks>
        /// Using this constructor will supply no additional vtable entries to the annotated type, other than the default ones (eg. for <see cref="IInspectable"/>).
        /// </remarks>
        public WinRTExposedTypeAttribute()
        {
        }

        /// <summary>
        /// Creates a new <see cref="WinRTExposedTypeAttribute"/> instance with the specified parameters.
        /// </summary>
        /// <param name="winrtExposedTypeDetails">The <see cref="IWinRTExposedTypeDetails"/> implementation type to use to retrieve vtable entries for the annotated type.</param>
        public WinRTExposedTypeAttribute(
            [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)]
            Type winrtExposedTypeDetails)
        {
            WinRTExposedTypeDetails = winrtExposedTypeDetails;
        }

        /// <inheritdoc cref="IWinRTExposedTypeDetails.GetExposedInterfaces"/>
        public ComWrappers.ComInterfaceEntry[] GetExposedInterfaces()
        {
            return WinRTExposedTypeDetails is not null ? 
                ((IWinRTExposedTypeDetails)Activator.CreateInstance(WinRTExposedTypeDetails)).GetExposedInterfaces() : 
                Array.Empty<ComWrappers.ComInterfaceEntry>();
        }

#if NET
        [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)]
#endif
        internal Type WinRTExposedTypeDetails { get; }
    }

#if NET8_0_OR_GREATER
    /// <summary>
    /// An <see cref="IWinRTExposedTypeDetails"/> implementation for types that are explicitly not meant to be marshalled to native code.
    /// </summary>
    /// <remarks>
    /// This type can be used as argument for <see cref="WinRTExposedTypeAttribute"/> on any managed types that are not meant to be marshalled,
    /// but that would otherwise trigger the CsWinRT AOT generator (because they implement a WinRT interface, or derive from a WinRT exposed
    /// type). When support for marshalling is not needed, using this type allows suppressing warnings, and disabling that code generation.
    /// This can also provide a small binary size improvement in such cases, as that unnecessary marshalling code will not be emitted.
    /// </remarks>
#if EMBED
    internal
#else
    public
#endif
    sealed class WinRTManagedOnlyTypeDetails : IWinRTExposedTypeDetails
    {
        /// <inheritdoc/>
        public ComWrappers.ComInterfaceEntry[] GetExposedInterfaces()
        {
            ThrowNotSupportedException();

            return Array.Empty<ComWrappers.ComInterfaceEntry>();
        }

        /// <summary>
        /// Throws a <see cref="NotSupportedException"/> to signal that a blocked type is being marshalled.
        /// </summary>
        [DoesNotReturn]
        private static void ThrowNotSupportedException()
        {
            throw new NotSupportedException(
                "The annotated type does not support WinRT marshalling, and can only be used by managed code. If you do intend " +
                "on marshalling it, remove the '[WinRTExposedType(typeof(WinRTManagedOnlyTypeDetails))]' annotation on it, " +
                "and mark the type as partial, to allow the CsWinRT AOT generator to emit the necessary marshalling code for it.");
        }
    }
#endif

    /// <summary>
    /// An attributes used for generated RCW types, to expose a factory method for them.
    /// </summary>
    [EditorBrowsable(EditorBrowsableState.Never)]
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public
#endif
    abstract class WinRTImplementationTypeRcwFactoryAttribute : Attribute
    {
        /// <summary>
        /// Creates a new instance of a given RCW type, from an input <see cref="IInspectable"/> object.
        /// </summary>
        /// <param name="inspectable">The native <see cref="IInspectable"/> object to use to construct the RCW instance.</param>
        /// <returns>The resulting RCW instance wrapping the same native object as <paramref name="inspectable"/>.</returns>
        public abstract object CreateInstance(IInspectable inspectable);
    }

    /// <summary>
    /// An attributes used to explicitly indicate ther runtime class name to use for WinRT exposed types.
    /// </summary>
    /// <remarks>This attribute is emitted by the CsWinRT generator for non-authored types implementing WinRT interfaces.</remarks>
    [EditorBrowsable(EditorBrowsableState.Never)]
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class WinRTRuntimeClassNameAttribute : Attribute
    {
        /// <summary>
        /// Creates a new <see cref="WinRTRuntimeClassNameAttribute"/> instance with the specified parameters.
        /// </summary>
        /// <param name="runtimeClassName">The runtime class name to use.</param>
        public WinRTRuntimeClassNameAttribute(string runtimeClassName)
        {
            RuntimeClassName = runtimeClassName;
        }

        /// <summary>
        /// Gets the runtime class name for the current instance.
        /// </summary>
        public string RuntimeClassName { get; }
    }

    /// <summary>
    /// An attribute used to indicate which generated type contains the exported functions for a given WinRT component assembly.
    /// </summary>
    [EditorBrowsable(EditorBrowsableState.Never)]
    [AttributeUsage(AttributeTargets.Assembly, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class WinRTAssemblyExportsTypeAttribute : Attribute
    {
        /// <summary>
        /// Creates a new <see cref="WinRTAssemblyExportsTypeAttribute"/> instance with the specified parameters.
        /// </summary>
        /// <param name="type">The type containing the exported functions for the current WinRT component assembly.</param>
        public WinRTAssemblyExportsTypeAttribute(Type type)
        {
            Type = type;
        }

        /// <summary>
        /// Gets the type containing the exported functions for the current WinRT component assembly
        /// </summary>
        public Type Type { get; }
    }

    /// <summary>
    /// An attribute used to indicate the properties which are bindable via the <see cref="Microsoft.UI.Xaml.Data.ICustomProperty"/> implementation
    /// provided for use in WinUI scenarios. The type which this attribute is placed on also needs to be marked partial and needs to be non-generic.
    /// </summary>
    /// <remarks>
    /// This type also provides equivalent support for the UWP XAML interface (as it shares the same IID as the WinUI type).
    /// </remarks>
#if NET8_0_OR_GREATER
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, Inherited = false, AllowMultiple = false)]
#else
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
#endif
#if EMBED
    internal
#else
    public
#endif
    sealed class GeneratedBindableCustomPropertyAttribute : Attribute
    {
        /// <summary>
        /// Marks all public properties as bindable.
        /// </summary>
        public GeneratedBindableCustomPropertyAttribute()
        {
        }

        /// <summary>
        /// Marks the specified public properties as bindable.
        /// </summary>
        /// <param name="propertyNames">The name of the non-indexer public properties to mark as bindable.</param>
        /// <param name="indexerPropertyTypes">The parameter type of the indexer public properties to mark as bindable.</param>
        public GeneratedBindableCustomPropertyAttribute(string[] propertyNames, Type[] indexerPropertyTypes)
        {
            PropertyNames = propertyNames;
            IndexerPropertyTypes = indexerPropertyTypes;
        }

        internal string[] PropertyNames { get; }
        internal Type[] IndexerPropertyTypes { get; }
    }
#endif

#if NET8_0_OR_GREATER
    /// <summary>
    /// An attribute used to indicate that the type definition it is put on
    /// is exposed to the WinRT ABI and needs a vtable generated for it.
    /// The type which this attribute is placed on also needs to be marked partial.
    /// </summary>
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class GeneratedWinRTExposedTypeAttribute : Attribute
    {
        /// <summary>
        /// Marks the type it is put on as exposed to the WinRT ABI
        /// so that a vtable can be generated for it.
        /// </summary>
        public GeneratedWinRTExposedTypeAttribute()
        {
        }
    }

    /// <summary>
    /// An attribute used to indicate that the the type passed to the constructor
    /// is exposed to the WinRT ABI and needs a vtable generated for it.
    /// </summary>
    [AttributeUsage(AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
#if EMBED
    internal
#else
    public
#endif
    sealed class GeneratedWinRTExposedExternalTypeAttribute : Attribute
    {
        /// <summary>
        /// Marks the given type as exposed to the WinRT ABI so that a vtable can be generated for it.
        /// </summary>
        public GeneratedWinRTExposedExternalTypeAttribute(Type type)
        {
            Type = type;
        }

        internal Type Type { get; }
    }
#endif

#if NET8_0_OR_GREATER
    /// <summary>
    /// An attribute that indicates that the annotated member or field (initializer) is performing a dynamic cast to a Windows Runtime type.
    /// This in turns ensures that the necessary metadata is kept during trimming so that the cast can work correctly in all scenarios.
    /// </summary>
    /// <seealso cref="DynamicDependencyAttribute"/>
    [AttributeUsage(AttributeTargets.Constructor | AttributeTargets.Method | AttributeTargets.Field, AllowMultiple = true, Inherited = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class DynamicWindowsRuntimeCastAttribute : Attribute
    {
        /// <summary>
        /// Creates a new <see cref="DynamicWindowsRuntimeCastAttribute"/> instance with the specified parameters.
        /// </summary>
        /// <param name="type">The Windows Runtime type being used for the cast.</param>
        public DynamicWindowsRuntimeCastAttribute(Type type)
        {
        }
    }
#endif
}

namespace System.Runtime.InteropServices.WindowsRuntime
{
    [AttributeUsage(System.AttributeTargets.Parameter, AllowMultiple = false, Inherited = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class ReadOnlyArrayAttribute : Attribute
    {
    }

    [AttributeUsage(System.AttributeTargets.Parameter, AllowMultiple = false, Inherited = false)]
#if EMBED
    internal
#else
    public
#endif
    sealed class WriteOnlyArrayAttribute : Attribute
    {
    }
}