mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 09:26:52 +01:00
Add P0 integration and control add-in runtime guidance (#100)
* Add P0 integration and control add-in guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 02baffe8-0600-430d-81fa-a9993685e7cb * Correct API part multiplicity guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 02baffe8-0600-430d-81fa-a9993685e7cb * Refine API part multiplicity guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1c37924e-9749-4e63-9d58-bd73d659f736 --------- Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
This commit is contained in:
Jesper Schulz-Wedde
GitHub
parent
e0ebdd35c7
commit
0bb1065bc3
16 changed files with 526 additions and 12 deletions
|
|
@ -0,0 +1,3 @@
|
|||
function loadPackagedTemplate(url) {
|
||||
return $.get(url).done(renderTemplate);
|
||||
}
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
function loadPackagedTemplate(url) {
|
||||
return $.ajax({
|
||||
url: url,
|
||||
xhrFields: {
|
||||
withCredentials: true
|
||||
}
|
||||
}).done(renderTemplate);
|
||||
}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
bc-version: [all]
|
||||
domain: ui
|
||||
keywords: [control-add-in, packaged-resource, ajax, withcredentials, xhrfields, jquery]
|
||||
technologies: [javascript]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Load packaged control add-in resources with credentialed AJAX
|
||||
|
||||
## Description
|
||||
|
||||
JavaScript in a Business Central control add-in can load a static resource from its extension package with AJAX, but the request needs the Business Central context and cookies. Set `xhrFields.withCredentials = true`; shorthand calls such as `$.get` omit that setting and can work during development yet fail in production.
|
||||
|
||||
## Best Practice
|
||||
|
||||
Use an AJAX form that explicitly enables `withCredentials` whenever a control add-in requests a packaged static resource. Keep this rule scoped to resources served from the add-in package; it is not generic advice to attach credentials to arbitrary external requests.
|
||||
|
||||
See sample: `control-addin-package-resource-ajax-needs-withcredentials.good.js`.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
Using `$.get(url)` or an `XMLHttpRequest` without `withCredentials = true` to retrieve package content. The request can lack the context and cookies required by the Business Central service.
|
||||
|
||||
See sample: `control-addin-package-resource-ajax-needs-withcredentials.bad.js`.
|
||||
|
||||
## Source
|
||||
|
||||
[Control add-in object: Loading static resources using AJAX requests](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-control-addin-object#loading-static-resources-using-ajax-requests).
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
function startSendingRows(rows) {
|
||||
window.setInterval(() => {
|
||||
Microsoft.Dynamics.NAV.InvokeExtensibilityMethod(
|
||||
"StoreRows",
|
||||
[JSON.stringify(rows)],
|
||||
false);
|
||||
}, 100);
|
||||
}
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
const pendingChunks = [];
|
||||
let callInProgress = false;
|
||||
let transferHalted = false;
|
||||
|
||||
function sendRows(rows, maxArgumentsBytes) {
|
||||
if (transferHalted)
|
||||
throw new Error("Retry or discard the failed chunk before sending more rows.");
|
||||
|
||||
const encoder = new TextEncoder();
|
||||
const chunks = [];
|
||||
let chunk = [];
|
||||
const argumentBytes = (payload) =>
|
||||
encoder.encode(JSON.stringify([payload])).length;
|
||||
|
||||
for (const row of rows) {
|
||||
if (argumentBytes(JSON.stringify([row])) > maxArgumentsBytes)
|
||||
throw new Error("A row exceeds the configured payload limit.");
|
||||
|
||||
const candidate = JSON.stringify([...chunk, row]);
|
||||
|
||||
if (argumentBytes(candidate) <= maxArgumentsBytes) {
|
||||
chunk.push(row);
|
||||
continue;
|
||||
}
|
||||
|
||||
chunks.push(JSON.stringify(chunk));
|
||||
chunk = [row];
|
||||
}
|
||||
|
||||
if (chunk.length > 0)
|
||||
chunks.push(JSON.stringify(chunk));
|
||||
|
||||
pendingChunks.push(...chunks);
|
||||
sendNextChunk();
|
||||
}
|
||||
|
||||
function sendNextChunk() {
|
||||
if (callInProgress || pendingChunks.length === 0)
|
||||
return;
|
||||
|
||||
callInProgress = true;
|
||||
const payload = pendingChunks[0];
|
||||
Microsoft.Dynamics.NAV.InvokeExtensibilityMethod(
|
||||
"StoreRows",
|
||||
[payload],
|
||||
false,
|
||||
() => {
|
||||
pendingChunks.shift();
|
||||
callInProgress = false;
|
||||
sendNextChunk();
|
||||
},
|
||||
() => {
|
||||
callInProgress = false;
|
||||
transferHalted = true;
|
||||
showTransferError();
|
||||
});
|
||||
}
|
||||
|
||||
function retryFailedChunk() {
|
||||
if (!transferHalted)
|
||||
return;
|
||||
|
||||
transferHalted = false;
|
||||
sendNextChunk();
|
||||
}
|
||||
|
||||
function discardFailedChunk() {
|
||||
if (!transferHalted)
|
||||
return;
|
||||
|
||||
pendingChunks.shift();
|
||||
transferHalted = false;
|
||||
sendNextChunk();
|
||||
}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
bc-version: [20..]
|
||||
domain: ui
|
||||
keywords: [control-add-in, invokeextensibilitymethod, success-callback, throttling, payload, reduced-functionality]
|
||||
technologies: [javascript]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Serialize control add-in AL calls and keep payloads small
|
||||
|
||||
## Description
|
||||
|
||||
`InvokeExtensibilityMethod` crosses from a control add-in into the Business Central service. Repeated calls that outpace AL execution fill the communication channel, trigger reduced-functionality warnings, and can be queued, throttled, or rejected; an oversized single payload can also be rejected immediately. The success and error callbacks exist so the add-in can bound this traffic.
|
||||
|
||||
## Best Practice
|
||||
|
||||
Send byte-bounded chunks and invoke the next AL event only from the previous call's completion callback. Handle the error callback and stop until the caller explicitly retries or discards the failed chunk. There is no universal safe threshold, so measure the serialized argument array, reserve transport headroom below the server's `ClientServicesMaxUploadSize`, and reject an individual item that exceeds the configured budget.
|
||||
|
||||
See sample: `control-addin-throttle-al-calls-and-payload-size.good.js`.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
Calling `InvokeExtensibilityMethod` on an interval without tracking completion, recursively creating intervals, or serializing an entire unbounded dataset into one call. These patterns can overwhelm the client-service channel or exceed the upload limit.
|
||||
|
||||
See sample: `control-addin-throttle-al-calls-and-payload-size.bad.js`.
|
||||
|
||||
## Source
|
||||
|
||||
[Control add-in performance best practices](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-control-addin-bestpractices), [InvokeExtensibilityMethod](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods/devenv-invokeextensibility-method), and [control add-in resiliency](https://learn.microsoft.com/dynamics365/business-central/across-controladdin-resiliency).
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
page 50353 "WS Order API Bad"
|
||||
{
|
||||
PageType = API;
|
||||
APIPublisher = 'contoso';
|
||||
APIGroup = 'sales';
|
||||
APIVersion = 'v1.0';
|
||||
EntityName = 'order';
|
||||
EntitySetName = 'orders';
|
||||
ODataKeyFields = SystemId;
|
||||
SourceTable = "Sales Header";
|
||||
|
||||
layout
|
||||
{
|
||||
area(content)
|
||||
{
|
||||
repeater(records)
|
||||
{
|
||||
part(lines; "WS Order Line API Bad")
|
||||
{
|
||||
EntityName = 'orderLine';
|
||||
EntitySetName = 'orderLines';
|
||||
Multiplicity = ZeroOrOne;
|
||||
SubPageLink = "Order No." = Field("No.");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
table 50353 "WS Order Line Bad"
|
||||
{
|
||||
fields
|
||||
{
|
||||
field(1; "Entry No."; Integer)
|
||||
{
|
||||
AutoIncrement = true;
|
||||
}
|
||||
field(2; "Order No."; Code[20])
|
||||
{
|
||||
TableRelation = "Sales Header"."No.";
|
||||
}
|
||||
}
|
||||
|
||||
keys
|
||||
{
|
||||
key(PK; "Entry No.")
|
||||
{
|
||||
Clustered = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
page 50354 "WS Order Line API Bad"
|
||||
{
|
||||
PageType = API;
|
||||
APIPublisher = 'contoso';
|
||||
APIGroup = 'sales';
|
||||
APIVersion = 'v1.0';
|
||||
EntityName = 'orderLine';
|
||||
EntitySetName = 'orderLines';
|
||||
ODataKeyFields = SystemId;
|
||||
SourceTable = "WS Order Line Bad";
|
||||
|
||||
layout
|
||||
{
|
||||
area(content)
|
||||
{
|
||||
repeater(records)
|
||||
{
|
||||
field(id; Rec.SystemId)
|
||||
{
|
||||
Editable = false;
|
||||
}
|
||||
field(orderNumber; Rec."Order No.")
|
||||
{
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,151 @@
|
|||
page 50350 "WS Order API"
|
||||
{
|
||||
PageType = API;
|
||||
APIPublisher = 'contoso';
|
||||
APIGroup = 'sales';
|
||||
APIVersion = 'v1.0';
|
||||
EntityName = 'order';
|
||||
EntitySetName = 'orders';
|
||||
ODataKeyFields = SystemId;
|
||||
SourceTable = "Sales Header";
|
||||
|
||||
layout
|
||||
{
|
||||
area(content)
|
||||
{
|
||||
repeater(records)
|
||||
{
|
||||
field(id; Rec.SystemId)
|
||||
{
|
||||
Editable = false;
|
||||
}
|
||||
part(lines; "WS Order Line API")
|
||||
{
|
||||
EntityName = 'orderLine';
|
||||
EntitySetName = 'orderLines';
|
||||
SubPageLink = "Order Id" = Field(SystemId);
|
||||
}
|
||||
part(summary; "WS Order Summary API")
|
||||
{
|
||||
EntityName = 'orderSummary';
|
||||
Multiplicity = ZeroOrOne;
|
||||
SubPageLink = "Order Id" = Field(SystemId);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
table 50350 "WS Order Line"
|
||||
{
|
||||
fields
|
||||
{
|
||||
field(1; "Entry No."; Integer)
|
||||
{
|
||||
AutoIncrement = true;
|
||||
}
|
||||
field(2; "Order Id"; Guid)
|
||||
{
|
||||
TableRelation = "Sales Header".SystemId;
|
||||
}
|
||||
field(3; Description; Text[100])
|
||||
{
|
||||
}
|
||||
}
|
||||
|
||||
keys
|
||||
{
|
||||
key(PK; "Entry No.")
|
||||
{
|
||||
Clustered = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
table 50351 "WS Order Summary"
|
||||
{
|
||||
fields
|
||||
{
|
||||
field(1; "Order Id"; Guid)
|
||||
{
|
||||
TableRelation = "Sales Header".SystemId;
|
||||
}
|
||||
field(2; Summary; Text[100])
|
||||
{
|
||||
}
|
||||
}
|
||||
|
||||
keys
|
||||
{
|
||||
key(PK; "Order Id")
|
||||
{
|
||||
Clustered = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
page 50351 "WS Order Line API"
|
||||
{
|
||||
PageType = API;
|
||||
APIPublisher = 'contoso';
|
||||
APIGroup = 'sales';
|
||||
APIVersion = 'v1.0';
|
||||
EntityName = 'orderLine';
|
||||
EntitySetName = 'orderLines';
|
||||
ODataKeyFields = SystemId;
|
||||
SourceTable = "WS Order Line";
|
||||
DelayedInsert = true;
|
||||
|
||||
layout
|
||||
{
|
||||
area(content)
|
||||
{
|
||||
repeater(records)
|
||||
{
|
||||
field(id; Rec.SystemId)
|
||||
{
|
||||
Editable = false;
|
||||
}
|
||||
field(orderId; Rec."Order Id")
|
||||
{
|
||||
}
|
||||
field(description; Rec.Description)
|
||||
{
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
page 50352 "WS Order Summary API"
|
||||
{
|
||||
PageType = API;
|
||||
APIPublisher = 'contoso';
|
||||
APIGroup = 'sales';
|
||||
APIVersion = 'v1.0';
|
||||
EntityName = 'orderSummary';
|
||||
EntitySetName = 'orderSummaries';
|
||||
ODataKeyFields = SystemId;
|
||||
SourceTable = "WS Order Summary";
|
||||
DelayedInsert = true;
|
||||
|
||||
layout
|
||||
{
|
||||
area(content)
|
||||
{
|
||||
repeater(records)
|
||||
{
|
||||
field(id; Rec.SystemId)
|
||||
{
|
||||
Editable = false;
|
||||
}
|
||||
field(orderId; Rec."Order Id")
|
||||
{
|
||||
}
|
||||
field(summary; Rec.Summary)
|
||||
{
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
bc-version: [17..]
|
||||
domain: web-services
|
||||
keywords: [api-page, page-part, subpagelink, systemid, multiplicity, deep-insert, navigation-property]
|
||||
technologies: [al]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Link API parts on SystemId and choose the correct multiplicity
|
||||
|
||||
## Description
|
||||
|
||||
`Multiplicity` is available from runtime 6.3 (Business Central 17.3) and defaults an API page part to a 1:N collection. The multiplicity-specific guidance therefore does not apply to BC 17.0 through 17.2. An API page part creates an OData navigation property and, for collection multiplicity, enables deep insert of child entities. When a custom parent API is keyed by its immutable `SystemId`, its child should carry a related GUID foreign key so the navigation constraint uses that same stable external identity. `Multiplicity` controls whether metadata exposes an object (`ZeroOrOne`) or a collection (`Many`).
|
||||
|
||||
## Best Practice
|
||||
|
||||
Define the child foreign key as `Guid` with a `TableRelation` to the parent table's `SystemId`, then use `SubPageLink = "<Parent Id>" = Field(SystemId)` on the parent API page. A child collection may omit `Multiplicity` and rely on the default 1:N relationship, or declare `Multiplicity = Many` explicitly. Set `Multiplicity = ZeroOrOne` when the intended navigation metadata is a singleton.
|
||||
|
||||
See sample: `link-api-parts-on-systemid-and-set-multiplicity.good.al`.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
On a parent API with `ODataKeyFields = SystemId`, linking a child business field such as `"Order No."` to the parent's `"No."` creates a second identity scheme for navigation instead of using the contract's stable GUID. A separate defect is an explicit `Multiplicity` that conflicts with the intended shape, such as `ZeroOrOne` on an order-lines collection or `Many` on a singleton. Do not treat omission alone as a defect: it is valid for a collection because the default is 1:N, while an intended singleton must explicitly use `Multiplicity = ZeroOrOne`.
|
||||
|
||||
See sample: `link-api-parts-on-systemid-and-set-multiplicity.bad.al`.
|
||||
|
||||
## Source
|
||||
|
||||
[Developing a custom API](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-develop-custom-api) and [Multiplicity property](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/properties/devenv-multiplicity-property).
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
query 50355 "WS Webhook Customer Query"
|
||||
{
|
||||
QueryType = API;
|
||||
APIPublisher = 'contoso';
|
||||
APIGroup = 'sales';
|
||||
APIVersion = 'v1.0';
|
||||
EntityName = 'webhookCustomer';
|
||||
EntitySetName = 'webhookCustomers';
|
||||
|
||||
elements
|
||||
{
|
||||
dataitem(customer; Customer)
|
||||
{
|
||||
column(id; SystemId)
|
||||
{
|
||||
}
|
||||
column(displayName; Name)
|
||||
{
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
function receiveBusinessCentralWebhook(request, response) {
|
||||
processNotifications(request.body.value);
|
||||
response.sendStatus(200);
|
||||
}
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
page 50354 "WS Webhook Customer API"
|
||||
{
|
||||
PageType = API;
|
||||
APIPublisher = 'contoso';
|
||||
APIGroup = 'sales';
|
||||
APIVersion = 'v1.0';
|
||||
EntityName = 'webhookCustomer';
|
||||
EntitySetName = 'webhookCustomers';
|
||||
ODataKeyFields = SystemId;
|
||||
SourceTable = Customer;
|
||||
|
||||
layout
|
||||
{
|
||||
area(content)
|
||||
{
|
||||
repeater(records)
|
||||
{
|
||||
field(id; Rec.SystemId)
|
||||
{
|
||||
Editable = false;
|
||||
}
|
||||
field(displayName; Rec.Name)
|
||||
{
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
function receiveBusinessCentralWebhook(request, response) {
|
||||
const validationToken = request.query.validationToken;
|
||||
|
||||
if (typeof validationToken === "string") {
|
||||
response.status(200).type("text/plain").send(validationToken);
|
||||
return;
|
||||
}
|
||||
|
||||
processNotifications(request.body.value);
|
||||
response.sendStatus(200);
|
||||
}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
bc-version: [all]
|
||||
domain: web-services
|
||||
keywords: [webhook, subscription, validationtoken, expirationdatetime, webhook-supported-resources, api-page, sourcetabletemporary, querytype]
|
||||
technologies: [al, javascript]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Verify webhook eligibility and complete every validationToken handshake
|
||||
|
||||
## Description
|
||||
|
||||
Business Central can subscribe only to eligible API pages, not every endpoint that can be read through an API. Webhooks exclude API queries, temporary API pages, pages with composite OData keys, pages over system tables, and pages over Job Queue Entry (table 472); the environment's `webhookSupportedResources` endpoint is authoritative. Creating and renewing a subscription both call the `notificationUrl` with `validationToken`, and both fail unless the subscriber returns that token in the response body with `200 OK`.
|
||||
|
||||
## Best Practice
|
||||
|
||||
Before creating a subscription, confirm the resource appears in `webhookSupportedResources` and that a custom endpoint is an API page with a single stable key over an eligible persistent table. Use one validation path that echoes `validationToken` for both create (`POST`) and renew (`PATCH`) handshakes. Track `expirationDateTime` and renew before expiry: online subscriptions expire after three days, while on-premises lifetime defaults to three days and can be changed with `ApiSubscriptionExpiration`.
|
||||
|
||||
See samples: `webhook-eligibility-and-validationtoken-renewal.good.al` and `webhook-eligibility-and-validationtoken-renewal.good.js`.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
Attempting to subscribe to an API query, temporary/composite/system-table/Job Queue Entry API page, or assuming a successful create handshake makes renewal automatic. Composite includes an explicit multi-field `ODataKeyFields` and a missing `ODataKeyFields` when the source table's primary key has multiple fields. A renewal issues the same validation challenge; a notification handler that ignores the query-string token cannot create or renew the subscription.
|
||||
|
||||
See samples: `webhook-eligibility-and-validationtoken-renewal.bad.al` and `webhook-eligibility-and-validationtoken-renewal.bad.js`.
|
||||
|
||||
## Source
|
||||
|
||||
[Working with webhooks](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-subscriptions) and [Update subscriptions](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/api-reference/v2.0/api/dynamics_subscriptions_update).
|
||||
Loading…
Add table
Add a link
Reference in a new issue