> For the complete documentation index, see [llms.txt](https://docs.ezra360.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ezra360.com/customization/plugins.md). # Plugins ## 1. Overview: Plugins ### 1.1 What is a Plugin? A Plugin is a class that implements the IXrmPlugin interface. It is triggered automatically by the Ezra360 platform when a specific event occurs on a specific entity — for example, when a record is created, updated, or deleted. \ Plugins run as part of the entity lifecycle. They receive a **PluginExecutionContext** object that provides access to the triggering record and platform services. #### Common use cases for plugins: * Auto-creating related child records when a parent is saved * Enforcing business rules before a record is committed to the database * Sending notifications or emails when a record reaches a certain state * Calculating rollup or summary values on related records * Preventing deletion of records that have active dependencies #### Plugin (IXrmPlugin) Characteristics * [ ] Triggered automatically by entity events * [ ] Implements IXrmPlugin * [ ] Return type: void * [ ] Execution step: PostUpdate, PreCreate, etc. * [ ] Access: PluginExecutionContext * [ ] Example: Enforce approval rules on save ## 2. Prerequisites & NuGet Packages Before writing any code, ensure your development environment is properly set up. ### 2.1 Required Software * Visual Studio 2022 (Community, Professional, or Enterprise edition) * .NET Core 3.1 SDK — download from * Git (optional, for source control) ### 2.2 Creating the Project In Visual Studio, create a new Class Library project targeting .NET Core 3.1: 1. Open Visual Studio 2022 2. Click Create a new project 3. Search for "Class Library" and select Class Library (.NET Core) 4. Name the project using the convention: CompanyName.Module.Feature — e.g. ERP.Ezra360.Package 5. Set the framework to .NET Core 3.1 6. Click Create ### 2.3 Required NuGet Packages Add the following packages via NuGet Package Manager (Tools > NuGet Package Manager > Manage NuGet Packages for Solution):
## 3. Project Structure in Visual Studio A well-organised Ezra360 plugin project follows a consistent folder structure. Each folder serves a specific purpose and maps to a distinct category of code responsibility. ### 3.1 Recommended Folder Layout YourProject/ \\ ├── Models/ ← C# classes mapping to SQL query results \ │ ├── Directives.cs \ │ └── DirectiveSubmissions.cs \ ├── Plugins/ ← Event-driven logic (IXrmPlugin) \ │ ├── CreateDirectiveSubmissions.cs \ │ └── SendConfirmationEmail.cs \\ ### 3.2 Folder Descriptions #### Plugins/ Contains all event-driven plugin classes. Each file implements IXrmPlugin. These are triggered automatically by entity lifecycle events such as PostUpdate, PreCreate, PostDelete, etc. #### Models/ Contains plain C# classes (POCOs) that map to the results of your SQL queries. When you execute a SQL query through context.BusinessActions.ExecuteListQuery(), the SDK maps each result row to an instance of your model class. Column names in the SQL SELECT must match property names on the model. ## 4. Creating a Plugin (IXrmPlugin) A plugin class must be public and implement the IXrmPlugin interface from the Xrm.Soft.Aer.SDK package. There is one required method: ExecutePlugin(PluginExecutionContext context). {% stepper %} {% step %} ### Add a New Class File Right-click the Plugins folder in Solution Explorer, select Add > Class, and give it a descriptive name that reflects what the plugin does. For example: \ • CalculatePackageTotals.cs \ • CreateDirectiveSubmissions.cs {% endstep %} {% step %} ### Implement IXrmPlugin Your class must use the correct using directives and implement the required interface. Below is the standard boilerplate structure: ```cs using Xrm.Soft.Aer.SDK; using System; using System.Linq; using System.Collections.Generic; using System.Diagnostics; namespace ERP.Ezra360.Package.Plugins { public class CalculatePackageTotals : IXrmPlugin { private const decimal MaxTotalAmount = 1000000m; public void ExecutePlugin(PluginExecutionContext context) { var stopwatch = Stopwatch.StartNew(); context.Trace("CalculatePackageTotals: Execution started."); try { // Validate ValidateContext(context); var packageLineId = GetPackageLineId(context); context.Trace($"CalculatePackageTotals: Processing PackageLine ID: {packageLineId}"); // Get and validate lines var lines = GetPackageLines(context, packageLineId); if (!lines.Any()) { context.Trace("CalculatePackageTotals: No package lines found. Skipping update."); return; } // Calculate and validate total var total = CalculateTotal(lines); ValidateTotal(total); // Update package UpdatePackage(context, lines.First().PackageId.Value, total); stopwatch.Stop(); context.Trace($"CalculatePackageTotals: Completed successfully in {stopwatch.ElapsedMilliseconds}ms."); } catch (Exception ex) { context.Trace($"CalculatePackageTotals ERROR: {ex.Message}"); context.Trace($"CalculatePackageTotals Stack Trace: {ex.StackTrace}"); if (ex.InnerException != null) { context.Trace($"CalculatePackageTotals Inner Exception: {ex.InnerException.Message}"); } throw new InvalidPluginExecutionException($"CalculatePackageTotals failed: {ex.Message}", ex); } } private void ValidateContext(PluginExecutionContext context) { if (context == null) throw new ArgumentNullException(nameof(context)); if (context.Target == null) throw new InvalidOperationException("Target record is required."); } private Guid GetPackageLineId(PluginExecutionContext context) { var target = context.Target as BusinessEntity; if (target == null || !target.Id.HasValue || target.Id.Value == Guid.Empty) throw new InvalidOperationException("Valid target ID is required."); return target.Id.Value; } private List GetPackageLines(PluginExecutionContext context, Guid packageLineId) { var query = PackageSQL.GetPackageLines.Replace("@PackageLineId", $"'{packageLineId}'"); context.Trace($"CalculatePackageTotals: Executing query: {query}"); return context.BusinessActions .ExecuteListQuery(query) .ToList(); } private decimal CalculateTotal(List lines) { if (lines == null || lines.Count == 0) throw new InvalidOperationException("No package lines to calculate."); return Math.Round(lines.Sum(l => l.Amount), 2); } private void ValidateTotal(decimal total) { if (total < 0) throw new InvalidOperationException($"Total amount cannot be negative: {total:C}"); if (total > MaxTotalAmount) throw new InvalidOperationException($"Total amount {total:C} exceeds maximum allowed {MaxTotalAmount:C}"); } private void UpdatePackage(PluginExecutionContext context, Guid packageId, decimal total) { context.Trace($"CalculatePackageTotals: Updating Package ID: {packageId} with total: {total:C}"); var package = new BusinessEntity("Package") { Id = packageId, Attributes = new List { new EntityAttribute { SchemaName = "totalamount", Value = total } } }; context.BusinessActions.Update(package); context.Trace("CalculatePackageTotals: Package updated successfully."); } } public class PackageLine { public Guid Id { get; set; } public Guid? PackageId { get; set; } public decimal Amount { get; set; } public string ProductName { get; set; } public int Quantity { get; set; } } public static class PackageSQL { public const string GetPackageLines = @" SELECT Id, PackageId, ISNULL(Amount, 0) AS Amount, ProductName, Quantity FROM PackageLine WHERE Id = @PackageLineId"; } } ``` {% endstep %} {% step %} ### Key Context Methods All platform operations are accessed through context.BusinessActions. Below are the most commonly used methods:
{% hint style="info" %} Tip: Always wrap your plugin logic in a try/catch block. Unhandled exceptions in plugins will surface \ as generic platform errors and will not include your error message. {% endhint %} {% endstep %} {% endstepper %} ### 4.1 Accessing the Triggering Record The PluginExecutionContext exposes a Target property that represents the record that triggered the event. Cast it to BusinessEntity to access its fields: ```c# // Get the target record (the one that was created/updated/deleted) var target = (BusinessEntity)context.Target; // Access its Id Guid recordId = target.Id.Value; // Access an attribute value (if it was included in the trigger) var amount = target.Attributes .FirstOrDefault(a => a.SchemaName == "Amount")?.Value; ``` {% hint style="info" %} Note: The Target entity only contains attributes that were changed in the triggering operation, not the full record. To access fields that were not changed, use context.BusinessActions.RetrieveRecord() to fetch the full record from the database. {% endhint %} ## 5. Building the DLL in Visual Studio Once your plugin code is complete, you need to compile the project to produce a DLL file that will be uploaded to Ezra360. ### 5.1 Build the Solution Go to the menu bar and select Build > Build Solution, or press Ctrl + Shift + B. Visual Studio will compile all projects in the solution. {% hint style="info" %} The build must complete with zero errors. Warnings are acceptable. If there are errors, the DLL file will not be generated and any existing DLL at the output path may be stale or absent. {% endhint %} ### 5.2 Locate the Output DLL After a successful build, the compiled DLL is placed in: *ProjectFolder\bin\Debug\netcoreapp3.1\YourProjectName.dll* Navigate to this folder in Windows Explorer. The DLL filename matches your project name exactly. You will also see a .pdb file (debug symbols) and a .deps.json file — only the .dll needs to be uploaded. {% hint style="info" %} ✔ Tip: Always build in Debug mode when uploading to a sandbox or UAT environment. Use Release mode only for production deployments. Debug builds include additional diagnostic information that helps trace issues in Plugin Trace Logs. {% endhint %} ### 5.3 Build Configuration Reference
## 6. Uploading the DLL to Ezra360 After building the DLL, it must be uploaded to Ezra360 as an Xrm Assembly record. The assembly record holds the compiled code and serves as the container for all plugin classes and plugin message registrations. {% stepper %} {% step %} ### Navigate to Xrm Assemblies Log into your Ezra360 environment. From the top navigation bar, open the Customizations menu. Scroll down to Xrm Assemblies and click it.
{% endstep %} {% step %} ### Create or Update the Assembly If this is the first time you are uploading this DLL, click New to create a new assembly record. If the assembly already exists and you are updating it after a code change, click on the existing record. The assembly record form contains: * File — a file upload control to select your .dll file * Assembly Name — auto-populated from the DLL metadata after upload * Version — auto-populated with your build version number (e.g. 2026.5.28.1422) {% hint style="info" %} The version number in Ezra360 reflects your assembly version attribute in the .csproj file. It typically follows the format **Year.Month.Day.BuildNumber.** You can confirm you have the right version after upload. {% endhint %} {% endstep %} {% step %} ### Upload the DLL File Click the Choose File button in the assembly form, navigate to your bin/Debug/netcoreapp3.1/ folder, and select the .dll file. The Assembly Name and Version fields will auto-populate once the file is selected. Click Save & Close to complete the upload. The assembly is now registered in Ezra360 and ready for plugin message registration.
{% endstep %} {% endstepper %} ## 7. Registering Plugin Classes After uploading your assembly, you must register each plugin class you want to use. Plugin classes are listed under the XRM Plugin Classes tab on the assembly record. This step tells Ezra360 which C# classes in your DLL are valid plugins. ### 7.1 Adding a New Plugin Class On the assembly record, click the XRM Plugin Classes tab. Click Add New to open the Quick Create dialog.
Fill in the following fields: * Name — must match the class name exactly as it appears in your C# code * Plugin Type — select the appropriate type for plugins * Assembly — pre-filled with the current assembly record
## 8. Registering Plugin Messages A Plugin Message is the configuration record that tells Ezra360 when to fire a specific plugin class. It binds a plugin class to an entity and an execution step. \ Plugin messages are registered under the Plugin Messages tab on the assembly record. ### 8.1 Viewing Existing Plugin Messages
Each row in the Plugin Messages table represents one registration — one plugin bound to one entity and one execution step. ### 8.2 Adding a New Plugin Message Click Add New on the Plugin Messages tab to open the Quick Create dialog:
Fill in all required fields (marked with a red asterisk):
## 9. Updating an Existing Assembly After your initial deployment, subsequent code changes require re-uploading the DLL. The process is similar to the initial upload but with a few important differences. ### 8.1 Re-Upload Process 1. Make your code changes in Visual Studio 2. Rebuild the solution (Ctrl + Shift + B) and confirm zero errors 3. Navigate to Customizations > Xrm Assemblies in Ezra360 4. Click on the existing assembly record 5. Click the upload/attachment icon next to the Name field (the paperclip icon) 6. Select the updated .dll from your bin/Debug/netcoreapp3.1/ folder 7. The Version field will update to reflect the new build version 8. Click Save {% hint style="info" %} ✔ Tip: You do not need to re-register plugin messages after re-uploading a DLL. Your existing plugin message registrations continue to work as long as the class names remain the same. Only add new registrations when you add new plugin classes. {% endhint %} ## 10. Execution Steps Reference Execution steps define the precise moment in the entity's lifecycle when a plugin fires. Choosing the wrong execution step is a common source of bugs — for example, using PreUpdate when you need the record to already be saved before reading it back. ### 10.1 Create Events
### 10.2 Update Events
### 10.3 Retrieve Events
### 10.4 Delete Events
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ezra360.com/customization/plugins.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.