import { Callout } from "zudoku/ui/Callout";

# Marketplace module

**Module:** `businessdev.ALbuild.Marketplace`  •  **Tier:** Licensed  •  **Cmdlets:** 7

The **Marketplace** module ingests apps to Microsoft Marketplace (AppSource) via Partner Center — authentication, product/submission lookup, creating submissions, submitting, waiting for validation and promotion. This is a **licensed** feature.

<Callout type="caution" title="Licensing">
Cmdlets in this module are part of a licensed tier and call `Assert-ALbuildLicensed` on entry. Without a valid ALbuild license they fail with clear remediation guidance. See [Licensing & tiers](../concepts/licensing).
</Callout>

## Cmdlets in this module

| Cmdlet | Description |
| --- | --- |
| [`Get-BcMarketplaceProduct`](#get-bcmarketplaceproduct) | Retrieves Business Central products from the Microsoft product-ingestion API. |
| [`Get-BcMarketplaceSubmission`](#get-bcmarketplacesubmission) | Retrieves a product's submission(s) from the Partner Center ingestion API. |
| [`Invoke-BcMarketplacePromotion`](#invoke-bcmarketplacepromotion) | Promotes a validated Marketplace submission to live. |
| [`New-BcMarketplaceAuthContext`](#new-bcmarketplaceauthcontext) | Acquires an OAuth2 access token for the Microsoft Marketplace / Partner Center APIs. |
| [`New-BcMarketplaceSubmission`](#new-bcmarketplacesubmission) | Uploads app package(s) and creates a Marketplace (AppSource) submission via Partner Center. |
| [`Submit-BcMarketplaceApp`](#submit-bcmarketplaceapp) | Submits an AL app to Microsoft Marketplace (AppSource) end to end. |
| [`Wait-BcMarketplaceValidation`](#wait-bcmarketplacevalidation) | Waits for a Marketplace submission to finish validation. |

---

## Get-BcMarketplaceProduct

Retrieves Business Central products from the Microsoft product-ingestion API.

Mirrors the proven Publish-AppSourceApp / Get-AppSourceProduct implementation: the product name
lives in the product's 'alias' (NOT 'name'), the product type is 'dynamics365BusinessCentral'
(camelCase - the hyphenated form returns 400), and the working schema version is
'2022-03-01-preview3'. Results are paged via '@nextLink'.

### Syntax

```powershell
Get-BcMarketplaceProduct
    -AuthContext <PSObject>
    [-Name <String>]
    [-ProductType <String>]
    [-ApiVersion <String>]
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | :---: | --- |
| `-AuthContext` | PSObject | Yes | An auth context from New-BcMarketplaceAuthContext (Graph scope: 'https://graph.microsoft.com/.default'). |
| `-Name` | String | No | Optional product-name (alias) filter: exact match first, then wildcard/substring. |
| `-ProductType` | String | No | Product type. Default 'dynamics365BusinessCentral'. **Default:** `'dynamics365BusinessCentral'`. |
| `-ApiVersion` | String | No | Product ingestion API version. Default '2022-03-01-preview3'. **Default:** `'2022-03-01-preview3'`. |

### Output

The product object(s) (each with id, alias, identity.externalId, ...).

---

## Get-BcMarketplaceSubmission

Retrieves a product's submission(s) from the Partner Center ingestion API.

### Syntax

```powershell
Get-BcMarketplaceSubmission
    -AuthContext <PSObject>
    -ProductId <String>
    [-SubmissionId <String>]
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | :---: | --- |
| `-AuthContext` | PSObject | Yes | Auth context (Partner Center scope: 'https://api.partner.microsoft.com/.default'). |
| `-ProductId` | String | Yes | The product id (with or without the 'product/' prefix). |
| `-SubmissionId` | String | No | Optional submission id. If omitted, the latest submission is returned. |

### Output

The submission object (latest, or the requested one).

---

## Invoke-BcMarketplacePromotion

Promotes a validated Marketplace submission to live.

### Syntax

```powershell
Invoke-BcMarketplacePromotion
    -AuthContext <PSObject>
    -ProductId <String>
    -SubmissionId <String>
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | :---: | --- |
| `-AuthContext` | PSObject | Yes | Auth context (Partner Center scope). |
| `-ProductId` | String | Yes | The product id. |
| `-SubmissionId` | String | Yes | The submission id to promote. |

### Output

The updated submission status object.

---

## New-BcMarketplaceAuthContext

Acquires an OAuth2 access token for the Microsoft Marketplace / Partner Center APIs.

Client-credentials OAuth2 against Azure AD, returning an auth context for the other Marketplace
cmdlets. The Partner Center ingestion API and the Graph product-ingestion API use different
scopes - pass the appropriate -Scope. The context carries the numeric PublisherId (Seller ID),
which the Partner Center ingestion API requires as the 'x-ms-publisherId' header, and the client
id/secret so the token can be renewed (Update-BcMarketplaceAuthContext) during long submissions.
Mirrors the proven Publish-AppSourceApp / New-AppSourceAuthContext implementation.

### Syntax

```powershell
New-BcMarketplaceAuthContext
    -TenantId <String>
    -ClientId <String>
    -ClientSecret <Object>
    [-Scope <String>]
    [-PublisherId <String>]
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | :---: | --- |
| `-TenantId` | String | Yes | Azure AD tenant id (or verified domain). |
| `-ClientId` | String | Yes | Azure AD application (client) id. |
| `-ClientSecret` | Object | Yes | Client secret (SecureString or plain string). |
| `-Scope` | String | No | OAuth2 scope. Default 'https://api.partner.microsoft.com/.default'. Use 'https://graph.microsoft.com/.default' for product-ingestion (Get-BcMarketplaceProduct). **Default:** `'https://api.partner.microsoft.com/.default'`. |
| `-PublisherId` | String | No | Numeric publisher/Seller ID (Partner Center > Settings > Account settings > Identifiers). Sent as the required 'x-ms-publisherId' header on Partner Center ingestion calls. |

### Output

PSCustomObject: AccessToken, TokenType, ExpiresOn, ClientId, ClientSecret, TenantId, Scope, Authority, PublisherId.

---

## New-BcMarketplaceSubmission

Uploads app package(s) and creates a Marketplace (AppSource) submission via Partner Center.

Faithful port of the proven Publish-AppSourceApp / New-AppSourceSubmission flow (Partner Center
ingestion API v1.0), so ALbuild submits exactly the way that works:
 1. read the product's Package branch + package configuration;
 2. upload the main app (Dynamics365BusinessCentralAddOnExtensionPackage) and the library apps
 (Dynamics365BusinessCentralAddOnLibraryExtensionPackage - zipped into one archive when there
 is more than one) to Azure Blob Storage via the package SAS URI, marking each Processed
 (with a 409-conflict cleanup+retry), and adding a package reference;
 3. bump the product's appVersion property from the app manifest (rejecting a downgrade);
 4. update the package configuration and create a 'preview' submission;
 5. optionally wait for validation and auto-promote to live.
Requires the Az.Storage module (blob upload) and the auth context's PublisherId (x-ms-publisherId).

### Syntax

```powershell
New-BcMarketplaceSubmission
    -AuthContext <PSObject>
    -ProductId <String>
    -AppFile <String>
    [-LibraryAppFile <String[]>]
    [-AutoPromote]
    [-DoNotWait]
    [-TimeoutMinutes <Int32>]
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | :---: | --- |
| `-AuthContext` | PSObject | Yes | Auth context from New-BcMarketplaceAuthContext (Partner Center scope; carries PublisherId). |
| `-ProductId` | String | Yes | The product id (with or without the 'product/' prefix). |
| `-AppFile` | String | Yes | The main .app file to submit. |
| `-LibraryAppFile` | String[] | No | Optional dependent/library .app files. |
| `-AutoPromote` | switch | No | Promote to live after successful preview validation. |
| `-DoNotWait` | switch | No | Return after creating the submission without waiting for validation. |
| `-TimeoutMinutes` | Int32 | No | Validation wait timeout. Default 30. **Default:** `30`. |

### Output

PSCustomObject: ProductId, SubmissionId, AppFile, Libraries, State, Substate, Promoted.

---

## Submit-BcMarketplaceApp

Submits an AL app to Microsoft Marketplace (AppSource) end to end.

Orchestrates a Marketplace submission: authenticates (Partner Center and product-ingestion
scopes), resolves the product by name, uploads the app (and library apps) and creates a
submission, waits for validation, and optionally promotes it to live. Requires a valid
ALbuild license.

### Syntax

```powershell
Submit-BcMarketplaceApp
    [-ProductName <String>]
    -AppPath <String>
    [-LibraryAppPath <String[]>]
    -AppFile <String>
    [-LibraryAppFile <String[]>]
    -TenantId <String>
    -ClientId <String>
    -ClientSecret <Object>
    -PublisherId <String>
    [-AutoPromote]
    [-TimeoutMinutes <Int32>]
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | :---: | --- |
| `-ProductName` | String | No | The Marketplace product (offer) name. OPTIONAL - defaults to the main app's manifest name. Provide it only to override (e.g. when the offer name differs from the app name). |
| `-AppPath` | String | Yes | A folder of built .app files, or a single .app file. The main app and its library (dependency) apps are selected automatically and TEST apps are excluded - so a task can just point at the build output folder without naming a specific, version-stamped file. |
| `-LibraryAppPath` | String[] | No | Optional additional folder(s) or .app file(s) whose apps are submitted as library apps, for offers whose main app and library app are built by different pipelines/repositories and so arrive as separate release artifacts (e.g. Address Validation + its Extension License library). Test apps are excluded. Only valid with -AppPath. |
| `-AppFile` | String | Yes | (Legacy) An explicit main .app file. Prefer -AppPath. Ignored when -AppPath is given. |
| `-LibraryAppFile` | String[] | No | Optional dependent/library .app files (only used with the legacy -AppFile). |
| `-TenantId` | String | Yes | Azure AD tenant id for the Partner Center service principal. |
| `-ClientId` | String | Yes | Service principal client id. |
| `-ClientSecret` | Object | Yes | Service principal client secret. |
| `-PublisherId` | String | Yes | Numeric publisher/Seller ID (Partner Center > Settings > Account settings > Identifiers). Required by the Partner Center ingestion API (sent as the 'x-ms-publisherId' header). |
| `-AutoPromote` | switch | No | Promote to live after successful validation. |
| `-TimeoutMinutes` | Int32 | No | Validation timeout. Default 30. **Default:** `30`. |

### Output

PSCustomObject with ProductId, SubmissionId, State, Substate, Promoted.

---

## Wait-BcMarketplaceValidation

Waits for a Marketplace submission to finish validation.

Polls the submission until it reaches a publishable state (Published/ReadyToPublish),
fails, or the timeout elapses. The auth token is refreshed when -AuthContextFactory is
supplied (useful for long validations).

### Syntax

```powershell
Wait-BcMarketplaceValidation
    -AuthContext <PSObject>
    -ProductId <String>
    -SubmissionId <String>
    [-TimeoutMinutes <Int32>]
    [-IntervalSeconds <Int32>]
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | :---: | --- |
| `-AuthContext` | PSObject | Yes | Auth context (Partner Center scope). |
| `-ProductId` | String | Yes | The product id. |
| `-SubmissionId` | String | Yes | The submission id to monitor. |
| `-TimeoutMinutes` | Int32 | No | Maximum minutes to wait. Default 40. **Default:** `40`. |
| `-IntervalSeconds` | Int32 | No | Polling interval. Default 30. **Default:** `30`. |

### Output

PSCustomObject with State, Substate, Completed, TimedOut.

---