Include steps in the readme on how to configure the environment

README.md

@@ -1,20 +1,20 @@
 # Table of Contents
-- [Table of Contents](#table-of-contents)
-- [Intune-PowerShell-SDK](#intune-powershell-sdk)
-- [Getting started](#getting-started)
-    - [One-time setup (PowerShell Gallery)](#one-time-setup-powershell-gallery)
-    - [One-time setup (GitHub)](#one-time-setup-github)
-    - [Before this module is used in your organization](#before-this-module-is-used-in-your-organization)
-    - [Each time you use the module](#each-time-you-use-the-module)    
-    - [Discovering available commands](#discovering-available-commands)
-- [Example usage](#example-usage)
-    - [Retrieving objects](#retrieving-objects)
-    - [Creating objects](#creating-objects)
-    - [Modifying objects](#modifying-objects)
-    - [Deleting objects](#deleting-objects)
-    - [Calling functions and actions](#calling-functions-and-actions)
-- [Notable features](#notable-features)
-- [Known issues and workarounds](#known-issues-and-workarounds)
+- [Table of Contents](#Table-of-Contents)
+- [Intune-PowerShell-SDK](#Intune-PowerShell-SDK)
+- [Getting started](#Getting-started)
+  - [One-time setup (PowerShell Gallery)](#One-time-setup-PowerShell-Gallery)
+  - [One-time setup (GitHub)](#One-time-setup-GitHub)
+  - [Before this module is used in your organization](#Before-this-module-is-used-in-your-organization)
+  - [Each time you use the module](#Each-time-you-use-the-module)
+  - [Discovering available commands](#Discovering-available-commands)
+- [Example usage](#Example-usage)
+  - [Retrieving objects](#Retrieving-objects)
+  - [Creating objects](#Creating-objects)
+  - [Modifying objects](#Modifying-objects)
+  - [Deleting objects](#Deleting-objects)
+  - [Calling functions and actions](#Calling-functions-and-actions)
+- [Notable features](#Notable-features)
+- [Known issues and workarounds](#Known-issues-and-workarounds)
 
 # Intune-PowerShell-SDK
 This repository contains the source code for the PowerShell module which provides support for the Intune API through Microsoft Graph.
@@ -31,42 +31,68 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 ```PowerShell
 Install-Module -Name Microsoft.Graph.Intune
 ```
+
 ## One-time setup (GitHub)
 1. Download the module from the [Releases](https://github.com/Microsoft/Intune-PowerShell-SDK/releases) tab in the GitHub repository.
 2. The "drop\outputs\build\Release\net471" folder in the zip file contains the module.
-    - If you are using Windows, extract the "net471" folder.  **You must have .NET 4.7.1 or higher installed**.    
+    - If you are using Windows, extract the "net471" folder.  **You must have .NET 4.7.1 or higher installed**.
 3. The module manifest is the "Microsoft.Graph.Intune.psd1" file inside this folder.  This is the file you would refer to when importing the module.
 4. Import the module:
 ```PowerShell
 Import-Module $sdkDir/Microsoft.Graph.Intune.psd1
 ```
+
 ## Before this module is used in your organization
 An admin user must provide consent for this app to be used in their organization.  This can be done with the following command:
 ```PowerShell
 Connect-MSGraph -AdminConsent
 ```
+
 ## Each time you use the module
 To authenticate with Microsoft Graph (this is not required when using CloudShell):
 ```PowerShell
 Connect-MSGraph
 ```
-To authenticate with Microsoft Graph using [System.Management.Automation.PSCredential]
+
+To authenticate with Microsoft Graph using a [PSCredential] object:
+```PowerShell
+# 1. Create the PSCredential object
+$adminUPN = Read-Host -Prompt "Enter UPN"
+$adminPwd = Read-Host -AsSecureString -Prompt "Enter password for $adminUPN"
+$creds = New-Object System.Management.Automation.PSCredential ($adminUPN, $adminPwd)
+
+# 2. Log in with these credentials
+Connect-MSGraph -PSCredential $creds
+```
+
+To authenticate in a non-standard environment:
 ```PowerShell
-$adminUPN=Read-Host -Prompt "Enter UPN"
-$adminPwd=Read-Host -AsSecureString -Prompt "Enter password for $adminUPN"
-$creds = New-Object System.Management.Automation.PSCredential ($AdminUPN, $adminPwd)
-$connection = Connect-MSGraph -PSCredential $creds
+# 1. Setup the environment
+# For example, in a National Cloud environment, the following is required before logging in
+Update-MSGraphEnvironment -AuthUrl 'https://login.microsoftonline.us/common' -GraphBaseUrl 'https://graph.microsoft.us' -GraphResourceId 'https://graph.microsoft.us' -SchemaVersion 'beta'
+
+# 2. Log in
+Connect-MSGraph
+
+# 3. Use the cmdlets
+# NOTE: If the schema version has been changed to something other than "v1.0" as in the above
+#   "Update-MSGraphEnvironment" command, only "Invoke-MSGraphRequest" should be used to make calls,
+#   because the standard cmdlets (e.g. "Get-IntuneMobileApp") have been generated based on the
+#   "v1.0" schema, and can produce unexpected results when used with other schema versions
+Invoke-MSGraphRequest -HttpMethod GET -Url 'deviceAppManagement/mobileApps'
 ```
 
 ## Discovering available commands
 Get the full list of available cmdlets:
 ```PowerShell
 Get-Command -Module Microsoft.Graph.Intune
 ```
+
 Get documentation on a particular cmdlet:
 ```PowerShell
 Get-Help <cmdlet name>
 ```
+
 Use a UI to see the parameter sets more easily:
 ```PowerShell
 Show-Command <cmdlet name>
@@ -78,14 +104,17 @@ Get all Intune applications:
 ```PowerShell
 Get-IntuneMobileApp
 ```
+
 Get all Intune device configurations:
 ```PowerShell
 Get-IntuneDeviceConfigurationPolicy
 ```
+
 Get all Intune managed devices:
 ```PowerShell
 Get-IntuneManagedDevice
 ```
+
 Get a filtered list of applications and select only the "displayName" and "publisher" properties:
 ```PowerShell
 # The filter string follows the same rules as specified in the OData v4.0 specification.
@@ -141,10 +170,10 @@ $deviceToLock | Invoke-IntuneManagedDeviceRemoteLock
 
 # Known issues and workarounds
 - Importing the `MSOnline` cmdlets before importing this `Intune` module will cause errors. Please use the `AzureAD` module instead, as the `MSOnline` module is deprecated.
-    - If you absolutely must use the `MSOnline` module, it should be imported AFTER the `Intune` module. Note, however, that this is not officially supported.
+  - If you absolutely must use the `MSOnline` module, it should be imported AFTER the `Intune` module. Note, however, that this is not officially supported.
 - If downloaded from Github, the file "Microsoft.Intune.PowerShellGraphSDK.dll" may be blocked when a release is first downloaded.  This will stop the assembly from correctly loading (and you will see an error message if you try to import the module).
 ```PowerShell
 Dir -Recurse $sdkDir | Unblock-File
 ```
 - The SDK is built out of Microsoft Graph v1.0 release, some functionality available in the Intune Administration UI is built using the Microsoft Graph beta release.
-    - Workaround is to use Invoke-RestMethod for such functionality. For more details see: https://github.com/Microsoft/Intune-PowerShell-SDK/issues/14 
+  - Workaround is to use Invoke-RestMethod for such functionality. For more details see: https://github.com/Microsoft/Intune-PowerShell-SDK/issues/14