Teams PowerShell Module Generally Available (At Last)

Slow Progress to 1.0

The Teams PowerShell module first appeared in March 2017. At the time, I wasn’t too impressed because the module was kind of odd in its approach and didn’t do a great job of managing teams. Over time, Microsoft updated the module (far too slowly for some) to a point where the preview versions 0.9.5 and 0.9.6 offered reasonable functionality.

For much of the time, progress with the module was gated by work Microsoft did on the Teams Admin Center. Invariably, soon after Microsoft upgraded the portal (for example, to manage teams in September 2018), a new version of the PowerShell module appeared. Now Microsoft has released the 1.0 version of the module, or the first “generally available” version. The new module includes some cmdlet changes that might force updates for scripts.

Installing Teams PowerShell 1.0

To get the new module, first make sure that you uninstall any of the older versions from your workstation:

Uninstall-Module MicrosoftTeams

Then, install the V1.0 release from the PowerShell Gallery:

Install-Module MicrosoftTeams -Repository PSGallery

Finally, connect to Teams with an administrator account (if you want to work with all the teams in the tenant) or a user account (to work with teams owned by that account).

Connect-MicrosoftTeams

At this point, if you check the module, you should see it report the correct version:

Get-Module |?{$_.Name -eq "MicrosoftTeams"}|Select Name, Version

Name           Version
----           -------
MicrosoftTeams 1.0.0

Get-Team and Filtering

The big changes in the V1.0 module are in the Get-Team cmdlet. First, Get-Team supports basic filtering capabilities. Get-Team can return a set of teams:

Owned by someone: specify the User parameter and pass the user’s email address:

Get-Team -User [email protected]

Archived (read-only): specify the Archived parameter and set it to $True to return a set of archived teams or $False to see a set of teams that are not archived.

Get-Team -Archived $True

Access (public or private): specify the Visibility parameter and set it to Public or Private to retrieve the teams you want:

Get-Team -Visibility Public

You can combine the parameters too:

Get-Team -Visibility Private -Archived $True -User [email protected]

While you retrieve sets of teams with Get-Team, two issues become painfully apparent. First, the cmdlet is slow. Second, the filters are client-side rather than server-side and don’t support the kind of filtering functionality that you might be accustomed to with cmdlets like Get-Mailbox. For instance, wildcard matching is unsupported.

This won’t be a big deal when you only work with a few teams, but it becomes a much bigger problem as the number of teams mounts into the hundreds or thousands.

Microsoft acknowledges that performance isn’t what it should be, and we can hope for improvements in the future. Unfortunately, the Get-UnifiedGroup cmdlet (often used to retrieve information not returned by Get-Team) is a sloth of a cmdlet too. The net is that we have plenty of time to drink coffee.

Simplification and Consolidation in Team Settings

The original version of Get-Team returned just a few properties for a team. With this release, Microsoft has deprecated several subsidiary cmdlets into Get-Team so that the one cmdlet can return all the settings related to a team. For example, you don’t have to run Get-TeamGuestSettings to find out what guest users can do in a team or Get-TeamFunSettings (an excellent name) to return the settings controlling the use of GIFS and stickers in chats. This change and the associated change to Set-Team to set values for team settings might mean that you need to update scripts.

Here’s what the full set of properties returned for a team looks like:

Get-Team -GroupId de797c44-d998-4682-b1e0-aa938cfc05a8 |Format-List

GroupId                           : de797c44-d998-4682-b1e0-aa938cfc05a8
DisplayName                       : Forza Roma
Description                       : Rome at its best
Visibility                        : Public
MailNickName                      : ForzaRoma
Classification                    :
Archived                          : False
AllowGiphy                        : True
GiphyContentRating                : moderate
AllowStickersAndMemes             : True
AllowCustomMemes                  : True
AllowGuestCreateUpdateChannels    : False
AllowGuestDeleteChannels          : False
AllowCreateUpdateChannels         : True
AllowDeleteChannels               : True
AllowAddRemoveApps                : True
AllowCreateUpdateRemoveTabs       : True
AllowCreateUpdateRemoveConnectors : True
AllowUserEditMessages             : True
AllowUserDeleteMessages           : True
AllowOwnerDeleteMessages          : True
AllowTeamMentions                 : True
AllowChannelMentions              : True

As mentioned above, the Set-Team cmdlet now can control all the settings previously set in cmdlets like Set-TeamGuestSettings. For example:

Set-Team -GroupId de797c44-d998-4682-b1e0-aa938cfc05a8 -AllowGuestCreateUpdateChannels $True

Other Cmdlets

The 1.0 module does not change how the cmdlets to work with users (Add-TeamUser), channels (New-TeamChannel) or managing teams (New-Team, Remove-Team) work. All existing scripts should work just fine with the new module, part from one known bug where a classification cannot be set with the New-Team or Set-Team cmdlets (Microsoft expects to fix this problem soon).

The Connect-MicrosoftTeams cmdlet now supports the ability to specify the kind of Teams environment a tenant is located in. If you don’t use one of the sovereign clouds, you can forget about this and use Connect-MicrosoftTeams without passing the TeamsEnvironmentName parameter.

Future Developments

Critical parts of the V1.0 of the Teams PowerShell module are too slow for my liking, but apart from that, the module is solid. From this point on, Microsoft plans to keep two versions of the Teams PowerShell module available. The Generally Available version is intended for production use while the Preview version is for early access to updated or new cmdlets. The division between the two versions reflects the fact that Microsoft has GA and beta versions of the Graph endpoints for Teams.

The next thing Microsoft needs to do is to combine the old Skype for Business Online module (used for managing policies and other org-wide settings) with this module. A single consolidated module with some extra speed would be a nice announcement at Ignite 2019.