FlintsLabs.D365.ODataClient 1.2.27

FlintsLabs.D365.ODataClient

A fluent OData client for Microsoft Dynamics 365 Finance & Operations.

Features

• 🔗 Fluent API - Chainable query builder with IntelliSense support
• 🔍 LINQ Support - Write queries using lambda expressions
• ➕ Expand Support - Easily expand navigation properties (query.Expand("Nav") or query.Expand(x => x.Nav))
• 📨 Custom Headers - Add custom headers like Prefer to requests
• 🏢 Cross-Company - Query across legal entities
• 🔐 Multi-Auth Support - Azure AD (Cloud), ADFS (On-Premise), and Dataverse
• 📦 CRUD Operations - Full Create, Read, Update, Delete support
• 🌐 Multi-Source - Connect to multiple D365 instances (F&O, Dataverse) simultaneously

Table of Contents

• Installation
• Configuration
  • Option 1: Azure AD (Cloud)
  • Option 2: ADFS (On-Premise)
  • Option 3: Dataverse
  • Option 4: Multiple Sources
• Usage in ASP.NET Core
  • Quick Start (Single Source)
  • Advanced (Multiple Sources)
  • Naming Convention
• CRUD Operations
• API Reference
• Requirements

Installation

dotnet add package FlintsLabs.D365.ODataClient

Configuration

Option 1: Azure AD (Cloud D365)

// Program.cs - Fluent Builder using Enum
builder.Services.AddD365ODataClient(d365 => 
{
    d365.UseAzureAD()
        .WithClientId("your-client-id")
        .WithClientSecret("your-client-secret")
        .WithTenantId("your-tenant-id")
        .WithResource("https://your-org.operations.dynamics.com");
});

// appsettings.json
{
  "D365": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "TenantId": "your-tenant-id",
    "Resource": "https://your-org.operations.dynamics.com"
  }
}

// Or from configuration
builder.Services.AddD365ODataClient(builder.Configuration, "D365");

Option 2: ADFS (On-Premise D365)

// Program.cs - Fluent Builder for ADFS
builder.Services.AddD365ODataClient(d365 => 
{
    d365.UseADFS()
        .WithTokenEndpoint("https://fs.your-company.com/adfs/oauth2/token")
        .WithClientId("your-client-id")
        .WithClientSecret("your-client-secret")
        .WithResource("https://ax.your-company.com")
        .WithOrganizationUrl("https://ax.your-company.com/namespaces/AXSF/");
});

// appsettings.json for ADFS
{
  "D365OnPrem": {
    "TenantId": "adfs",
    "TokenEndpoint": "https://fs.your-company.com/adfs/oauth2/token",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "Resource": "https://ax.your-company.com",
    "OrganizationUrl": "https://ax.your-company.com/namespaces/AXSF/",
    "GrantType": "client_credentials"
  }
}

// From configuration (auto-detects ADFS when TenantId="adfs" or TokenEndpoint is set)
builder.Services.AddD365ODataClient(builder.Configuration, "D365OnPrem");

Option 3: Microsoft Dataverse (CRM / Power Platform)

// Program.cs - Fluent Builder for Dataverse
builder.Services.AddD365ODataClient(D365ServiceScope.Dataverse, d365 => 
{
    d365.WithClientId("your-client-id")
        .WithClientSecret("your-client-secret")
        .WithTenantId("your-tenant-id")
        .WithResource("https://org.api.crm5.dynamics.com")
        .WithOrganizationUrl("https://org.api.crm5.dynamics.com/api/data/v9.2/")
        .WithScope("https://org.api.crm5.dynamics.com/.default")
        .WithBooleanFormatting(D365BooleanFormatting.Literal);
});

// appsettings.json
{
  "DataverseConfigs": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "TenantId": "your-tenant-id",
    "Resource": "https://org.api.crm5.dynamics.com",
    "OrganizationUrl": "https://org.api.crm5.dynamics.com/api/data/v9.2/",
    "Scope": "https://org.api.crm5.dynamics.com/.default",
    "BooleanFormatting": "Literal"
  }
}

// From configuration
builder.Services.AddD365ODataClient(
    D365ServiceScope.Dataverse, 
    builder.Configuration, 
    "DataverseConfigs");

Option 4: Multiple D365 Sources (Cloud + On-Premise)

