Getting Started

Getting Started with MvRAdaptiveCards

This guide will help you get started with the MvRAdaptiveCards PowerShell module.

Installation

Install the module from the PowerShell Gallery:

Install-Module -Name MvRAdaptiveCards -Scope CurrentUser

To update to the latest version:

Update-Module -Name MvRAdaptiveCards

We encourage you to update regularly to benefit from new features and bug fixes.

Importing the Module

Import the module into your PowerShell session is not required if you have PowerShell 5.1 or later, as modules are auto-imported when a command is invoked. However, you can manually import it using:

Import-Module MvRAdaptiveCards

When importing the module you have the benefit of seeing the banner.

 ┌────╗
 │ >_ │ MvRAdaptiveCards version 0.9.5
 ╚────┘ - PowerShell Module for creating Adaptive Cards

Your First Card

Let's create a simple "Hello World" card:

New-AdaptiveCard {
    New-CardTextBlock -Text "Hello World!" -Size Large -Weight Bolder
    New-CardTextBlock -Text "This is my first Adaptive Card created with PowerShell" -Wrap
} | Get-CardResponse -ViewMethod EdgeApp

What's Happening Here?

1. New-AdaptiveCard - Creates the card container
2. Scriptblock { } - Contains the card elements
3. New-CardTextBlock - Adds text elements to the card
4. | Get-CardResponse - Displays the card and waits for user interaction
5. -ViewMethod EdgeApp - Opens the card in a popup window using Edge App mode

Setup the modules defaults for easier use

You can set default values for your Adaptive Cards by using the Start-CardSetupGuide cmdlet. This opens an interactive guide to configure your preferred defaults. For example the connection with Microsoft Teams.

Start-CardSetupGuide

Follow the steps in the guide to set up your environments defaults for easier use of the module.

note: You can always re-run the setup guide to update your settings. note: Settings are defaults that can be overridden per card as needed.

Display Methods

The module supports multiple ways to display cards:

• Out-CardPreview - Opens a preview window to view the card without interaction
• Get-CardResponse supports several -ViewMethod options:
  • EdgeApp - Opens the card in a popup window using Edge App mode
  • Browser - Outputs the card to the default web browser
• Out-OnlineDesigner - Opens the card in the Adaptive Cards online designer for editing

You can also not use any display method and just generate the JSON payload for further use:

New-AdaptiveCard {
    New-CardTextBlock -Text "Hello World!" -Size Large -Weight Bolder
    New-CardTextBlock -Text "This is my first Adaptive Card created with PowerShell" -Wrap
} 

This will output the Adaptive Card JSON to the console, which you can then use in other applications or services that support Adaptive Cards.

For ease of use, there is also Get-ACR - a shorthand command that defaults to EdgeApp view method with autosize and hidden header.

Understanding the Syntax

MvRAdaptiveCards uses a declarative, scriptblock-based approach:

New-AdaptiveCard {
    # Elements are added in order
    New-CardTextBlock -Text "Title" -Size Large
    
    # Containers can hold other elements
    New-CardContainer -Items {
        New-CardTextBlock -Text "Inside a container"
        New-CardImage -Url "image.png"
    }
    
    # Actions provide interactivity
    New-CardActionSet -Actions {
        New-CardActionSubmit -Title "Submit"
    }
}

Adding Interactive Elements

Input Fields

Adding input fields allows users to provide data that can be captured when the card is submitted. Here's an example of a card with text input fields:

New-AdaptiveCard {
    New-CardTextBlock -Text "User Information" -Size Large
    
    New-CardInputText -Id "name" -Label "Name" -Placeholder "Enter your name"
    New-CardInputText -Id "email" -Label "Email" -Style Email
    
    New-CardActionSet -Actions {
        New-CardActionSubmit -Title "Submit" -Style Positive
    }
} | Get-CardResponse -ViewMethod EdgeApp

Buttons and Actions and the Data parameter

MvRAdaptiveCards supports various actions like Submit and OpenUrl. You can also pass custom data with actions using the -Data parameter:

New-AdaptiveCard {
    New-CardTextBlock -Text "Choose an action"
    
    New-CardActionSet -Actions {
        New-CardActionSubmit -Title "Save" -Style Positive -Data @{ action = "save" }
        New-CardActionSubmit -Title "Cancel" -Style Default -Data @{ action = "cancel" }
        New-CardActionOpenUrl -Title "Learn More" -Url "https://adaptivecards.io"
    }
} | Get-CardResponse -ViewMethod EdgeApp

Handling Responses

Capture user input from the card:

$response = New-AdaptiveCard {
    New-CardInputText -Id "username" -Label "Username"
    New-CardInputText -Id "password" -Label "Password" -Style Password
    
    New-CardActionSet -Actions {
        New-CardActionSubmit -Title "Login"
    }
} | Get-CardResponse -ViewMethod EdgeApp

# Access the submitted values
if ($response) {
    Write-Host "Username: $($response.username)"
    Write-Host "Password entered: $($response.password -ne $null)"
}

Note: Password values are not returned in plain text for security reasons. This example is for demonstration only.

Next Steps

• Explore Core Concepts to understand the card structure
• Check out the Examples Gallery for real-world scenarios

Module Not Found

Check if the module is installed:

Get-Module -ListAvailable -Name MvRAdaptiveCards

If not found, reinstall:

Install-Module -Name MvRAdaptiveCards -Force

---

← Back to Home | Next: Core Concepts →