Current Version of the Microsoft Teams PowerShell Module is 4.9.1
Updated November 15, 2022
On March 31, 2022, Microsoft announced that they will cease support for versions older than 4.0 in mid-June (MC350371), so you should now be using version 4.0 or later. See this page for information about the supported versions.
Updating the Module
Updating the Microsoft Teams module is easy. In an administrator PowerShell session, run the command:
Update-Module MicrosoftTeams -RequiredVersion 4.9.1 -Force
A lot of the development work now being done in the Teams PowerShell module is the modernization of the cmdlets inherited from the Skype for Business Online connector. These cmdlets (like Get-CsTeamsMeetingPolicy) are used for policy management and, unlike the Teams management cmdlets, are not based on the Microsoft Graph. The work includes the removal of basic authentication (now done for more than 50% of the cmdlets), including removal of dependencies on components like WinRM. Note that the use of basic authentication does not mean that user credentials are transmitted in clear text (OAuth tokens are sent, but not user credentials).
An unusual interim update released on November 15, 2022, V4.9.1 of the Microsoft Teams PowerShell module contains the generally available implementation of application-based authentication support for the Connect-MicrosoftTeams cmdlet. Several other changes are in the module, including:
- A new implementation of the *-CsTeamsChannelPolicy and *-CsTeamsUpdateManagementPolicy cmdlet sets. The Set- and New-CsTeamsUpdateManagementPolicy cmdlets also gain the UseNewTeamsClient parameter to prepare the way for the preview of the new Teams (V2) enterprise client. The Set- and New-CsTeamsChannelPolicy cmdlets have a new EnablePrivateTeamDiscovery parameter to allow clients to find teams marked as private.
- Fixes problems with authentication token refresh in some cmdlets.
- Adds several properties to Get-CsOnlineUser when run without an identity (for example, CountryAbbreviation).
- Fixes problems with how some cmdlets display properties.
- Fixes the Add-TeamChannelUser and Remove-TeamChannelUser cmdlets so that you can add or remove a user to a shared channel with a UPN rather than an object identifier.
Released on November 1, 2022, V4.9 of the Microsoft Teams PowerShell module continues the work to modernize the cmdlets from the old Skype from Business Online connector. This work is important because some of the older cmdlets can’t run in environments like Azure Automation. The upgraded policy management cmdlets still aren’t perfect in terms of their support for Azure Automation, but they do work (as illustrated by this example).
The notable changes in V4.9 include:
- Modernized versions of the *-CsTeamsFeedbackPolicy, *-CsTeamsMessagingPolicy, *-CsTeamsMeetingPolicy, and *-CsOnlineVoiceMailPolicy cmdlet sets.
- The Get/Set-CsTeamsEducationConfiguration cmdlets are now GA. This only affects Teams for Education deployments.
- Adds the ExplicitRecordingConsent and ForceStreamingAttendeeMode parameters to the Teams meeting policy cmdlets.
- Adds the Description, PreambleAudioFile, and PostambleAudioFile to the Online voicemail policy.
- Adds the AllowChatWithGroup parameter to the Teams messaging policy.
- Adds the EnableFeedbackSuggestions parameter to the Teams feedback policy.
- Releases the Update-CsTeamsShiftsConnectionInstance cmdlet.
For the record, the Add-TeamChannelUser issue remains unresolved in V4.9. Documentation has not been updated at the time of writing.
Released on October 11, 2022, V4.8 of the Microsoft Teams PowerShell module is another incremental fit and finish update. Microsoft documents the following in its release notes:
- [Get|New]-CsTeamsShiftsConnectionTeamMap cmdlets – TimeZone attribute added.
- Removes SendEmailFromAddress and SendEmailFromDisplayName input parameters from Set-CsOnlineDialinConferencingUser.Removes AllowAllAcsResources and BlockedAcsResources parameters from Set-TeamsAcsFederationConfiguration.
- Adds ForceListenMenuEnabled parameter to callflow settings in New-CsAutoAttendantCallFlow, New-CsAutoAttendant and Set-CsAutoAutoAttendant. This setting enables the tenant to ignore DTMF/speech inputs while greetings/menu options are played.
I thought that Microsoft was going to fix the bug in the Add-TeamChannelUser cmdlet that prevents a user from another tenant being added to a shared channel when specifying their user principal name – but they haven’t!
Microsoft released V4.7 of the MicrosoftTeams PowerShell module on September 1, 2022. Unlike V4.6, this is very much a fit-and-finish release and most tenant administrator will not notice the changes because of the lack of impact on mainline cmdlets. Here’s the set of changes as documented in the release notes.
- Fixes issues with process clean-up when using module on PS ISE and dotnet applications.
- General availability of the [Get|New]-CsBatchTeamsDeployment cmdlets.
- Releases [New|Set]-CSTeamsShiftsConnectionInstance, Test-CsTeamsShiftsConnectionValidate support for UKG Dimensions.
- Fixes issues with incorrect token fetch while choosing between multiple accounts using AccountId parameter in Connect-MicrosoftTeams.
- Default values of Conference mode & Presence mode attributes are changed from false to true for New-CsCallQueue cmdlet.
Microsoft released V4.6 of the MicrosoftTeams PowerShell module on July 29, 2022. Continuing the recent trend, the new version contains a lot of modernization activity as Microsoft seeks to upgrade cmdlets (mainly from the old Skype for Business connector) to match updated standards. Among the changes are:
The Get-CsOnlineUser cmdlet now has an AccountType parameter. For example, to find user accounts:
Get-CsOnlineUser -AccountType User | Format-Table DisplayName
This command returns accounts for user and shared mailboxes. The cmdlet supports “Guest” as a parameter value, but it doesn’t return any guest accounts in my tenant. Some other bits might be needed.
The *-CsTeamsEventsPolicy cmdlet set is added. This appears to be a policy to control webinars, perhaps to move settings for these (and other events) out of the meeting policy.
Get-CsTeamsEventsPolicy AllowWebinars : Enabled EventAccessType : Everyone Description : Default policy DataSource : Key : ScopeClass=Global;SchemaId=;AuthorityId=;DefaultXml=;XmlRoot= Identity : Global
Some extra cmdlets to support shared channels are added. For example, the Add-TeamChannelUser cmdlet now takes an optional tenant identifier to allow the addition of a user from an external tenant to a shared channel:
Add-TeamChannelUser -GroupId b647d5ff-3bda-4333-b768-7990084569b6 -DisplayName "📔Teams Practices and Architecture" -User "James.Hoover@O365maestro.onmicrosoft.com" -TenantId 22e90715-3da6-4a78-9ec6-b3282389492b
The Get-SharedWithTeam cmdlet checks if a shared channel is shared with a team:
Get-SharedWithTeam -HostTeamId b647d5ff-3bda-4333-b768-7990084569b6 -ChannelId "19:5-aYUE7mEEoAmK8gzNZDfT6aTmsyh5DXKAWLNP45aks1@thread.tacv2" | fl GroupId : b647d5ff-3bda-4333-b768-7990084569b6 DisplayName : Office 365 Adoption TenantId : a662313f-14fc-43a2-9a7a-d2e27f4f3478 IsHostTeam : True
The Get-TeamAllChannel cmdlet returns all channels and their properties found in a team. This cmdlet makes it easier to report channels.
Get-TeamAllChannel -GroupId b647d5ff-3bda-4333-b768-7990084569b6 Id : 19:email@example.com DisplayName : Microsoft 365 Roadmap items Description : MembershipType : Standard HostTeamId : a647d5ff-3bda-4333-b768-7990084569b6 TenantId : a662313f-14fc-43a2-9a7a-d2e27f4f3478 Id : 19:firstname.lastname@example.org DisplayName : Blog Posts Description : Blogs from many places MembershipType : Standard HostTeamId : b647d5ff-3bda-4333-b768-7990084569b6 TenantId : a662313f-14fc-43a2-9a7a-d2e27f4f3478 Id : 19:email@example.com DisplayName : Project Hydra Description : Discussions about the Hydra Project MembershipType : Private HostTeamId : a647d5ff-3bda-4333-b768-7990084569b6 TenantId : a662313f-14fc-43a2-9a7a-d2e27f4f3478 Id : 19:5-aYUE7mEEoAmK8gzNZDfT6aTmsyh5DXKAWLNP45aks1@thread.tacv2 DisplayName : 📔Teams Practices and Architecture Description : Discussions about the most productive practices and architectural decisions in Microsoft Teams deployments MembershipType : Shared HostTeamId : b647d5ff-3bda-4333-b768-7990084569b6 TenantId : a662313f-14fc-43a2-9a7a-d2e27f4f3478
The Get-TeamIncomingChannel cmdlet reports if a team has access to shared channels hosted in other tenants:
Get-TeamIncomingChannel -GroupId 5b617155-a124-4e32-a230-022dfe0b80ac Id : 19:qxTeKg0KEuJTNd9S-d75-dq4gJz30bdhSg4HOKBRj3Y1@thread.tacv2 DisplayName : 📔Teams and Groups Discussion Description : MembershipType : Shared HostTeamId : 2713f078-45a7-4b86-a548-d97870ad2b70 TenantId : 22e90715-3da6-4a78-9ec6-b3282389492b
The Get-AssociatedTeam cmdlet reports the set of teams a user has access to, including teams hosting shared channels in another tenant (like the last team in the example listing):
Get-AssociatedTeam -User Ken.Bowers@office365itpros.com GroupId DisplayName TenantId ------- ----------- -------- 82ae842d-61a6-4776-b60d-e131e2d5749c Rugby Lovers a662313f-14fc-43a2-9a7a-d2e27f4f3478 bda4f6ed-f102-4a23-a2f7-ef363f45ded6 Sales Team a662313f-14fc-43a2-9a7a-d2e27f4f3478 fee4a526-fd91-46e9-a45b-cdb92f929602 Corona Virus News a662313f-14fc-43a2-9a7a-d2e27f4f3478 9367a82e-9c65-4258-86fb-c2eb304c79ef Privacy Advocates a662313f-14fc-43a2-9a7a-d2e27f4f3478 50a43aed-4a24-4925-a2f4-6545e63a066d James Hoover Team 22e90715-3da6-4a78-9ec6-b3282389492b
The Get-TeamTargetingHierarchyStatus cmdlet is also released, but I don’t see how this is used.
On July 1, 2022, Microsoft published V4.5.0. This release doesn’t contain anything earthshattering and is largely devoted to a set of fixes and enhancements (see the release notes). The Get-CsOnlineUser cmdlet now supports a SoftDeletedUsers parameter to list soft-deleted Azure AD accounts enabled for Teams:
Get-CsOnlineUser -SoftDeletedUsers | ft Displayname, SoftDeletionTimestamp DisplayName SoftDeletionTimestamp ----------- --------------------- Maurice Keane 01/07/2022 10:17:13
The Teams module doesn’t contain a cmdlet to restore a soft-deleted account. To do that, you’ll need to use a cmdlet like Restore-MgDirectoryDeletedItem as described in this article.
On June 1, 2022, Microsoft published V4.4.1. This follows the release of 4.3 in May (not much happened in that version). Work continues to modernize the old Skype for Business policy management cmdlets and to fix bugs. The most important changes in this release are:
- The Get-CsOnlineUser cmdlet now returns null values if a user doesn’t have an explicit policy assigned (in other words, they use the default tenant policy).
- The Get-CsPhoneNumberAssignment cmdlet returns new City and IsoSubDivision attributes.
In reality, not much to report…
On April 13, 2022, Microsoft published V4.2 of the Microsoft Teams PowerShell module in the PowerShell Gallery. The release notes for the module are sadly deficient in terms of the clarity and completeness of the information they offer about the changes. I’ve noted these concerns to the Teams developers because it doesn’t take much effort for a program manager to write up some concise and coherent notes instead of grabbing a bunch of developer comments about changes. Here’s my interpretation of the changes:
Proxy support for all the cmdlets relevant for Teams. The supported cmdlets are being gradually rolled out.
In other words, Microsoft has deprecated some old cmdlets only used for managing Skype for Business Online. These cmdlets will be removed from the MicrosoftTeams module over the next few months.
Fixes issues with [New|Set]- modernized Policy cmdlets when used with PSListModifier type parameters.
This is an internal fix which shouldn’t affect scripts.
[BREAKING CHANGE] PSListModifier type parameters will only accept Hashtable with Add or Remove. Hashtable with Replace is not supported now, instead value(s) can be set directly in the parameter.
PSListModifier is a helper class used by many cmdlets to manipulate lists (for instance, the set of email addresses assigned to a mail-enabled recipient). Instead of passing simple values in parameters to update lists, you need to use hash tables.
Fixes format issues with [Get|New]- of few modernized Policy cmdlets (CsVideoInteropServiceProvider, CsInboundBlockedNumberPattern, CsTeamsComplianceRecordingApplication, CsTeamsTranslationRule, CsTeamsUnassignedNumberTreatment, CsVoiceNormalizationRule).
Improved performance of pipeline input processing with the modernized cmdlets.
A modernized cmdlet is one that is REST-based (AutoRest-generated) instead of communicating with the server using the older PowerShell remoting method. Some of the cmdlets needed a little help to improve their performance.
Fixes minor issues with pipeline input results.
Apparently, the fix makes sure that Catch handles errors correctly.
Get-CsOnlineUser: Country attribute (known as CountryOrRegionDisplayName in versions earlier than 3.x.x), is added.
[BREAKING CHANGE] Get-CsOnlineUser: CountryAbbreviation attribute is now only available when used with -Identity parameter.
Both these changes are due to an update to an internal store. You should update scripts to use Country instead of CountryOrRegionDisplayName and make sure that the identity parameter is passed to Get-CsOnlineUser when you want to see the CountryAbbreviation attribute. For example:
(Get-CsOnlineUser -Identity Kim.Akers@Office365itpros.com).CountryAbbreviation
[BREAKING CHANGE] Get-CsOnlineVoicemailPolicy returns data for MaximumRecordingLength in string format instead of TimeSpan.
The change from date time to string output might break some scripts.
Updates in Version 4.0
Version 4.0 of the Microsoft Teams PowerShell module is mostly a fit and finish release. This update marks the completion of the work to modernize the old policy management and voice cmdlets inherited from Skype for Business Online to versions that don’t use remoting. The new versions of the cmdlets should be more stable than their predecessors. Other changes include:
- Release of the *-CsCallingDelegate and *-CsUserCallingSettings cmdlets.
- The InMemory switch is no longer supported for any cmdlet except New-CsVoiceNormalizationRule.
- The following cmdlets are deprecated: ConvertTo-JsonForPSWS, Set-CsUserServicesPolicy, [Get|Set]-CsNetworkConfiguration, [Set|Remove]-CsTenantNetworkConfiguration, New-CsNetworkMediaBypassConfiguration, [Get|Grant|New|Remove|Set]-CsTeamsVerticalPackagePolicy,[Get|Remove|Set]-CsVoiceNormalizationRule.
It doesn’t appear that Microsoft has done any work to the cmdlets used to create and manage teams. Updates for shared channels were available in version 3.1.1. However, some shared channel operations are still not possible in PowerShell, such as inviting a team to join a channel.
Updates in Versions 3.0-3.1.1
Most of the work on the Microsoft Teams PowerShell module since 2.6.0 has focused on the older policy cmdlets inherited from the Skype for Business like Grant-CsApplicationAccessPolicy. The work converts the cmdlets from using remoting (based on the WS-Management protocol) to a more modern implementation better suited for cloud environments. Some performance issues have also been addressed. So far, there are no reports of any problems with the 3.1.1 version.
Updates in 2.6.0
So far, no known errors have shown up in version 2.6 of the Microsoft Teams PowerShell module. The changes noted in the release notes are:
- Fixes the bug where MicrosoftTeams module lookup failed if made a nested module of another custom PowerShell module. Now, MicrosoftTeams cmdlets are available even if it’s a nested module of another module.
- Releases [Get|New|Complete|Clear]-CsOnlineTelephoneNumberOrder cmdlets.
- Releases Get-CsOnlineTelephoneNumberCountry and Get-CsOnlineTelephoneNumberType cmdlets.
- Releases new parameters for these cmdlets : Get-CsOnlineApplicationInstance, New-CsExternalAccessPolicy, New-CsTeamsAppSetupPolicy, New-CsTeamsCallingPolicy, New-CsTeamsCallParkPolicy, New-CsTeamsMeetingPolicy, New-CsTeamsMessagingPolicy, Set-CsTeamsAppSetupPolicy, Set-CsTeamsCallParkPolicy, Set-CsTeamsGuestMessagingConfiguration, Set-CsTeamsMeetingPolicy, Set-CsTenantFederationConfiguration, Set-CsExternalAccessPolicy, Set-CsTeamsCallingPolicy.
- Fixes the failure that occurred when retrying login with Connect-MicrosoftTeams after an incorrect sign-in attempt.
- Fixes Add-TeamChannelUser and Remove-TeamChannelUser failing for private channel.
- Updates to make the module’s release notes available in PowerShell Gallery for each new version.
I will update this list as more information becomes available.
Updates and Issues in 2.5.0
Here are some details of the changes in the 2.5.0 release of the Microsoft Teams PowerShell module:
- Updates for AccessToken login with Connect-MicrosoftTeams. The Access Token login for the Connect-MicrosoftTeams cmdlet now uses a unified token array instead of separate parameters for each resource access token. Some fixes are also included for interactive logins using Connect-MicrosoftTeams in CloudShell.
- Improvements to New-Team cmdlet for team creation scenarios. The improvements are bug fixes to address issues reported when running New-Team to create new teams. However, the improvements appear to have introduced a new set of issues (see below).
- TeamsUnassignedNumberTreatment cmdlets are now available. No further details are available.
- The Get-CsCsOnlineDialInConferencingBridge and Set-CsOnlineDialInConferencingBridge cmdlets are available (if you have Teams Voice licenses).
- “Modernized” (Graph-based) versions of the Get-CsTenant and Get-CSOnlineUser cmdlets (using the identity parameter only) are available. The Get-CSOnlineUser cmdlet, which returns details of a Teams user and the policies assigned to their account, is often used in scripts. Modernization should ensure that output is the same as the old version of the cmdlet but experience tells that this is sometimes not the case, so it is wise to test scripts which use the cmdlet to validate that everything works as expected. For instance, the LineURI property no longer has a “Tel:+” prefix.
One problem reported in 2.5 is that the New-Team cmdlet does not return the GUID (object identifier) of the newly created team. A new team is created successfully but New-Team returns Graph target resource information which must be parsed to extract the GUID. For example, before 2.5, the $TeamId variable would contain a valid GUID. You can see what it now gets from New-Team:
$TeamId = New-Team -DisplayName "Auxerre Lovers" -Description "Auxerre people" -MailNickName Auxerre.Team -Owner Tony.Redmond@office365itpros.com -Visibility Public C:\> $TeamId TargetResourceLocation ---------------------- /teams('75c2bd1a-d67d-417c-99c8-faa14e8be918')/operations('3f6d0c84-e20d-493d-972e-0b5d2f420bb3')
You can extract the GUID from the information returned by New-Team and use it. For example:
$GroupId = $TeamId.TargetResourceLocation.SubString($TeamId.TargetResourceLocation.IndexOf("'")+1,36) Get-Team -GroupId $GroupId GroupId DisplayName Visibility Archived MailNickName Description ------- ----------- ---------- -------- ------------ ----------- 75c2bd1a-d67d-417c-99c8-faa14e8be918 Auxerre Lovers Public False AuxerreLovers Auxerre people
Obviously, going through the extraction is a royal pain. Microsoft withdrew and reissued 2.5 to include the old version of the cmdlet and then fixed the bug in version 2.6.
For some reason, although the documentation for the Connect-MicrosoftTeams cmdlet includes the option to use a certificate thumbprint to authenticate, the cmdlet in 2.5.0 is missing the CertificateThumbPrint parameter. I’ve asked Microsoft why.
Updates in 2.3.1
The changes in the V2.3.1 of the Microsoft Teams PowerShell module are mostly bug fixes and don’t stretch to much new functionality. Here’s what’s important:
- A new cmdlet (Get-MultiGeoRegion) is available to get the multi-geo region for teams and groups. This is part of the Teams support for multi-geo organizations announced at Ignite 2021.
- The release notes for V2.2.0 preview said that another new cmdlet (Get-LicenseReportForChangeNotificationSubscription) would “get details of total change notification events that can be sent to users,” whatever that means. This cmdlet hasn’t made it into V2.3.1.
- The V2.2.0 preview also discussed some internal engineering in the refactoring of remote session management. As Microsoft observed at the time, this change should result in no functional change for tenant admins. There’s no mention of this work for V2.3.1, but Microsoft does say that they have fixed “a large latency issue while remoting commands,” which could be connected.
- General availability for the cmdlets to manage custom group policy assignments. Group policy assignments mean that organizations can build packages (sets) of policies to assign to groups (security groups, Microsoft 365 groups, or distribution lists). Microsoft includes some standard packages in Teams. If you want to build custom packages, you need the famous Teams Advanced Communications license.
- Microsoft notes “updates to input parameters and output formats” for many cmdlets. This appears innocuous (and seem to affect policy cmdlets like Get-CsTeamsMeetingPolicy and Get-CsTeamsMessagingPolicy) but might affect scripts which depend on a certain parameter being passed or returned data being in a certain format. Changes like this underline the need for testing against a new module.
Because of the bug fixes included in module updates, we recommend you download and test your scripts against the latest version of the Teams PowerShell module as soon as convenient. If the tests prove successful, then you can deploy the new module into production.
Some Authentication Issues
Soon after the release of the 2.0 module, people realized that it didn’t work so well with integrated Windows authentication. This arose because of replacing the Active Directory Authentication Library (ADAL) with the Microsoft Authentication Library (MSAL). According to the release notes, V2.3.1 includes fixes for integrated Windows authentication to make the Connect-MicrosoftTeams cmdlet work better. However, some reports indicate that some problems still exist when running Connect-MicrosoftTeams. Organizations should test their scripts to establish if connection failures still exist and report the information to Microsoft.
Microsoft says that the errors in Set-CsUser and other cmdlets seen in earlier versions are now addressed.
Retirement of old Skype for Business Online Cmdlets
Microsoft upgraded the Teams module to 2.0 in March 2021. This was a big update because it marked the incorporation of the cmdlets from the old Skype for Business Online connector. Replacing the Skype for Business Online connector with the Teams PowerShell module means that tenants must upgrade their scripts to ensure that the correct module is loaded. Although the New-CsOnlineSession is no longer necessary to connect to what is now effectively the Teams policy endpoint, the other cmdlets previously accessed through the connector are available after Connect-MicrosoftTeams runs to create a new session. A big advantage is that there’s no need to run the Enable-CsOnlineSessionforReconnection cmdlet to stop the session timing out after an hour.
Stay acquainted with all the moving parts of Office 365 by subscribing to the Office 365 for IT Pros eBook. Monthly updates mean that we stay ahead of the game in terms of warning our readers when they need to take action.