Copy page

PowerShell Module

Feeds module

Module: businessdev.ALbuild.Feeds  •  Tier: Free / Licensed  •  Cmdlets: 14

The Feeds module is home to ALbuild's headline capability: a real transitive dependency resolver across NuGet v3 feeds, Azure DevOps Universal Packages, GitHub Releases and Microsoft's public feeds. It also creates and publishes NuGet packages and promotes them to Azure DevOps feed views. See the Dependency resolver deep dive.

Cmdlets in this module

---

ConvertFrom-BcRemoteUrl

Derives the Azure DevOps organization and project from a git remote URL.

The org/project a project-scoped Universal feed needs used to be parsed with a single regex that only matched the HTTPS remote format (dev.azure.com/{org}/{project}/_git/...). Azure Pipelines checks out exactly that way, so the pipeline worked; an SSH-based checkout (our agents / any SSH clone) uses the SSH v3 form (git@ssh.dev.azure.com/{org}/{project}/{repo}), which the HTTPS regex does NOT match - the project came back empty, the Universal download ran org-scoped, the project-scoped feed was not found, and the failure surfaced much later as AL1024 on publish.

This function recognizes every common Azure DevOps remote format so org/project resolve the same regardless of how the repo was cloned:

• HTTPS https://[user@]dev.azure.com/{org}/{project}/_git/{repo}
• Legacy HTTPS https://{org}.visualstudio.com/{project}/_git/{repo}
• SSH v3 [user@]ssh.dev.azure.com/{org}/{project}/{repo}
• SSH host-alias <alias>/{org}/{project}/{repo} (a ~/.ssh/config Host alias)

Returns empty strings for both when nothing is recognized (e.g. a non-Azure-DevOps remote), so the caller can fall back to org-scoped behaviour without a hard failure.

Syntax

Code
ConvertFrom-BcRemoteUrl
    [-RemoteUrl <String>]

Parameters

Output