// Program.cs - Named Services for multiple D365 sources
builder.Services.AddD365ODataClient(D365ServiceScope.Cloud, d365 => 
{
    d365.UseAzureAD()
        .WithClientId("cloud-client-id")
        .WithClientSecret("cloud-secret")
        .WithTenantId("cloud-tenant-id")
        .WithResource("https://cloud.operations.dynamics.com");
});

builder.Services.AddD365ODataClient(D365ServiceScope.OnPrem, d365 => 
{
    d365.UseADFS()
        .WithTokenEndpoint("https://fs.company.com/adfs/oauth2/token")
        .WithClientId("onprem-client-id")
        .WithClientSecret("onprem-secret")
        .WithResource("https://ax.company.com")
        .WithOrganizationUrl("https://ax.company.com/namespaces/AXSF/");
});

// Or from configuration with named sections
builder.Services.AddD365ODataClient(D365ServiceScope.Cloud, builder.Configuration, "D365Cloud");
builder.Services.AddD365ODataClient(D365ServiceScope.OnPrem, builder.Configuration, "D365OnPrem");

Usage in ASP.NET Core

Quick Start (Single D365 Source)

Use this pattern when connecting to one D365 instance only.

Step 1: Configure appsettings.json

{
  "D365": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "TenantId": "your-tenant-id",
    "Resource": "https://your-org.operations.dynamics.com"
  }
}

Step 2: Register in Program.cs

// Register D365 client (no name = "Default")
builder.Services.AddD365ODataClient(builder.Configuration, "D365");

Step 3: Inject ID365Service in Controller

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly ID365Service _d365;

    // DI will inject ID365Service automatically
    public ProductsController(ID365Service d365)
    {
        _d365 = d365;
    }

    [HttpGet]
    public async Task<IActionResult> GetProducts()
    {
        var products = await _d365.Entity<Product>("ReleasedProductsV2")
            .CrossCompany()
            .Where(p => p.ItemNumber.StartsWith("A"))
            .Take(10)
            .ToListAsync();

        return Ok(products);
    }
    
    // IN clause (multiple values) - auto-generates OR filter
    [HttpGet("by-codes")]
    public async Task<IActionResult> GetProductsByCodes([FromQuery] string[] codes)
    {
        var products = await _d365.Entity<Product>("ReleasedProductsV2")
            .CrossCompany()
            .Where(p => codes.Contains(p.ItemNumber))  // -> (ItemNumber eq 'A001' or ItemNumber eq 'A002' ...)
            .ToListAsync();

        return Ok(products);
    }
}

Type-Safe Entity Names (User-Defined Enum)

Instead of using magic strings for entity names, you can define your own enum for type-safety and IntelliSense support.

Step 1: Define Your Entity Enum

using System.ComponentModel;

namespace MyApp.D365;

/// <summary>
/// Custom D365 Entity names for type-safe queries.
/// Use [Description] attribute to map to actual D365 entity name.
/// If no [Description], the enum member name is used.
/// </summary>
public enum D365Entity
{
    // CUSTOMERS & VENDORS
    [Description("CustomersV3")]
    Customer,
    
    [Description("VendorsV2")]
    Vendor,
    
    // PRODUCTS
    [Description("ReleasedProductsV2")]
    Product,
    
    [Description("InventItemBarcodes")]
    Barcode,
    
    // ORDERS
    [Description("SalesOrderHeadersV2")]
    SalesOrderHeader,
    
    [Description("SalesOrderLines")]
    SalesOrderLine,
    
    [Description("PurchaseOrderHeadersV2")]
    PurchaseOrderHeader,
    
    // FINANCE
    [Description("LedgerJournalHeaders")]
    JournalHeader,
    
    // COMMON (no [Description] - uses enum name directly)
    LegalEntities,
    Companies,
    Currencies
}

Step 2: Use Enum in Queries

// BEFORE: Magic string (error-prone)
var customers = await d365.Entity<Customer>("CustomersV3").ToListAsync();

// AFTER: Type-safe enum (recommended)
var customers = await d365.Entity<Customer>(D365Entity.Customer).ToListAsync();

// Works with all query methods
var products = await d365.Entity<Product>(D365Entity.Product)
    .CrossCompany()
    .Where(p => p.IsActive == true)
    .Take(100)
    .ToListAsync();

Resolution Priority

Migration Guide (String → Enum)

Before (v1.2.15 and earlier):

