Skip to content

app-module-management.md

Latest commit

 

History

History
263 lines (195 loc) · 7.12 KB

app-module-management.md

File metadata and controls

263 lines (195 loc) · 7.12 KB
Raw

App Module Management

App modules (model-driven apps) define the structure, navigation, and components of model-driven applications in Dataverse. This guide covers creating, updating, retrieving, and deleting app modules using PowerShell.

Retrieving App Modules

Get a specific app module by ID

$app = Get-DataverseAppModule -Connection $c -Id $appId

Returns parsed properties like Id, UniqueName, Name, Description, PublishedOn, etc.

Get an app module by UniqueName

$app = Get-DataverseAppModule -Connection $c -UniqueName "msdyn_SalesHub"

Get all app modules

$apps = Get-DataverseAppModule -Connection $c

Find app modules by name with wildcards

$salesApps = Get-DataverseAppModule -Connection $c -Name "Sales*"

Get raw attribute values

$app = Get-DataverseAppModule -Connection $c -Id $appId -Raw

Returns all raw attributes from the appmodule record instead of parsed properties.

Get published app modules only

$publishedApps = Get-DataverseAppModule -Connection $c -Published

Creating and Updating App Modules

Create a new app module

$appId = Set-DataverseAppModule -Connection $c -PassThru `
    -UniqueName "my_custom_app" `
    -Name "My Custom Application" `
    -Description "A custom model-driven app"

Update an existing app module by ID

Set-DataverseAppModule -Connection $c `
    -Id $appId `
    -Name "Updated App Name" `
    -Description "Updated description"

Update an app module by UniqueName

Set-DataverseAppModule -Connection $c `
    -UniqueName "my_custom_app" `
    -Description "New description"

Create with icon and form factor

$iconResourceId = (Get-DataverseRecord -Connection $c -TableName webresource -FilterValues @{name="app_icon.svg"}).webresourceid

Set-DataverseAppModule -Connection $c -PassThru `
    -UniqueName "sales_app" `
    -Name "Sales Application" `
    -WebResourceId $iconResourceId `
    -FormFactor 1 `  # Main form factor
    -ClientType 1

### Create with navigation type and featured flag

```powershell
Set-DataverseAppModule -Connection $c -PassThru `
    -UniqueName "featured_app" `
    -Name "Featured App" `
    -NavigationType MultiSession `
    -IsFeatured $true

Validate and publish an app

Set-DataverseAppModule -Connection $c -PassThru `
    -UniqueName "ready_app" `
    -Name "Ready App" `
    -Validate `
    -Publish

Upsert pattern with NoCreate

# Only update if exists, don't create new
Set-DataverseAppModule -Connection $c `
    -UniqueName "existing_app" `
    -Name "Updated Name" `
    -NoCreate

Safe update with NoUpdate

# Only create if doesn't exist, don't update existing
Set-DataverseAppModule -Connection $c `
    -UniqueName "new_app" `
    -Name "New App" `
    -NoUpdate

Publish an app after creation/update

Set-DataverseAppModule -Connection $c -PassThru `
    -UniqueName "my_app" `
    -Name "My App" `
    -Publish

Validate an app before publishing

Set-DataverseAppModule -Connection $c -PassThru `
    -UniqueName "my_app" `
    -Name "My App" `
    -Validate `
    -Publish

Set an app module icon from an icon set

# Set icon for an app module using an icon from an online icon set
Set-DataverseAppmoduleIconFromSet -UniqueName "my_app" `
    -IconName "person" `
    -IconSet FluentUI `
    -PublisherPrefix "contoso" `
    -Publish

Downloads an icon from an online icon set, creates a web resource, and sets it as the app module's icon. See Set-DataverseAppmoduleIconFromSet for more details.

Deleting App Modules

Delete by ID

Remove-DataverseAppModule -Connection $c -Id $appId -Confirm:$false

Delete by UniqueName

Remove-DataverseAppModule -Connection $c -UniqueName "my_app" -Confirm:$false

Safe deletion with IfExists

# Don't error if app doesn't exist
Remove-DataverseAppModule -Connection $c -UniqueName "maybe_exists" -IfExists -Confirm:$false

Preview deletion with WhatIf

Remove-DataverseAppModule -Connection $c -UniqueName "my_app" -WhatIf

Common Scenarios

Clone an app module

# Get existing app
$originalApp = Get-DataverseAppModule -Connection $c -Id $originalAppId

# Create new app with same properties
$newAppId = Set-DataverseAppModule -Connection $c -PassThru `
    -UniqueName "$($originalApp.UniqueName)_copy" `
    -Name "$($originalApp.Name) (Copy)" `
    -Description $originalApp.Description `
    -WebResourceId $originalApp.WebResourceId `
    -FormFactor $originalApp.FormFactor `
    -ClientType $originalApp.ClientType

Bulk create apps for multiple purposes

$appConfigs = @(
    @{ UniqueName = "sales_app"; Name = "Sales Hub"; Description = "Sales management app" },
    @{ UniqueName = "service_app"; Name = "Customer Service"; Description = "Service management app" },
    @{ UniqueName = "marketing_app"; Name = "Marketing Hub"; Description = "Marketing management app" }
)

foreach ($config in $appConfigs) {
    Set-DataverseAppModule -Connection $c -PassThru `
        -UniqueName $config.UniqueName `
        -Name $config.Name `
        -Description $config.Description
}

Audit app module configuration

# Get all apps and export metadata
$apps = Get-DataverseAppModule -Connection $c

$apps | Select-Object UniqueName, Name, Description, PublishedOn, FormFactor, IsFeatured |
    Export-Csv -Path "app-audit.csv" -NoTypeInformation

Clean up development apps

# Remove all apps with names starting with "dev_"
Get-DataverseAppModule -Connection $c -Name "dev_*" |
    ForEach-Object {
        Remove-DataverseAppModule -Connection $c -Id $_.Id -Confirm:$false
    }

App Module Properties

When working with app modules, you'll encounter these key properties:

  • Id: The unique identifier (GUID) of the app module
  • UniqueName: The schema name used to reference the app (required for creation)
  • Name: The display name shown in the app launcher
  • Description: Optional description of the app's purpose
  • WebResourceId: The web resource ID for the app icon
  • FormFactor: The form factor (1=Main, 2=Quick, 3=Preview, 4=Dashboard)
  • ClientType: The client type for the app
  • NavigationType: The navigation type (Single session or Multi session)
  • IsFeatured: Whether the app is featured in the app launcher
  • PublishedOn: When the app was last published

See Also