With the potential of Microsoft Teams having tens of thousands of users, thousands of teams, and thousands of channels, having the ability to automate and bulk manage these teams, channels, and team members is imperative for an administrator. With that said, we need to understand how nicely PowerShell integrates with Microsoft Teams and how you can use PowerShell to interact with Teams and also generate scripts to perform some of the more common, and possibly tedious, tasks associated with Teams.
Microsoft Teams PowerShell provides several cmdlets for managing all aspects of Microsoft Teams, and the Teams PowerShell module offers three great features:
- Support for authentication options like credentials and access tokens
- Ability to manage all aspects of Teams, including teams, users, policies, and configuration
- Automates common repetitive tasks streamlining their completion
Before you can begin using these PowerShell Teams cmdlets you have to install them and there are a few ways to complete this installation:
- Install the Microsoft Teams PowerShell module via PowerShell Gallery (preferred method)
- Install the Microsoft Teams PowerShell module manually by downloading the .nupkg
- Deploy to Azure Automation
We are going to explore the preferred method of installation being that is the most thorough and it requires minimal steps. However, before we can begin the installation, we need to ensure we meet the minimum PowerShell requirement of 5.1. There are a few easy ways to determine which version of PowerShell you are running, this excludes digging into the operating system registry, and you do so by opening a PowerShell window and then entering one of the following commands:
$PSVersionTable.PSVersion (Provides the PowerShell Major, Minor, and build information)
$PSVersionTable (Provides the PowerShell version and other extraneous information)
Get-Host | Select-Object Version (Provides just the PowerShell version)
The following screen shows these results from these commands:
If you discover you aren’t running PowerShell 5.1 you can upgrade to it by downloading the Windows Management Framework 5.1, which includes Windows PowerShell 5.1. This can be downloaded here from the Microsoft Download Center.
After verifying we have the correct version of PowerShell we can continue with our installation of the Teams PowerShell Module by using the following two commands from within a Windows PowerShell Window that was opened with Admin rights:
- Install-Module -Name PowerShellGet -Force -AllowClobber (Ensures the PowerShell Gallery (PSGallery) is configured as a trusted repository)
- Install-Module -Name MicrosoftTeams -Force -AllowClobber (Installs Teams PowerShell Module)
Note: To ensure you have the latest Teams PowerShell module you can use the following cmdlet:
Update-Module -Name MicrosoftTeams
To verify the Teams PowerShell cmdlets were installed properly you can issue the following Microsoft Teams command that is used to connect to Microsoft Teams using PowerShell:
Connect-MicrosoftTeams
Important: If you receive an error indicating the MicrosoftTeams module was found, but the module could not be loaded… it is because of the ExecutionPolicy setting. To resolve this error, enter in the following cmdlet and execute the Connect-MicrosoftTeams cmdlet again:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
After establishing a connection to Microsoft Teams, run the following cmdlet to verify connection:
Get-Team (displays a list of Teams in your M365 tenant)
There is a plethora of Microsoft Teams PowerShell cmdlets, so we are not going to be able to discuss all of them, but we will explore an overview of the most common cmdlets used to manage your teams, channels, and team members. The general cmdlets for managing your teams, channels, and users involves using five primary commands using a verb-noun pattern
- Add-xxx Adds a Teams user to a Teams component
- Get-xxx Retrieve and display information about a Teams component
- New-xxx Create a new Teams components
- Set-xxx Modify or change settings on a Teams component
- Remove-xxx Delete a Teams component
Obtaining help on available Microsoft Teams PowerShell cmdlets
There are just too many Microsoft Teams PowerShell cmdlets for anyone to remember all of them, but you can get help on all the Microsoft Teams PowerShell cmdlets by using the following command
- Get-Command -Module Microsoft.Teams
Use the following command to display a list of Microsoft Teams PowerShell cmdlets that begin with a verb, like New
- Get-Command -Module Microsoft.Teams New-*
Use the following command to display the details of a specific Microsoft Teams PowerShell cmdlet
- Get-Help New-Team -Detail
Use the following command to see examples of a specific Microsoft Teams PowerShell cmdlet
- Get-Help New-Team -Examples
Managing Microsoft Teams components in bulk
If you have the need to create site collections or add Teams users in bulk you can create a .csv file containing the necessary fields, separated by a comma, for the Teams object and use PowerShell to perform a bulk import. For instance, if you wanted to create several Microsoft Teams, you can create a .csv file, we can call NewMSTeams.csv, using a format similar to below;
Line 1: TeamName,TeamDescription,Visibility,Owner
In subsequent lines you provide the values for each teams you want to create;
Line 2+ MTPMarketing,”MTP Marketing Team”,Public,Brian@Microtechpoint.com
To create the new Microsoft Teams, you’ll open Windows PowerShell in Administrator mode, connect to Microsoft Teams using the Connect-MicrosoftTeams cmdlet, and then execute the following command:
Import-Csv C:\users\Brian\Desktop\NewMSTeams.csv | ForEach-Object {New-Team -DisplayName $_.TeamName -TeamDescription $_.TeamDescription -Visibiliity $_.Visibility -Owner $_.Owner}
To add users to the new Microsoft Teams you’ll create another .csv file. This file, we can call TeamMembers.csv, will store each users Email address, and the role they will become a member of within the team, using a format similar to below;
Line 1: EmailAddress,Role
In subsequent lines you provide the values for each user including their email address and the desired role that you want them to be a member of within the team;
Line 2+ Linda@Microtechpoint.com,Owner
In order for us to add the users to the correct team you need to obtain the GroupId of your Teams and use the correct GroupID when adding the users to Teams. To obtain the group ID for your teams you’ll open Windows PowerShell in Administrator mode and connect to Microsoft Teams using the Connect-MicrosoftTeams command. After doing so you can display Microsoft Teams and their GroupIDs using
- Get-Team (Displays all available teams and their GroupID)
- Get-Team -DisplayName “MTP Sports” (Displays the GroupId of the team specified)
Tip: Create a variable to store the GroupID allowing you to use it multiple times while in the current PowerShell window.
$TeamGroupID = (Get-Team -DisplayName “MTP Sports Team”).GroupID
This screen displays the steps we used to connect to Microsoft Teams from a Windows PowerShell opened in Administrator mode. Displaying all teams and the associated information, specifically the GroupID we need to perform the bulk import. We then displayed a specific team’s information called “MTP Sports Teams”, followed by executing the command to store the GroupId in a variable, and showing the value of the variable which contains the GroupID for MTP Sports Teams.
Common Microsoft Team cmdlets
- Get-Team, New-Team, Set-Team, Remove-Team
- Get-TeamUser, Add-TeamUser, Remove-TeamUser
- Get-TeamChannel, New-TeamChannel, Set-TeamChannel, Remove-TeamChannel
- Get-TeamChannelUser, Add-TeamChannelUser, Remove-TeamChannelUser
The following PowerShell screen contains the commands used to create a new team called “MTP Sports Team”, add Brian as a user to the team, create a new channel called “Caddyshack Gophers”, and displays that Brian as the owner of our new Caddyshack Gophers channel.
As I mentioned previously there are too many Teams PowerShell cmdlets to discuss but you can review and learn about all of these cmdlets by accessing this MicrosoftTeamsPowerShell website. Furthermore, Microsoft Teams PowerShell is constantly changing, so you should monitor these changes by following the Microsoft Teams PowerShell Release Notes.