public class ProductController : ControllerBase
{
    private readonly ID365Service _d365;
    
    public async Task<IActionResult> GetProducts()
    {
        var products = await _d365.Entity<Product>("ReleasedProductsV2")
            .CrossCompany()
            .ToListAsync();
        return Ok(products);
    }
}

After (v1.2.16+):

// 1. Create enum file: Enums/D365Entity.cs
public enum D365Entity
{
    [Description("ReleasedProductsV2")]
    Product
}

// 2. Update controller to use enum
public class ProductController : ControllerBase
{
    private readonly ID365Service _d365;
    
    public async Task<IActionResult> GetProducts()
    {
        var products = await _d365.Entity<Product>(D365Entity.Product)  // <- Changed!
            .CrossCompany()
            .ToListAsync();
        return Ok(products);
    }
}

Benefits

• ✅ No typos - Compiler catches invalid entity names
• ✅ IntelliSense - Auto-complete entity names
• ✅ Centralized - All entity names in one file
• ✅ Refactor-safe - Rename enum updates all usages
• ✅ Documentation - XML comments on enum members

Performance

Recommendation: Use Enum for most cases (type-safety + cached performance). Use String only in extremely high-frequency loops where every nanosecond matters.

Multiple Enum Types

You can organize entities into multiple enum types (e.g., by module). Each enum type is cached separately:

// Sales module entities
public enum SalesEntity
{
    [Description("SalesOrderHeadersV2")]
    SalesOrder,
    
    [Description("SalesOrderLines")]
    SalesOrderLine
}

// Purchasing module entities
public enum PurchaseEntity
{
    [Description("PurchaseOrderHeadersV2")]
    PurchaseOrder
}

// Usage - both work correctly, no conflicts
var orders = await d365.Entity<SO>(SalesEntity.SalesOrder).ToListAsync();
var pos = await d365.Entity<PO>(PurchaseEntity.PurchaseOrder).ToListAsync();

Advanced (Multiple D365 Sources)

Use this pattern when connecting to multiple D365 instances (e.g., Cloud + On-Premise, Production + Sandbox).

Step 1: Configure appsettings.json with multiple sections

{
  "D365Cloud": {
    "ClientId": "cloud-client-id",
    "ClientSecret": "cloud-secret",
    "TenantId": "cloud-tenant-id",
    "Resource": "https://cloud.operations.dynamics.com"
  },
  "D365OnPrem": {
    "TenantId": "adfs",
    "TokenEndpoint": "https://fs.company.com/adfs/oauth2/token",
    "ClientId": "onprem-client-id",
    "ClientSecret": "onprem-secret",
    "Resource": "https://ax.company.com",
    "OrganizationUrl": "https://ax.company.com/namespaces/AXSF/"
  }
}

Step 2: Register with Names in Program.cs

⚠️ Important: The name you use here must match what you use in GetService("name") later!

// Option A: Use Enum (recommended - prevents typos)
builder.Services.AddD365ODataClient(D365ServiceScope.Cloud, builder.Configuration, "D365Cloud");
builder.Services.AddD365ODataClient(D365ServiceScope.OnPrem, builder.Configuration, "D365OnPrem");

// Option B: Use custom string names (flexible)
builder.Services.AddD365ODataClient("Org1-Cloud", builder.Configuration, "D365Cloud");
builder.Services.AddD365ODataClient("Org2-OnPrem", builder.Configuration, "D365OnPrem");

D365 client 'Cloud' is already registered. Use a unique name for each client.

Step 3: Inject ID365ServiceFactory in Controller

[ApiController]
[Route("api/[controller]")]
public class SyncController : ControllerBase
{
    private readonly ID365ServiceFactory _d365Factory;

    // DI will inject the factory (not individual services)
    public SyncController(ID365ServiceFactory d365Factory)
    {
        _d365Factory = d365Factory;
    }

    [HttpGet("cloud-products")]
    public async Task<IActionResult> GetFromCloud()
    {
        // Get service by the SAME name used in Program.cs
        var d365 = _d365Factory.GetService("Cloud");  // Matches D365ServiceScope.Cloud
        
        var products = await d365.Entity<Product>("ReleasedProductsV2")
            .CrossCompany()
            .Take(10)
            .ToListAsync();

        return Ok(products);
    }

