Standardise (#1)

* Actually write it as a function

Signed-off-by: Luke Tainton <luke@tainton.uk>

* Fix readme headers

Import-TeamsUsers.ps1

@@ -1,53 +0,0 @@
-function Import-TeamsUsers {
-    Param(
-        [parameter(Mandatory=$true,HelpMessage="Specify Group ID")]
-        $GroupId,
-        [parameter(Mandatory=$true,HelpMessage="Specify CSV file")]
-        $File
-    )
-
-    # Import CSV file and required module
-    $Users = Import-CSV $File
-    $UserCount = $Users | Measure-Object | Select-Object -expand count
-    Import-Module -Name MicrosoftTeams
-
-    # Check Team exists
-    Try {
-        $Team = Get-Team -GroupId $GroupId
-        If ($Team) {
-            $TeamName = $Team.DisplayName
-            Write-Host -ForegroundColor Green "Team $TeamName exists!"
-        }
-    } Catch [System.UnauthorizedAccessException] {
-        # User is not authenticated
-        Write-Host -ForegroundColor Red "You need to authenticate to Microsoft Teams before continuing. Please run 'Connect-MicrosoftTeams' and try again."
-        Break
-    } Catch [System.Net.Http.HttpRequestException] {
-        # Team does not exist
-        Write-Host -ForegroundColor Red "Team with ID $GroupId does not exist!"
-        Break
-    }
-
-    $Consent = Read-Host -Prompt "You are about to add $UserCount users. Are you sure? [y/N]"
-    If ($Consent -eq "y" -Or $Consent -eq "Y") {
-        $Users | ForEach-Object {
-            $User = $_.email
-            $Role = $_.role
-            Write-Host "Adding user $User with role $Role"
-            Add-TeamUser -GroupId $GroupId -Role $Role -User $User -ErrorAction SilentlyContinue
-        }
-    } Else {
-        Write-Host -ForegroundColor Red "Aborting."
-    }
-
-}
-
-
-$GroupId = ""
-$File = ""
-
-If ($GroupId -And $File) {
-	Import-TeamsUsers -GroupId $GroupId -File $File
-} Else {
-	Write-Host -ForegroundColor Red "`$GroupId and/or `$File missing."
-}

Import-TeamsUsers.psm1

@@ -0,0 +1,84 @@
+Function Import-TeamsUsers {
+
+<#
+    .SYNOPSIS
+    Import-TeamsUsers is a Powershell function that will enrol users from a CSV file into a given Microsoft Teams group.
+
+    .DESCRIPTION
+    Import-TeamsUsers is a Powershell function that will enrol users from a CSV file into a given Microsoft Teams group.
+    It has two required parameters (switches): -GroupId and -File. 
+
+    .PARAMETER GroupId
+    Specifies the unique identified for the destination Team. This can be retrieved from Powershell by executing the Get-Team cmdlet.
+
+    .PARAMETER File
+    The path to the CSV file that contains your users. Can either be an absolute path or relative path.
+
+    .EXAMPLE
+    Import-TeamsUsers -GroupId "00000000-0000-0000-0000-000000000000" -File "users.csv"
+#>
+
+    Param(
+        [parameter(Mandatory=$true, position=0, ParameterSetName='Params', HelpMessage="Specify Group ID")]
+        [string]$GroupId,
+        [parameter(Mandatory=$true, position=1, ParameterSetName='Params', HelpMessage="Specify CSV file")]
+        [string]$File
+    )
+
+    Begin {
+        ##### IMPORT CSV FILE #####
+        If ($File) {
+            $Users = Import-CSV $File
+        } Else {
+            Write-Host -ForegroundColor Red "CSV file not specified or does not exist."
+            Exit
+        }
+
+        ##### CHECK MODULE IS INSTALLED AND IMPORTED #####
+        if (Get-Module -ListAvailable -Name MicrosoftTeams) {
+            Import-Module -Name MicrosoftTeams
+            Connect-MicrosoftTeams
+        } else {
+            Write-Host -ForegroundColor Red "Module MicrosoftTeams doesn't exist. Please run 'Install-Module -Name MicrosoftTeams' and retry."
+            Exit
+        }
+
+        ##### CHECK TEAM EXISTS #####
+        Try {
+            $Team = Get-Team -GroupId $GroupId
+            If ($Team) {
+                $TeamName = $Team.DisplayName
+                Write-Host -ForegroundColor Green "Team $TeamName exists!"
+            }
+        } Catch [System.UnauthorizedAccessException] {
+            # User is not authenticated or does not have access
+            Write-Host -ForegroundColor Red "You do not have access to manage this team."
+            Exit
+        } Catch [System.Net.Http.HttpRequestException] {
+            # Team does not exist
+            Write-Host -ForegroundColor Red "Team with ID $GroupId does not exist."
+            Exit
+        }
+
+    }
+    Process {
+        $UsersAdded = 0;
+        $UserCount = $Users | Measure-Object | Select-Object -expand count
+        $Consent = Read-Host -Prompt "You are about to add $UserCount users. Are you sure? [y/N]"
+        If ($Consent -eq "y" -Or $Consent -eq "Y") {
+            $Users | ForEach-Object {
+                $User = $_.email
+                $Role = $_.role
+                Write-Host "Adding user $User with role $Role"
+                If (Add-TeamUser -GroupId $GroupId -Role $Role -User $User -ErrorAction SilentlyContinue) {$global:UsersAdded++}
+            }
+        } Else {
+            Write-Host -ForegroundColor Red "Aborting."
+            Exit
+        }
+    }
+    
+    End {
+        Write-Host -ForegroundColor Green "$UsersAdded added successfully."
+    }
+}

README.md

@@ -3,26 +3,22 @@ A Powershell script that imports users from a CSV into a Microsoft Teams team.
 
 # Setting up your device
 This script runs via PowerShell. If you're on Windows, you'll already have this. If not, please download it from the [releases page](https://github.com/PowerShell/PowerShell/releases). Once you've got PowerShell:
-1. Open PowerShell.
+1. Open PowerShell as an administrator.
 2. Allow remote scripts to execute by running `Set-ExecutionPolicy RemoteSigned`. If you don't do this, the script won't run.
 3. Install the Microsoft Teams module. To do this, run `Install-Module -Name MicrosoftTeams`. Accept any prompts that you are given.
 
 # Gathering information
 You'll need to do a few things before you can run the script:
 1. Have a CSV file with the users you want to add. This needs to be in the format `email,role`. You can copy the template if required.
-2. Import the Microsoft Teams module. Run `Import-Module -Name MicrosoftTeams` in your Powershell terminal.
-3. Authenticate to Microsoft Teams. Run `Connect-MicrosoftTeams` in your Powershell terminal and follow the instructions.
-4. Get your group ID. Run `Get-Team -User <EMAIL>`, substituting `<EMAIL>` for your Office 365 email address, to list all teams you are a member of.
+2. Get your group ID. Import the MS Teams module (`Import-Module -Name MicrosoftTeams`) and run `Get-Team -User <EMAIL>`, substituting `<EMAIL>` for your Office 365 email address, to list all teams you are a member of.
 
 # Running the script
-1. Copy or move the CSV file to the same folder that the `Import-TeamsUsers.ps1` file is in.
-2. Open the `Import-TeamsUsers.ps1` file.
-3. Modify the `$GroupId` variable to the Group ID you found from step 4 in the section above.
-4. Modify the `$File` variables to the name of your CSV file.
-5. Run the script. 
+1. Download the repository to your PC.
+2. Change directory to where you downloaded the repository and import the Import-TeamsUsers module (`Import-Module ./Import-TeamsUsers.psm1`).
+3. Run `Import-TeamsUsers -GroupId <GROUPID> -File <FILE>`.
 
 # Need help?
-If you require assistance running the script, please [send me an email](mailto:luke@tainton.uk?subject=I%20need%20help%20running%20Import-TeamsUsers).
+If you require assistance running the script, see the help by executing `Get-Help Import-TeamsUsers` (requires importing the module first - see step 2 above). If you still need help, please [send me an email](mailto:luke@tainton.uk?subject=I%20need%20help%20running%20Import-TeamsUsers).
 
 # Issues? Want a new feature?
 If you're having problems with the script or have an idea for a new feature, please check [here](https://github.com/luketainton/Import-TeamsUsers/issues) to see if someone else is having the same problem, and open an issue if one doesn't already exist. If you can implement a fix or feature request, please file a pull request!