XrmTools.Meta.Attributes 1.2.0

XrmTools.Meta.Attributes is a source-only package that adds all the attribute types required by Xrm Tools. You would use these attributes to add metadata to your plugins and custom APIs and Xrm Tools enables you to deploy your plugins, generate code on-the-fly and many other cool things that make you more productive. You can now focus on more important matters, like your core business logic.

This package is part of the Xrm Tools extension for Visual Studio, which provides a set of tools to enhance your development experience with Microsoft Dataverse (formerly known as Common Data Service or Dynamics 365).

If you aren't already using Xrm Tools for Power Platform development, I suggest checking out Xrm Tools Wiki to learn how modern way of Power Platform development can enhance your experience. You can do pretty much everything with regards to plugins and API development without ever leaving Visual Studio.

Accessibility

By default, the types generated into your project from XrmTools.Meta.Attributes are internal.

If you want the generated types to be public, add the following property to your consuming project:

<PropertyGroup>
  <XrmToolsMetaAttributesUsePublicAccessibility>true</XrmToolsMetaAttributesUsePublicAccessibility>
</PropertyGroup>

This switch is optional. The NuGet package name remains XrmTools.Meta.Attributes.

Attributes

By installing this nuget packge, you will be able to use attributes to decorate your Dataverse plugins with metadata to enable code generation and automatic registration. Supported attributes are:

• PluginAttribute: Used to decorate a class that implements IPlugin to specify the plugin registration details. This attribute should be the first registration attribute on the class.
• StepAttribute: Used to decorate a class that implements IPlugin to specify the step registration details. This attribute comes after the PluginRegistrationAttribute and can be used multiple times to register multiple steps for the same plugin.
• ImageAttribute: Used to decorate a class that implements IPlugin to specify the image registration details. This attribute comes after the PluginStepAttribute and can be used multiple times to register multiple images for the same step.

Custom API

A plugin that provides a Custom API in Power Platform can benefit from the following attributes. Use the following attributes to make your API more readable and write a lot less code. Read more in Xrm Tools Wiki - Writing a Custom API

• CustomApiAttribute: Used to decorate a class that implements IPlugin to specify the custom API registration details. This attribute comes after the PluginRegistrattionAttribute and can be used only once on a class to register a custom API for the plugin.
• CustomApiRequestAttribute: Used to decorate a class, nested inside the calss that implements IPlugin to specify the custom API request parameters. By applying this attribute, all properties of the class will become request parameters for your custom API. This attribute can only be applied to a single class within the plugin class.
• CustomApiResponseAttribute: Used to decorate a class, nested inside the calss that implements IPlugin to specify the custom API response properties. By applying this attribute, all properties of the class will become response properties for your custom API. This attribute can only be applied to a single class within the plugin class.
• CustomApiRequestParameter: Used to optionally decorate a property of the class that is marked with CustomApiRequestAttribute to specify the custom API request parameter details. This attribute can be used to set the parameter name, description, and other details.
• CustomApiResponseProperty: Used to optionally decorate a property of the class that is marked with CustomApiResponseAttribute to specify the custom API response property details. This attribute can be used to set the parameter name, description, and other details.

Dependency Injection

By adding the following attributes to properties of your class you can opt into a simple compile-time dependency injection. Read more in Xrm Tools Wiki - Dependency Injection

• DependencyAttribute: Decorate a property as a dependency so that code generator can generate code to inject this dependency.
• DependencyConstructor: Decorate a constructor method as the constructor to be used by the dependency injection. It's useful when you have more than one constructor.
• DependencyProvider: Used for when you need your own custom logic to initialize a depdency. Just add the attribute to a property in your plugin write set your depdency like the following example.

    [DependencyProvider("User")]
    protected IOrganizationService UserOrgService
    {
        get => TryGet<IOrganizationService>("User", out var service)
            ? service
            : Set("User", OrgServiceFactory.CreateOrganizationService(Context.UserId));
    }

Early-bound (typed) Entities

It's a lot easier to add early-bound (typed) entities to your project. Just add the following attribute to your AssemblyInfo.cs or any global .cs file and save. Read more in Xrm Tools Wiki - Typed Entities

• EntityAttribute: Assembly scoped attribute that instructs the code generator to generate a typed entity with the given attributes.

Code Generation Settings

You can fine-tune code generation in Xrm Tools by adding the following global attributes to your Assemblyinfo.cs or any global .cs file.

• CodeGenReplacePrefixesAttribute: Assembly scoped attribute that instructs the code generator to replace or remove the prefixes of the entity names with the given values. This is useful when you want to use a different prefix for your entities or remove prefixes in the generated code.
• CodeGenGlobalOptionSetAttribute: Assembly scoped attribute that lets the developer decide if global option sets should be generated in the GlobalOptionSets.cs file or as enums in the typed entity files. By default, global option sets are generated locally.
• CodeGenNameCollisionSuffixAttribute: Assembly scoped attribute that sets the suffix appended to a generated property when its name would otherwise clash with the name of its enclosing type. This happens when a Dataverse column shares the logical name of its table (e.g. a table xxx_postalcode with a column xxx_postalcode), which C# does not allow. The default suffix is Value (so the column above becomes a PostalCodeValue property); use this attribute to choose another, e.g. [assembly: CodeGenNameCollisionSuffix("Attribute")].

Other Global Attributes

• PluginAssemblyAttribute: You can optionally customize the assembly level registration by adding this attribute to your AssemblyInfor.cs or any other global .cs file.
• SolutionAttribute: You can optionally include all your plugins in your designated Power Platform solution. Your solution need to already exist.