    [HttpGet("onprem-orders")]
    public async Task<IActionResult> GetFromOnPrem()
    {
        var d365 = _d365Factory.GetService("OnPrem");  // Matches D365ServiceScope.OnPrem
        
        var orders = await d365.Entity<SalesOrder>("SalesOrderHeadersV2")
            .CrossCompany()
            .Take(10)
            .ToListAsync();

        return Ok(orders);
    }
}

Naming Convention Summary

💡 Tip: Use D365ServiceScope enum to prevent typos. The enum values are: Default, Cloud, OnPrem, Dataverse

CRUD Operations

// Create
await _d365.Entity<Customer>("CustomersV3").AddAsync(newCustomer);

// Read
var customers = await _d365.Entity<Customer>("CustomersV3")
    .CrossCompany()
    .Where(c => c.CustomerAccount == "CUST001")
    .ToListAsync();

// Update
await _d365.Entity<Customer>("CustomersV3")
    .AddIdentity("CustomerAccount", "CUST001")
    .AddIdentity("dataAreaId", "usmf")
    .CrossCompany()
    .UpdateAsync(new { CustomerName = "Updated Name" });

// Update by Key (Where + [OdataKey] attribute required)
await _d365.Entity<EgrHeadETHTable>("rvl_egrheadeths")
    .Where(x => x.Id == headId)
    .UpdateAsync(new { rvl_wmsstatus = false });

// Delete
await _d365.Entity<Customer>("CustomersV3")
    .AddIdentity("CustomerAccount", "CUST001")
    .AddIdentity("dataAreaId", "usmf")
    .CrossCompany()
    .DeleteAsync();

OdataKey Update/Delete Examples

1) Single Key

using FlintsLabs.D365.ODataClient.Attributes;
using System.Text.Json.Serialization;

public class EgrHeadETHTable
{
    [OdataKey]
    [JsonPropertyName("rvl_egrheadethid")]
    public Guid Id { get; set; }
}

Update

await _d365.Entity<EgrHeadETHTable>("rvl_egrheadeths")
    .Where(x => x.Id == headId)
    .UpdateAsync(new { rvl_wmsstatus = false });

Delete

await _d365.Entity<EgrHeadETHTable>("rvl_egrheadeths")
    .Where(x => x.Id == headId)
    .DeleteAsync();

2) Composite Key

using FlintsLabs.D365.ODataClient.Attributes;
using System.Text.Json.Serialization;

public class SalesLine
{
    [OdataKey]
    [JsonPropertyName("dataAreaId")]
    public string DataAreaId { get; set; } = "";

    [OdataKey]
    [JsonPropertyName("SalesId")]
    public string SalesId { get; set; } = "";

    [OdataKey]
    [JsonPropertyName("LineNumber")]
    public decimal LineNumber { get; set; }
}

Update (ต้องระบุ key ให้ครบ)

await _d365.Entity<SalesLine>("SalesOrderLines")
    .Where(x => x.DataAreaId == "usmf" && x.SalesId == "SO-001" && x.LineNumber == 1m)
    .UpdateAsync(new { QtyOrdered = 5 });

Delete (ต้องระบุ key ให้ครบ)

await _d365.Entity<SalesLine>("SalesOrderLines")
    .Where(x => x.DataAreaId == "usmf" && x.SalesId == "SO-001" && x.LineNumber == 1m)
    .DeleteAsync();

API Reference

Query Methods

Execute Methods

Requirements

• .NET 8.0 or later
• Microsoft Dynamics 365 Finance & Operations
• Azure AD: App Registration with D365 F&O API permissions
• ADFS: Native Application registered in ADFS

Development

Running Tests

This project includes both Integration Tests (xUnit) and an interactive Test Console.

1. Configuration:

   • Rename appsettings.example.json to appsettings.json in the test project.
   • Update with your real D365 credentials (this file is git-ignored).

2. Run xUnit Tests (Automated):

   dotnet test
   

3. Run Test Console (Interactive):

   cd FlintsLabs.D365.ODataClient.TestConsole
   dotnet run
   

Logging

All HTTP requests are logged with full URLs. Enable Debug level to see request bodies:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Example output:

info: D365 GET: https://org1.../data/ReleasedProductsV2?cross-company=true&$top=3
dbug: Request Body: {"SalesOrderNumber":"SO-001",...}

Verification (.NET 10)

This library is verified to support .NET 10. To verify compatibility:

dotnet test -f net10.0

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.