In June 2020, Microsoft released into preview new functionality in the Microsoft Teams PowerShell module to connect to Skype for Business Online. Before this, two modules were required to manage Microsoft Teams and Skype for Business Online: the Skype for Business Online Windows PowerShell module and the Microsoft Teams module.
In this post, you will learn:
- How to remove the Skype for Business Online Connector module
- Install the preview version of the Microsoft Teams module
- The differences in connecting to Skype for Business Online using PowerShell 5.1 and 7.
Microsoft released even more functionality in version 2.0.0 of the Microsoft Teams PowerShell module! Read more about these updates here!
A Bit of History
Let’s cover some history of these two modules. First, the SkypeOnlineConnector module came with the release of Skype for Business Online (formerly Lync Online). As of version 126.96.36.199, this module has two functions and three cmdlets:
- Function: New-CsOnlineSession
- Function: Enable-CsOnlineSessionForReconnection
- Cmdlet: Get-CsOnlinePowerShellAccessInformation
- Cmdlet: Get-CsOnlinePowerShellAccessToken
- Cmdlet: Get-CsOnlinePowerShellEndpoint
There are two functions used for making connections to your Skype for Business Online tenant. The New-CsOnlineSession function created a remote PowerShell session to Skype for Business Online. You import that session using Import-PSSession. This session downloads a module prefixed with “tmp” containing the remaining commands to manage the service.
This model allows for adding new commands without releasing and installing a new module. Instead, the new commands are downloaded through the “tmp” module when the remote session is created. However, you can only download the Skype for Business Online PowerShell module and install it manually using an MSI. It is not available for installation from the PowerShell Gallery.
After Microsoft Teams came around, Microsoft released its own PowerShell module. You install it from the PowerShell Gallery:
Install-Module -Name MicrosoftTeams
This module includes basic commands around team, channel, and user management.
However, Skype for Business Online continued to receive new Teams commands (often designated in the commands with “CsTeams”). The older Skype module is still needed to manage some settings, while this second Teams module gains additional functionality.
Merging the Modules
Back in the What’s New in Microsoft Teams | June 2020 edition, Microsoft had this blurb that the Skype for Business Online Connector commands will be consolidated into the Teams module:
While this was later removed from the blog post, Microsoft is taking commands from the Skype Online PowerShell module and putting them into the Teams module. You still need to use the New-CsOnlineSession command to make the remote PowerShell session and import it, but you only need to install one module.
However, the module version 1.1.3 is currently in preview and this generally means it is not recommended for production use.
Configuring the Modules
To use this preview module with the merged commands, uninstall the Skype for Business Online Connector module installed using the MSI.
To remove the module, go into Add/Remove programs, find the installed module, and uninstall it like any other program on the computer:
You cannot use the Uninstall-Module command to remove the package in PowerShell as the package was not installed using the Install-Module command.
Next, remove the current version of the Microsoft Teams PowerShell module before installing the preview version. Since this package was installed from the PowerShell Gallery, use the Uninstall-Module command to remove all versions of the module:
Uninstall-Module -Name MicrosoftTeams -AllVersions
Once the module is removed, install the 1.1.3 preview version using the following command:
Install-Module MicrosoftTeams -AllowPrerelease -RequiredVersion "1.1.3-preview"
If the preview version changes in the future, be sure to update the code to reflect the new version. You view which versions are in preview by looking at the version history of the module in PowerShell Gallery:
If you select the link for the version, it will also provide the exact command to install the module:
Exploring the Preview Module
With the preview module installed, you view the available functions and cmdlets using this line of PowerShell code:
Get-Command -Module MicrosoftTeams
Looking through the list, you’ll see the familiar New-CsOnlineSession cmdlet available. You still need to create the session and import it, but the command to do so is in the same module as other Teams commands.
Notably missing is the Enable-CsOnlineSessionForReconnection. This command helped create new sessions when the previous one timed-out after 60 minutes.
The process for connecting to Skype for Business Online is largely unchanged in PowerShell 5.1. You create and import a Skype Online session. You can pass it a PSCredential object with the username and password, or just run the command and it will prompt for credentials. Once completed, you will see the familiar “tmp” module imported with the commands.
$skype = New-CsOnlineSession Import-PSSession -Session $skype
Compatibility with PowerShell 7
Up until this point, the Skype for Business Online module did not work in PowerShell 7 when creating the remote Skype session. This is due to the module not being .NET Core compatible (I opened an issue for it back in November 2019). I believe I even tried using the Windows compatibility mode but still a no-go. Microsoft even warns that the Teams module has known issues in PowerShell 7:
However, the New-CsOnlineSession in the Teams module does work inside of PowerShell 7, and it uses a new way to authenticate. Try creating a new remote session using the same method from earlier:
$skypePS7 = New-CsOnlineSession
PowerShell displays a warning message to navigate to https://microsoft.com/devicelogin and enter the code to authenticate. This process is the same if you are signing into a Teams phone, and I believe the Azure CLI module performs the same type of authentication.
After navigating to that URL, the site will prompt for the code from the PowerShell window. It will then ask for credentials or verify which account to use.
The PowerShell 7 window displays a flurry of output showing a token being requested, created, and stored in the cache. You’ll see the token is good for 1 hour after its creation.
From here, continue like always and import the session:
Import-PSSession -Session $skypePS7
Like the older Skype Online Connector module, it will import a “tmp” with all the familiar commands.
Refreshing the Remote Session
When the access token expires in an hour, the next command you run will prompt for an OAuth password. I’ve tried entering my admin account password, but it doesn’t like this very much. We can also see that the PSSession is broken:
From here, I decided to re-run the New-CsOnlineSession command from earlier, and this time it does not require me to authenticate. You will see in the output that PowerShell used a refresh token instead.
After I create the session, I run Import-PSSession with the -AllowClobber parameter. This will allow duplicate commands already imported from the first “tmp” module.
$skypePS7 = New-CsOnlineSession Import-PSSession -Session $skypePS7 -AllowClobber
Adding the New-CsOnlineSession command into the Teams module is a great step in simplifying the modules for managing both services. However, you still have to make two connections, one using Connect-MicrosoftTeams and another using New-CsOnlineSession.
Microsoft continues to add commands for administering Teams policies in the Skype Online module. This makes me cautious that it will be a long time before there is a unified module for managing Teams.
Microsoft Docs: Microsoft Teams PowerShell Overview
Microsoft Docs: Microsoft Teams PowerShell Release Notes
Microsoft Docs: Install Microsoft Teams PowerShell
PowerShell Gallery: Microsoft Teams
Check out my related article on troubleshooting errors connecting to Skype for Business Online PowerShell.