An example AssemblyInfo.cs file with these optional attributes.

using Microsoft.Xrm.Sdk.Client;
using System.Reflection;
using System.Runtime.InteropServices;
using XrmTools.Meta.Attributes;

[assembly: AssemblyTitle("XrmGenTest")]
// Other assembly attributes removed for brevity.

// The following is useful for when you have early-bound (typed) entities. It let's 
// Dataverse recognize your custom entity types.
[assembly: ProxyTypesAssembly]
// The following attribute is just using the default values.
[assembly: PluginAssembly]
// The following attribute is declaring which Power Platform solution will contain your plugins.
[assembly: Solution("Test")]
// The following attribute is telling Xrm Tools to generate global optionsets in a dedicated "GlobalOptionSets.cs" file.
[assembly: CodeGenGlobalOptionSet(GlobalOptionSetGenerationMode.GlobalOptionSetFile)]

Let's look at some more examples:

Example 1: Plugin Registration

using Microsoft.Xrm.Sdk;
using System;
using XrmTools.Meta.Attributes;
using XrmTools.Meta.Model;

namespace XrmGenTest;

[Plugin]
[Step("Create", "contact", "firstname,lastname", Stages.PostOperation, ExecutionMode.Synchronous)]
[Image(ImageTypes.PostImage, "firstname,lastname")]
public partial class ContactCreatePlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        if (serviceProvider == null)
        {
            throw new InvalidPluginExecutionException(nameof(serviceProvider));
        }
        // ... rest of the code.
    }
}

Example 2: Plugin Registration with a PluginBase class

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Extensions;
using System;
using XrmTools.Meta.Attributes;
using XrmTools.Meta.Model;

namespace XrmGenTest;

public abstract class PluginBase : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        if (serviceProvider == null)
        {
            throw new InvalidPluginExecutionException(nameof(serviceProvider));
        }
        var executionContext = serviceProvider.Get<IPluginExecutionContext7>();
        var organizationService = serviceProvider.GetOrganizationService(executionContext.UserId);
        var tracing = serviceProvider.Get<ITracingService>();
        Initialize(serviceProvider);
    }

    internal abstract void ExecuteInternal(IServiceProvider serviceProvider) { }
}

[Plugin]
[Step("Create", "account", "accountnumber,accountcategorycode,accountclassificationcode", Stages.PostOperation, ExecutionMode.Synchronous)]
[Image(ImageTypes.PostImage, "accountnumber")]
public partial class AccountCreatePlugin : PluginBase, IPlugin
{
    internal override void ExecuteLocal(IServiceProvider serviceProvider)
    {
        //... rest of the logic
    }
}

Example 3: Custom API Registration

using Microsoft.Xrm.Sdk;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using XrmTools.Meta.Attributes;

namespace XrmGenTest;

[Plugin]
[CustomApi("test_MyCustomApi", "My Custom API", "MyCustomApi")]
public partial class MyCustomApiPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        throw new InvalidPluginExecutionException("Test", PluginHttpStatusCode.ExpectationFailed);
    }

    [CustomApiRequest]
    public class Request
    {
        public bool BooleanParameter { get; set; }
        public DateTime DateTimeParameter { get; set; }
        // Marking the type as nullable will make the parameter optional in the Custom API.
        public decimal? DecimalParameter { get; set; }
        public Entity EntityParameter { get; set; }
        public Contact ContactParameter { get; set; } // This is a typed entity, you can use any entity that is registered in your Dataverse environment.
        public IEnumerable<Contact> ContactsParameter { get; set; } // This will be converted to an EntityCollection in the Custom API request.
        public EntityCollection EntityCollectionParameter { get; set; }
        public EntityReference EntityReferenceParameter { get; set; }
        // Null annotation makes the parameter optional.
        public float? FloatParameter { get; set; }
        public int IntegerParameter { get; set; }
        // You can manually set the parameter metadata like name, description.
        [CustomApiRequestParameter(UniqueName = "money_parameter", IsOptional = true, DisplayName = "Money Parameter", Description = "Money parameter description")]]
        public Money MoneyParameter { get; set; }
        public OptionSetValue PicklistParameter { get; set; }
        public XrmTools.Meta.Model.BindingTypes EnumParameter { get; set; }
        public string StringParameter { get; set; }
        public string[] StringArrayParameter { get; set; }
        public Guid GuidParameter { get; set; }
    }

    [CustomApiResponse]
    public class Response
    {
        public bool BooleanParameter { get; set; }
        public DateTime DateTimeParameter { get; set; }
        public decimal DecimalParameter { get; set; }
        public Entity EntityParameter { get; set; }
        public EntityCollection EntityCollectionParameter { get; set; }
        public EntityReference EntityReferenceParameter { get; set; }
        public float FloatParameter { get; set; }
        public int IntegerParameter { get; set; }
        public Money MoneyParameter { get; set; }
        public OptionSetValue PicklistParameter { get; set; }
        public XrmTools.Meta.Model.BindingTypes EnumParameter { get; set; }
        public string StringParameter { get; set; }
        public string[] StringArrayParameter { get; set; }
        public Guid GuidParameter { get; set; }
    }
}

Example 4: Two typed entities.

// Entities.cs

[assembly:Entity("contact", "firstname,lastname")]
[assembly:Entity("account", "name") ]

To learn more about Xrm Tools extension for Visual Studio, please refer to:

• GitHub repository
• Official documentation.