Digitall.Plugins.Registration 3.0.0-beta.3

Digitall.Plugins.Registration

NuGet package providing C# attributes for automated registration of Microsoft Dataverse plugin assemblies and workflow activities.

<p align="center"> <a href="LICENSE.md" target="_blank"> <img src="https://img.shields.io/github/license/DIGITALLNature/DigitallRegistrationPower.svg" alt="GitHub license"> </a> <a href="https://github.com/DIGITALLNature/DigitallRegistrationPower/releases" target="_blank"> <img src="https://img.shields.io/github/tag/DIGITALLNature/DigitallRegistrationPower.svg" alt="GitHub tag (latest SemVer)"> </a> <a href="https://www.nuget.org/packages/Digitall.Plugins.Registration" target="_blank"> <img src="https://img.shields.io/nuget/v/Digitall.Plugins.Registration" alt="NuGet"> </a> <a href="https://github.com/DIGITALLNature/DigitallRegistrationPower/graphs/contributors" target="_blank"> <img src="https://img.shields.io/github/contributors-anon/DIGITALLNature/DigitallRegistrationPower.svg" alt="GitHub contributors"> </a> </p>

Table of Contents

• Installation
• Usage
  • Plugin Registration
  • Custom API Registration
  • Custom Data Provider Registration
  • Workflow Registration
  • Managed Identity Registration
• API Reference
  • Attributes
  • Enums
• Requirements
• License

Installation

dotnet add package Digitall.Plugins.Registration

For a project in a subdirectory:

dotnet add src/MyProject package Digitall.Plugins.Registration

Usage

Add using Digitall.Plugins.Registration; to your file and decorate your plugin or workflow class with the appropriate attribute. A registration tool can then discover and apply these annotations automatically.

PluginRegistration

Use [PluginRegistration] on classes that implement IPlugin for standard plugin step registration. Multiple attributes can be stacked on one class to register multiple steps.

Constructor parameters (mandatory):

Optional named parameters:

using Digitall.Plugins.Registration;

[PluginRegistration(PluginExecutionMode.Asynchronous, "Create", PluginExecutionStage.PreOperation,
    PrimaryEntityName = "account", ExecutionOrder = 10)]
[PluginRegistration(PluginExecutionMode.Synchronous, "Update", PluginExecutionStage.PostOperation,
    PrimaryEntityName = "account",
    FilterAttributes = new[] { "name" },
    PreEntityImage = true, PreEntityImageAttributes = new[] { "name" })]
public class SamplePlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // ...
    }
}

CustomApiRegistration

Use [CustomApiRegistration] on classes that implement IPlugin and act as the handler for a Custom API. Multiple attributes can be stacked.

using Digitall.Plugins.Registration;

[CustomApiRegistration("dgt_calc_vacations")]
public class CalcVacationsPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // ...
    }
}

CustomDataProviderRegistration

Use [CustomDataProviderRegistration] on classes that implement IPlugin to declare operation handlers for a custom data provider. Its constructor requires the data-source schema name, event, and provider name; optional metadata can be set with named properties. Stack one attribute per operation and use the same data-source schema name to group handlers into one provider.

The provider is identified by its data-source configuration table, not by a virtual table. One provider can serve multiple virtual tables.

Required constructor arguments

Optional properties

using Digitall.Plugins.Registration;

[CustomDataProviderRegistration("dgt_CrmDataSource", DataProviderEvent.Create, "CRM Provider")]
[CustomDataProviderRegistration("dgt_CrmDataSource", DataProviderEvent.Update, "CRM Provider")]
public class HandleUpsertOnVirtualTable : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // ...
    }
}

The provider name is required on every declaration by the constructor; the registration tool can use the value from any declaration in the group. Optional string properties default to null. Omitted optional metadata preserves existing values: a declaration without optional metadata does not change existing table labels or descriptions. For first-time creation only, omitted table labels default to the schema name (singular) and the singular label plus " Records" (plural).

Registration-tool contract: This package supplies metadata only; it does not perform Dataverse registration or validation. A compatible dgtp release must:

• Validate required values before writes, reject Unspecified and unknown events, and reject conflicting metadata or different classes claiming the same provider operation.
• Resolve the schema name to the table's logical name and find the provider by datasourcelogicalname; reject ambiguous provider matches.
• Create/update the EntityDataProvider record and assign registered plugin-type IDs to its operation fields, rather than creating ordinary SDK message-processing steps.
• Preserve existing handlers for undeclared operations and preserve omitted optional metadata. Omission does not clear a value or remove a handler.

Creating or validating the provider's data-source configuration table belongs to the registration tool. The special table metadata and creation/reuse lifecycle must be verified before first-time provisioning is supported. Data-source records, custom configuration columns, virtual tables, and their mappings are outside this declaration's scope. Credentials must not be stored in attributes.

Breaking-change migration: The (string entityName, DataProviderEvent eventRegistration) constructor and EntityName property have been removed. Replace old declarations such as [CustomDataProviderRegistration("dgt_virtual_table", DataProviderEvent.Retrieve)] with the three-argument constructor shown above, selecting the provider's data-source schema name rather than copying the virtual-table name. Supply the provider name on each declaration and rebuild the plugin assembly. This API requires corresponding support in dgtp; legacy declarations must be rejected with migration guidance, not reinterpreted.

WorkflowRegistration

Use [WorkflowRegistration] on classes that derive from CodeActivity for workflow activity registration.

using Digitall.Plugins.Registration;

[WorkflowRegistration("Sample", "SampleGroup")]
public class SampleWorkflow : CodeActivity
{
    [Input(nameof(Email))]
    [RequiredArgument]
    [ReferenceTarget("email")]
    public InArgument<EntityReference> Email { get; set; }

    protected override void Execute(CodeActivityContext context)
    {
        // ...
    }
}

ManagedIdentityRegistration

Use [ManagedIdentityRegistration] at assembly level to associate a managed identity with the plugin assembly or package. Applied once per assembly.

Note: This attribute only handles the Dataverse-side registration. You still need to set up the managed identity in Azure and sign the assembly/package. See Microsoft Managed Identity overview.

using Digitall.Plugins.Registration;

[assembly: ManagedIdentityRegistration("00000000-0000-0000-0000-000000000000")]

API Reference

Attributes

Enums

PluginExecutionMode

PluginExecutionStage

DataProviderEvent

Requirements

• .NET Standard 2.0 or higher

License

Released under the Microsoft Public License (MS-PL).