PSCustomObject with Organization (a full https://dev.azure.com/&#123;org}/ URL, or '') and Project (the URL-decoded project name, or ''). The project name is URL-encoded in every remote format (e.g. 'Dynamics%20365%20...') and is decoded here.

---

Find-BcPackage

Finds the available versions of an AL app across feeds.

Syntax

Code
Find-BcPackage
    -AppId <String>
    [-Name <String>]
    [-Publisher <String>]
    [-Feeds <Object[]>]

Parameters

Output

PSCustomObject with Feed, PackageId, Version.

Examples

Example 1

Code
Find-BcPackage -AppId '437dbf0e-84ff-417a-965d-ed2bb9650972' -Name 'Base Application' -Publisher 'Microsoft'

---

Get-BcDependencyReconciliation

Reconciles an app's manifest dependencies against what a container already has and what the configured feeds can provide.

Read-only (installs nothing). For each dependency (from app.json 'dependencies'), reports whether it is already satisfied by an app installed in the container, otherwise whether a configured feed can provide a compatible version, otherwise that it is missing. Microsoft first-party apps ship with the artifact, so they normally show up as satisfied by the container.

Feeds are taken from -Feeds, else the currently registered feeds (Get-BcFeed) -- register them first with Register-BcFeed / Register-BcFeed -FromProjectConfig.

Syntax

Code
Get-BcDependencyReconciliation
    -ContainerName <String>
    -Dependencies <Object[]>
    [-Feeds <Object[]>]

Parameters

Output

PSCustomObject: containerName, feedsSearched, summary { total, satisfied, availableFromFeed, missing }, satisfied[], availableFromFeed[], missing[].

---

Get-BcFeed

Returns the registered feed providers.

Syntax

Code
Get-BcFeed
    [-Name <String>]

Parameters

Output

The registered feed provider object(s).

Examples

Example 1

Code
Get-BcFeed

---

Get-BcPackageVersion

The published versions of one or more package ids on a feed.

A plain listing, for the times when the question is "what is already on the feed" rather than "resolve a dependency". The runtime factory asks it to decide what it still has to build: idempotency keyed on blob storage alone lets blob and feed drift apart, because the checkpoint uploads to blob first and pushes to the feed second, and a failed push is warned about rather than fatal.

THE EMPTY-RESULT TRAP The provider's version lookup swallows every error and returns nothing, so "this package has no versions" and "the feed could not be asked" look identical from the outside. Reading the second as the first would tell the factory that nothing is published and send it off to rebuild the whole matrix - hundreds of containers.

So the feed is proven reachable and authorised FIRST, on its own, and a failure there throws. After that an empty version list genuinely means the package is absent, and callers can trust it. A caller that would rather degrade than rebuild should catch the exception and fall back.

Syntax

Code
Get-BcPackageVersion
    -Feed <Object>
    -PackageId <String[]>

Parameters

Output

PSCustomObject[] with PackageId and Versions (string[], empty when the package is absent).

Examples

Example 1

Code
$feed = Register-BcFeed -Name rt -Kind runtime -Url $url -Token $token
Get-BcPackageVersion -Feed $feed -PackageId '365businessdevelopment.365businessbanking.runtime-18-3-513-27128'

Example 2

Code
# What is already on the feed, as the factory asks it.
Get-BcPackageVersion -Feed $feed -PackageId $ids | ForEach-Object {
    foreach ($v in $_.Versions) { "$appId/$v" }
}

---

Get-BcUniversalPackage

Downloads a named package from an Azure DevOps Universal feed into a folder.

Azure DevOps Universal feeds address packages by name and version (unlike NuGet symbol feeds, which the dependency resolver queries by app id). This cmdlet downloads such a named package - e.g. shared symbol bundles or a configuration package - into -OutputFolder. It is the native replacement for the V1 DownloadArtifactsUniversalFeed / DownloadDependenciesUniversalFeed / DownloadConfigPackageUniversalFeed tasks.

Download uses the Azure CLI 'az artifacts universal download' (the supported Universal Packages client). The Azure CLI with the azure-devops extension must be available; the call is routed through Invoke-ALbuildProcess so it is captured and testable. Authenticate either by a prior 'az login' or by passing -AccessToken (a PAT), which is exported as AZURE_DEVOPS_EXT_PAT for the download only.

Syntax

Code
Get-BcUniversalPackage
    -Organization <String>
    -Feed <String>
    -Name <String>
    [-Version <String>]
    -OutputFolder <String>
    [-Project <String>]
    [-AccessToken <String>]
    [-AzExecutable <String>]

Parameters

Output

PSCustomObject: Name, Version, OutputFolder, Files.

Examples

Example 1

Code
Get-BcUniversalPackage -Organization 'https://dev.azure.com/contoso' -Feed 'D365BC' `
    -Name 'shared-symbols' -Version '*' -OutputFolder '.\.alpackages'

---

Invoke-BcPackagePromotion

Promotes a published NuGet package version to a view on an Azure DevOps Artifacts feed.

Azure DevOps Artifacts feeds expose 'views' (e.g. @Prerelease, @Release). Promoting a package version to a view lets partners consume it from a view-scoped feed URL (.../_packaging/<feed>@Prerelease/nuget/v3/index.json), which is how ALbuild distributes prerelease (dev) and release (master) app packages from one feed.

The view assignment is a one-shot PATCH against the Azure DevOps Packaging REST API (it is not part of the NuGet protocol). The feed's v3 index URL is parsed to derive the organisation, optional project and feed name. Promotion is OPT-IN: when -View is not supplied the cmdlet is a no-op and returns $true, so callers can pass the parameter through unconditionally.

Syntax

Code
Invoke-BcPackagePromotion
    -Url <String>
    [-View <String>]
    -ApiKey <String>
    [-PackagePath <String>]
    -PackageId <String>
    -Version <String>

Parameters

Output

System.Boolean ($true on success or when there is nothing to promote).

Examples

Example 1

Code
Invoke-BcPackagePromotion -Url $feedUrl -PackagePath .\pkg.1.0.0.nupkg -View Prerelease -ApiKey $env:FEED_PAT

---

New-BcNuGetPackage

Creates a NuGet package (.nupkg) that contains a Business Central .app.

Reads the .app manifest, derives the package id from the id scheme (or uses -PackageId), and produces a valid OPC NuGet package (with [Content_Types].xml and relationships) containing the .app and a generated .nuspec. Application/platform dependency ranges and extra dependencies can be declared (used by, for example, runtime packages).

Syntax

Code
New-BcNuGetPackage
    -AppFile <String>
    [-PackageId <String>]
    [-IdScheme <String>]
    [-Version <String>]
    [-Authors <String>]
    [-Description <String>]
    [-Dependency <Object[]>]
    [-OutputFolder <String>]

Parameters

Output

System.String - the path to the created .nupkg.

Examples

Example 1

Code
New-BcNuGetPackage -AppFile .\Publisher_App_1.0.0.0.app -IdScheme '{publisher}.{name}.symbols.{id}'

---

Publish-BcPackage

Pushes a NuGet package (.nupkg) to a NuGet v3 feed.

Resolves the feed's PackagePublish service from its service index and uploads the package using a multipart PUT (the NuGet v3 push protocol). An existing package version is reported as a conflict rather than failing the build (unless -FailOnConflict is set).

Syntax

Code
Publish-BcPackage
    -PackagePath <String>
    -Url <String>
    -ApiKey <String>
    [-FailOnConflict]
    [-View <String>]

Parameters

Output

System.Boolean ($true on success or conflict-when-not-failing).

Examples

Example 1

Code
Publish-BcPackage -PackagePath .\pkg.1.0.0.nupkg -Url $feedUrl -ApiKey $env:NUGET_KEY

Example 2

Code
Publish-BcPackage -PackagePath .\pkg.1.0.0.nupkg -Url $feedUrl -ApiKey $env:FEED_PAT -View Prerelease

---

Register-BcFeed

Registers a NuGet package feed for dependency resolution.

Creates a NuGet v3 feed provider and stores it in the session's feed registry. Registered feeds are used by Resolve-BcDependencies (unless feeds are passed explicitly). Use -IncludeMicrosoftDefaults to also register Microsoft's public BC feeds (MSSymbols, AppSourceSymbols, MSApps).

Syntax

Code
Register-BcFeed
    -Name <String>
    -Url <String>
    [-Token <String>]
    [-IdScheme <String>]
    [-Kind <String>]
    [-CacheFolder <String>]
    -IncludeMicrosoftDefaults
    -FromProjectConfig <String>
    [-WorkspaceRoot <String>]

Parameters

Output

The registered provider object(s).

Examples

Example 1

Code
Register-BcFeed -Name 'MyFeed' -Url 'https://pkgs.dev.azure.com/org/_packaging/Apps/nuget/v3/index.json' -Token $pat -Kind apps

Example 2

Code
Register-BcFeed -FromProjectConfig ./MyApp -WorkspaceRoot .

---

Resolve-BcDependencies

Resolves an AL project's dependencies across feeds and writes them to .alpackages.

Reads the project's app.json, resolves a mutually-compatible, transitively-complete set of dependency packages from the given (or registered) feeds - respecting the target build's platform/application versions and any apps already installed in the build (pinned, e.g. Microsoft first-party apps) - then downloads them in dependency order and writes a dependencies.lock.json for reproducible builds.

Syntax

Code
Resolve-BcDependencies
    -ProjectFolder <String>
    [-Feeds <Object[]>]
    [-WorkspaceRoot <String>]
    [-InstalledApps <Object[]>]
    [-TargetApplication <String>]
    [-TargetPlatform <String>]
    [-Select <String>]
    [-OutputFolder <String>]
    [-LockFilePath <String>]
    [-SkipDownload]

Parameters

Output

PSCustomObject with Resolved, OutputFolder, LockFile, Packages.

Examples

Example 1

Code
Resolve-BcDependencies -ProjectFolder ./app -InstalledApps (Get-BcContainerAppInfo -Name bld)

---

Resolve-BcDependencyCeiling

Picks the BC version that dependency resolution should cap against, from the available sources.

Pure helper (no I/O, unit-testable) for the Resolve Dependencies task. The dependency version ceiling is the BC version being built against - NOT app.json 'application'/'platform', which are the app's minimum supported versions (using those as the ceiling makes the resolver reject real dependency apps built for the current BC and fall back to symbol-only AppSource packages).

Precedence, highest first:

1. TargetVersionInput - an explicit pipeline value. Defaults (in the task) to $(bcArtifactVersion) from Get BC Artifact, so a CONTAINER-LESS build still honours the BC version it targets; can also be an author override. An unexpanded '$(...)' macro or an empty value is ignored (a container-less run leaves the default macro unexpanded).
2. InstalledApp - the platform app installed in the build container (exact build BC version); preserves the original container-based behaviour.
3. ConfigBcVersion - the 'bcVersion' pinned in albuild.json. Returns an empty Version (Source 'none') when nothing is available, so the caller resolves the newest version each app.json is compatible with.

Syntax

Code
Resolve-BcDependencyCeiling
    [-TargetVersionInput <String>]
    [-InstalledApp <Object[]>]
    [-ConfigBcVersion <String>]

Parameters

Output

PSCustomObject: Version (string, '' when none) and Source (string).

---

Resolve-BcExternalDependency

Syntax

Code
Resolve-BcExternalDependency
    [-UniversalPackages <Object[]>]
    [-LocalPackage <String[]>]
    [-UrlPackage <Object[]>]
    -OutputFolder <String>
    [-Organization <String>]
    [-Project <String>]
    [-AccessToken <String>]
    [-RequireUniversalPackages]
    [-BaseFolder <String>]
    [-ContainerName <String>]
    [-DockerExecutable <String>]

Parameters

---

Select-BcArtifactForDependencies

Picks the newest Business Central artifact whose build every project's dependencies still resolve against - stepping back through minor versions when an ISV has not yet shipped packages for the latest BC (dependency-aware selection with downgrade-on-conflict).

For 'Select = Latest' pipelines only. Enumerates the latest artifact and up to -MaxStepsBack earlier minor versions (crossing a major boundary to the previous major's latest minor when a minor reaches x.0), and - newest first - dry-runs Resolve-BcDependencies (-SkipDownload) for every project against that build. The first version where all projects resolve is chosen. If it is older than the latest, 'Downgraded' is set and 'ConflictReason' explains why the latest was skipped (the caller emits the pipeline warning). Throws if nothing within the window resolves. Because it uses an explicit target build and a synthetic Microsoft baseline, no container is needed - the choice is made before the (single) container is created.

A specific -Version pins the choice: enumeration/downgrade only runs when no explicit version is given.

Syntax

Code
Select-BcArtifactForDependencies
    -ProjectFolder <String[]>
    [-Type <String>]
    [-Country <String>]
    [-Version <String>]
    [-MaxStepsBack <Int32>]
    [-Feeds <Object[]>]
    [-InstalledApps <Object[]>]

Parameters

Output

PSCustomObject: ArtifactUrl, Version, LatestVersion, Downgraded, StepsBack, ConflictReason.

---