diff --git a/Documentation/SETUP.md b/Documentation/SETUP.md index fb8b0fc1..0114d197 100644 --- a/Documentation/SETUP.md +++ b/Documentation/SETUP.md @@ -57,7 +57,7 @@ potential confusion. At a high level, all you're doing is: The following section describes how to configure your system for use with StoreBroker, and lists the available options for installing the module contents. -### ExecutionPolicy +### ExecutionPolicy Update the `PowerShell ExecutionPolicy` to be `RemoteSigned` (which means that PowerShell scripts that are local to your machine don't need to be signed in order to execute). @@ -165,12 +165,6 @@ StoreBroker has a dependency on dll's from the following NuGet packages: WindowsAzure.Storage v8.1.1: Microsoft.WindowsAzure.Storage.dll Microsoft.Azure.Storage.DataMovement v0.5.1: Microsoft.WindowsAzure.Storage.DataMovement.dll -**For [Telemetry](USAGE.md#telemetry)** - - Microsoft.ApplicationInsights v2.0.1: Microsoft.ApplicationInsights.dll" - Microsoft.Diagnostics.Tracing.EventSource.Redist v1.1.24: Microsoft.Diagnostics.Tracing.EventSource.dll - Microsoft.Bcl.Async v1.0.168.0: Microsoft.Threading.Tasks.dll - During execution of a command, when StoreBroker has need for an object from one of these dll's, if it cannot find the dll, it will automatically download nuget.exe, then download the nuget package that the assembly is in, and finally cache it for the duration of your PowerShell session. @@ -205,7 +199,7 @@ To initially configure StoreBroker with your Developer Account: 2. You must [associate your AAD with your Dev Center account](https://msdn.microsoft.com/windows/uwp/monetize/create-and-manage-submissions-using-windows-store-services#associate-an-azure-ad-application-with-your-windows-dev-center-account) to obtain the credentials to allow StoreBroker to access your account and perform actions on - your behalf. + your behalf. 3. The app you want to publish must already exist. The Windows Store Submission API can only publish updates to existing applications. You can @@ -217,7 +211,7 @@ To initially configure StoreBroker with your Developer Account: submission, the Update attempt will fail. -> These prerequisites come directly from the +> These prerequisites come directly from the > [API Documentation](https://msdn.microsoft.com/windows/uwp/monetize/create-and-manage-submissions-using-windows-store-services). > Refer to that documentation for additional prerequisites. @@ -248,10 +242,10 @@ To get those values: account, and assign it the **Manager** role. If this application already exists in your AAD, you can select it on the **Add Azure AD applications** page to add it to your Dev Center account. Otherwise, you can create a new AAD application on the **Add Azure AD applications** page. - For more information, see [Add and manage Azure AD applications](https://msdn.microsoft.com/windows/uwp/publish/manage-account-users#add-and-manage-azure-ad-applications). + For more information, see [Add and manage Azure AD applications](https://msdn.microsoft.com/windows/uwp/publish/manage-account-users#add-and-manage-azure-ad-applications). 3. Return to the **Manage users** page, click the name of your Azure AD application to go to the - application settings, and copy the **Tenant ID** and **Client ID** values. + application settings, and copy the **Tenant ID** and **Client ID** values. 4. Click **Add new key**. On the following screen, copy the **Key** value, which corresponds to the **Client secret**. You *will not* be able to access this info again after you leave this page, @@ -292,12 +286,12 @@ One way to do this would be the following: 3. Now you can store the password somewhere on disk securely. Doing this will encrypt the password into a plain-text file, and only the same user logged-in to the exact same computer will be able to decrypt it. - + $cred.Password | ConvertFrom-SecureString | Set-Content -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'clientSecret.txt') 4. When you want to create the credentials yourself later on and authenticate (being sure to replace `` and `` with the proper values): - + $clientSecret = Get-Content -Path (Join-Path -Path ([System.Environment]::GetFolderPath('MyDocuments')) -ChildPath 'clientSecret.txt') | ConvertTo-SecureString $cred = New-Object System.Management.Automation.PSCredential "", $clientSecret Set-StoreBrokerAuthentication -TenantId -Credential $cred @@ -348,7 +342,7 @@ That setting (being configured to use the proxy) will be stored for the duration > the profile for you. Then, just add those 3 lines of code from Step 4 into your profile. To stop authenticating with the proxy, at any time simply close your PowerShell console window, or -call: +call: Clear-StoreBrokerAuthentication @@ -403,7 +397,7 @@ started by generating your app's PDP files based on your current published submi Where: * `` is your app's ID. - + * `` is the name of this release. Many teams name their releases as `YYMM` (depending on how often they release). This value will be added to each of the PDP's that are generated, and will impact the expected location of the screenshots being referenced. More on @@ -453,7 +447,7 @@ Every project should have its own StoreBroker config file. The config file has dynamically during your build from a localization service/process, leave both blank and only specify `PDPRootPath` at the commandline so that you can use environment variables to reference the local path, and move on to "**ii**". - + Otherwise, it's necessary for you to provide the path that the PDP's can be found. You'll do this with a combination of these two config values. The general idea is that you have a root folder for PDP's that contains sub-folders named after each @@ -480,7 +474,7 @@ Every project should have its own StoreBroker config file. The config file has be updated with the most recent PDP's, use the first method. If you _will_ be using release-named sub-folders to organize your PDP's, then you may wish to use the second option, and you can either choose to update your config file with the new release name - every time it changes, or provide it at the commandline instead. Your choice. + every time it changes, or provide it at the commandline instead. Your choice. > Remember that you have to escape any backslashes used in the config file. @@ -508,11 +502,11 @@ Every project should have its own StoreBroker config file. The config file has Screenshot2.png you would specify `\\share\MyApp\Images\` as your `ImagesRootPath`, and your PDP file - would set `201605` as the `Release` attribute (at the very top of the file). + would set `201605` as the `Release` attribute (at the very top of the file). `New-SubmissionPackage` would then combine those together at runtime to get the full path to these images. - > Remember that you have to escape any backslashes used in the config file. + > Remember that you have to escape any backslashes used in the config file. vi. `AppxPath` - Follow the guidance in the help comments to correctly specify where the appx packages for your app will be found. Since this is likely part of your build output, you'll @@ -575,7 +569,7 @@ started by generating your IAP's PDP files based on your current published (or p Where: * `` is your IAP's ID. - + * `` is the name of this release. Many teams name their releases as `YYMM` (depending on how often they release). This value will be added to each of the PDP's that are generated, and will impact the expected location of the screenshots being referenced. More on diff --git a/StoreBroker/Helpers.ps1 b/StoreBroker/Helpers.ps1 index 199a00d6..8aae49b6 100644 --- a/StoreBroker/Helpers.ps1 +++ b/StoreBroker/Helpers.ps1 @@ -945,7 +945,7 @@ function Get-HttpWebResponseContent { $content = $null - if ($WebResponse.ContentLength -gt 0) + if (($null -ne $WebResponse) -and ($WebResponse.ContentLength -gt 0)) { $stream = $WebResponse.GetResponseStream() $encoding = [System.Text.Encoding]::UTF8 diff --git a/StoreBroker/StoreBroker.psd1 b/StoreBroker/StoreBroker.psd1 index c4a48fa3..06be4631 100644 --- a/StoreBroker/StoreBroker.psd1 +++ b/StoreBroker/StoreBroker.psd1 @@ -6,7 +6,7 @@ CompanyName = 'Microsoft Corporation' Copyright = 'Copyright (C) Microsoft Corporation. All rights reserved.' - ModuleVersion = '1.19.4' + ModuleVersion = '1.20.0' Description = 'Provides command-line access to the Windows Store Submission REST API.' RootModule = 'StoreIngestionApi' diff --git a/StoreBroker/Telemetry.ps1 b/StoreBroker/Telemetry.ps1 index eb4cdf40..f21a1901 100644 --- a/StoreBroker/Telemetry.ps1 +++ b/StoreBroker/Telemetry.ps1 @@ -1,8 +1,9 @@ # Copyright (C) Microsoft Corporation. All rights reserved. -# Singleton telemetry client. Don't directly access this though....always get it -# by calling Get-TelemetryClient to ensure that the singleton is properly initialized. -$script:SBTelemetryClient = $null +# Singleton. Don't directly access this though....always get it +# by calling Get-BaseTelemetryEvent to ensure that it has been initialized and that you're always +# getting a fresh copy. +$script:SBBaseTelemetryEvent = $null Add-Type -TypeDefinition @" public enum StoreBrokerTelemetryProperty @@ -157,275 +158,208 @@ function Get-PiiSafeString } } -function Get-ApplicationInsightsDllPath +function Get-BaseTelemetryEvent { -<# + <# .SYNOPSIS - Makes sure that the Microsoft.ApplicationInsights.dll assembly is available - on the machine, and returns the path to it. + Returns back the base object for an Application Insights telemetry event. .DESCRIPTION - Makes sure that the Microsoft.ApplicationInsights.dll assembly is available - on the machine, and returns the path to it. - - This will first look for the assembly in the module's script directory. - - Next it will look for the assembly in the location defined by - $SBAlternateAssemblyDir. This value would have to be defined by the user - prior to execution of this cmdlet. + Returns back the base object for an Application Insights telemetry event. - If not found there, it will look in a temp folder established during this - PowerShell session. - - If still not found, it will download the nuget package - for it to a temp folder accessible during this PowerShell session. - - The Git repo for this module can be found here: http://aka.ms/StoreBroker - - .PARAMETER NoStatus - If this switch is specified, long-running commands will run on the main thread - with no commandline status update. When not specified, those commands run in - the background, enabling the command prompt to provide status information. + The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub .EXAMPLE - Get-ApplicationInsightsDllPath - - Returns back the path to the assembly as found. If the package has to - be downloaded via nuget, the command prompt will show a time duration - status counter while the package is being downloaded. + Get-BaseTelemetryEvent - .EXAMPLE - Get-ApplicationInsightsDllPath -NoStatus - - Returns back the path to the assembly as found. If the package has to - be downloaded via nuget, the command prompt will appear to hang during - this time. + Returns back a base telemetry event, populated with the minimum properties necessary + to correctly report up to this project's telemetry. Callers can then add on to the + event as nececessary. .OUTPUTS - System.String - The path to the Microsoft.ApplicationInsights.dll assembly. + [PSCustomObject] #> - [CmdletBinding(SupportsShouldProcess)] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] - param( - [switch] $NoStatus - ) - - $nugetPackageName = "Microsoft.ApplicationInsights" - $nugetPackageVersion = "2.0.1" - $assemblyPackageTailDir = "Microsoft.ApplicationInsights.2.0.1\lib\net45" - $assemblyName = "Microsoft.ApplicationInsights.dll" - - return Get-NugetPackageDllPath -NugetPackageName $nugetPackageName -NugetPackageVersion $nugetPackageVersion -AssemblyPackageTailDirectory $assemblyPackageTailDir -AssemblyName $assemblyName -NoStatus:$NoStatus -} - -function Get-DiagnosticsTracingDllPath -{ -<# - .SYNOPSIS - Makes sure that the Microsoft.Diagnostics.Tracing.EventSource.dll assembly is available - on the machine, and returns the path to it. - - .DESCRIPTION - Makes sure that the Microsoft.Diagnostics.Tracing.EventSource.dll assembly is available - on the machine, and returns the path to it. - - This will first look for the assembly in the module's script directory. - - Next it will look for the assembly in the location defined by - $SBAlternateAssemblyDir. This value would have to be defined by the user - prior to execution of this cmdlet. - - If not found there, it will look in a temp folder established during this - PowerShell session. - - If still not found, it will download the nuget package - for it to a temp folder accessible during this PowerShell session. - - The Git repo for this module can be found here: http://aka.ms/StoreBroker - - .PARAMETER NoStatus - If this switch is specified, long-running commands will run on the main thread - with no commandline status update. When not specified, those commands run in - the background, enabling the command prompt to provide status information. - - .EXAMPLE - Get-DiagnosticsTracingDllPath - - Returns back the path to the assembly as found. If the package has to - be downloaded via nuget, the command prompt will show a time duration - status counter while the package is being downloaded. - - .EXAMPLE - Get-DiagnosticsTracingDllPath -NoStatus + [CmdletBinding()] + param() - Returns back the path to the assembly as found. If the package has to - be downloaded via nuget, the command prompt will appear to hang during - this time. + if ($null -eq $script:SBBaseTelemetryEvent) + { + if (-not (Get-GitHubConfiguration -Name SuppressTelemetryReminder)) + { + Write-Log -Message "Telemetry is currently enabled. It can be disabled by setting ""`$global:SBDisableTelemetry = `$true"". Refer to USAGE.md#telemetry for more information." + } - .OUTPUTS - System.String - The path to the Microsoft.ApplicationInsights.dll assembly. -#> - [CmdletBinding(SupportsShouldProcess)] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] - param( - [switch] $NoStatus - ) + $username = Get-PiiSafeString -PlainText $env:USERNAME - $nugetPackageName = "Microsoft.Diagnostics.Tracing.EventSource.Redist" - $nugetPackageVersion = "1.1.24" - $assemblyPackageTailDir = "Microsoft.Diagnostics.Tracing.EventSource.Redist.1.1.24\lib\net35" - $assemblyName = "Microsoft.Diagnostics.Tracing.EventSource.dll" + $script:SBBaseTelemetryEvent = [PSCustomObject] @{ + 'name' = 'Microsoft.ApplicationInsights.66d83c523070489b886b09860e05e78a.Event' + 'time' = (Get-Date).ToUniversalTime().ToString("O") + 'iKey' = $global:SBApplicationInsightsKey + 'tags' = [PSCustomObject] @{ + 'ai.user.id' = $username + 'ai.session.id' = [System.GUID]::NewGuid().ToString() + 'ai.application.ver' = $MyInvocation.MyCommand.Module.Version.ToString() + 'ai.internal.sdkVersion' = '2.0.1.33027' # The version this schema was based off of. + } + + 'data' = [PSCustomObject] @{ + 'baseType' = 'EventData' + 'baseData' = [PSCustomObject] @{ + 'ver' = 2 + 'properties' = [PSCustomObject] @{ + 'DayOfWeek' = (Get-Date).DayOfWeek.ToString() + 'Username' = $username + } + } + } + } + } - return Get-NugetPackageDllPath -NugetPackageName $nugetPackageName -NugetPackageVersion $nugetPackageVersion -AssemblyPackageTailDirectory $assemblyPackageTailDir -AssemblyName $assemblyName -NoStatus:$NoStatus + return $script:SBBaseTelemetryEvent.PSObject.Copy() # Get a new instance, not a reference } -function Get-ThreadingTasksDllPath +function Invoke-SendTelemetryEvent { <# .SYNOPSIS - Makes sure that the Microsoft.Threading.Tasks.dll assembly is available - on the machine, and returns the path to it. + Sends an event to Application Insights directly using its REST API. .DESCRIPTION - Makes sure that the Microsoft.Threading.Tasks.dll assembly is available - on the machine, and returns the path to it. - - This will first look for the assembly in the module's script directory. + Sends an event to Application Insights directly using its REST API. - Next it will look for the assembly in the location defined by - $SBAlternateAssemblyDir. This value would have to be defined by the user - prior to execution of this cmdlet. - - If not found there, it will look in a temp folder established during this - PowerShell session. - - If still not found, it will download the nuget package - for it to a temp folder accessible during this PowerShell session. + A very heavy wrapper around Invoke-WebRequest that understands Application Insights and + how to perform its requests with and without console status updates. It also + understands how to parse and handle errors from the REST calls. The Git repo for this module can be found here: http://aka.ms/StoreBroker - .PARAMETER NoStatus - If this switch is specified, long-running commands will run on the main thread - with no commandline status update. When not specified, those commands run in - the background, enabling the command prompt to provide status information. - - .EXAMPLE - Get-ThreadingTasksDllPath - - Returns back the path to the assembly as found. If the package has to - be downloaded via nuget, the command prompt will show a time duration - status counter while the package is being downloaded. - - .EXAMPLE - Get-ThreadingTasksDllPath -NoStatus - - Returns back the path to the assembly as found. If the package has to - be downloaded via nuget, the command prompt will appear to hang during - this time. + .PARAMETER TelemetryEvent + The raw object representing the event data to send to Application Insights. .OUTPUTS - System.String - The path to the Microsoft.ApplicationInsights.dll assembly. + [PSCustomObject] - The result of the REST operation, in whatever form it comes in. + + .NOTES + This mirrors Invoke-SBRestMethod extensively, however the error handling is slightly + different. There wasn't a clear way to refactor the code to make both of these + Invoke-* methods share a common base code. Leaving this as-is to make this file + easier to share out with other PowerShell projects. #> - [CmdletBinding(SupportsShouldProcess)] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] + [CmdletBinding()] + [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidGlobalVars", "", Justification="We use global variables sparingly and intentionally for module configuration, and employ a consistent naming convention.")] param( - [switch] $NoStatus + [Parameter(Mandatory)] + [PSCustomObject] $TelemetryEvent ) - $nugetPackageName = "Microsoft.Bcl.Async" - $nugetPackageVersion = "1.0.168.0" - $assemblyPackageTailDir = "Microsoft.Bcl.Async.1.0.168\lib\net40" - $assemblyName = "Microsoft.Threading.Tasks.dll" - - return Get-NugetPackageDllPath -NugetPackageName $nugetPackageName -NugetPackageVersion $nugetPackageVersion -AssemblyPackageTailDirectory $assemblyPackageTailDir -AssemblyName $assemblyName -NoStatus:$NoStatus -} - -function Get-TelemetryClient -{ -<# - .SYNOPSIS - Returns back the singleton instance of the Application Insights TelemetryClient for - this module. - - .DESCRIPTION - Returns back the singleton instance of the Application Insights TelemetryClient for - this module. - - If the singleton hasn't been initialized yet, this will ensure all dependenty assemblies - are available on the machine, create the client and initialize its properties. - - This will first look for the dependent assemblies in the module's script directory. - - Next it will look for the assemblies in the location defined by - $SBAlternateAssemblyDir. This value would have to be defined by the user - prior to execution of this cmdlet. - - If not found there, it will look in a temp folder established during this - PowerShell session. + $jsonConversionDepth = 20 # Seems like it should be more than sufficient + $uri = 'https://dc.services.visualstudio.com/v2/track' + $method = 'POST' + $headers = @{'Content-Type' = 'application/json; charset=UTF-8'} - If still not found, it will download the nuget package - for it to a temp folder accessible during this PowerShell session. + $body = ConvertTo-Json -InputObject $TelemetryEvent -Depth $jsonConversionDepth -Compress + $bodyAsBytes = [System.Text.Encoding]::UTF8.GetBytes($body) - The Git repo for this module can be found here: http://aka.ms/StoreBroker - - .PARAMETER NoStatus - If this switch is specified, long-running commands will run on the main thread - with no commandline status update. When not specified, those commands run in - the background, enabling the command prompt to provide status information. - - .EXAMPLE - Get-TelemetryClient - - Returns back the singleton instance to the TelemetryClient for the module. - If any nuget packages have to be downloaded in order to load the TelemetryClient, the - command prompt will show a time duration status counter during the download process. - - .EXAMPLE - Get-TelemetryClient -NoStatus + try + { + Write-Log -Message "Sending telemetry event data to $uri [Timeout = $global:SBWebRequestTimeoutSec]" -Level Verbose - Returns back the singleton instance to the TelemetryClient for the module. - If any nuget packages have to be downloaded in order to load the TelemetryClient, the - command prompt will appear to hang during this time. + $params = @{} + $params.Add("Uri", $uri) + $params.Add("Method", $method) + $params.Add("Headers", $headers) + $params.Add("UseDefaultCredentials", $true) + $params.Add("UseBasicParsing", $true) + $params.Add("TimeoutSec", $global:SBWebRequestTimeoutSec) + $params.Add("Body", $bodyAsBytes) - .OUTPUTS - Microsoft.ApplicationInsights.TelemetryClient -#> - [CmdletBinding(SupportsShouldProcess)] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidGlobalVars", "", Justification="We use global variables sparingly and intentionally for module configuration, and employ a consistent naming convention.")] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] - param( - [switch] $NoStatus - ) + # Disable Progress Bar in function scope during Invoke-WebRequest + $ProgressPreference = 'SilentlyContinue' - if ($null -eq $script:SBTelemetryClient) + return Invoke-WebRequest @params + } + catch { - Write-Log -Message "Telemetry is currently enabled. It can be disabled by setting ""`$global:SBDisableTelemetry = `$true"". Refer to USAGE.md#telemetry for more information." - Write-Log -Message "Initializing telemetry client." -Level Verbose + $ex = $null + $message = $null + $statusCode = $null + $statusDescription = $null + $innerMessage = $null + $rawContent = $null + + if ($_.Exception -is [System.Net.WebException]) + { + $ex = $_.Exception + $message = $_.Exception.Message + $statusCode = $ex.Response.StatusCode.value__ # Note that value__ is not a typo. + $statusDescription = $ex.Response.StatusDescription + $innerMessage = $_.ErrorDetails.Message + try + { + $rawContent = Get-HttpWebResponseContent -WebResponse $ex.Response + } + catch + { + Write-Log -Message "Unable to retrieve the raw HTTP Web Response:" -Exception $_ -Level Warning + } + } + else + { + Write-Log -Exception $_ -Level Error + throw + } - $dlls = @( - (Get-ThreadingTasksDllPath -NoStatus:$NoStatus), - (Get-DiagnosticsTracingDllPath -NoStatus:$NoStatus), - (Get-ApplicationInsightsDllPath -NoStatus:$NoStatus) - ) + $output = @() + $output += $message - foreach ($dll in $dlls) + if (-not [string]::IsNullOrEmpty($statusCode)) { - $bytes = [System.IO.File]::ReadAllBytes($dll) - [System.Reflection.Assembly]::Load($bytes) | Out-Null + $output += "$statusCode | $($statusDescription.Trim())" } - $username = Get-PiiSafeString -PlainText $env:USERNAME + if (-not [string]::IsNullOrEmpty($innerMessage)) + { + try + { + $innerMessageJson = ($innerMessage | ConvertFrom-Json) + if ($innerMessageJson -is [String]) + { + $output += $innerMessageJson.Trim() + } + elseif (-not [String]::IsNullOrWhiteSpace($innerMessageJson.itemsReceived)) + { + $output += "Items Received: $($innerMessageJson.itemsReceived)" + $output += "Items Accepted: $($innerMessageJson.itemsAccepted)" + if ($innerMessageJson.errors.Count -gt 0) + { + $output += "Errors:" + $output += ($innerMessageJson.errors | Format-Table | Out-String) + } + } + else + { + # In this case, it's probably not a normal message from the API + $output += ($innerMessageJson | Out-String) + } + } + catch [System.ArgumentException] + { + # Will be thrown if $innerMessage isn't JSON content + $output += $innerMessage.Trim() + } + } - $script:SBTelemetryClient = New-Object Microsoft.ApplicationInsights.TelemetryClient - $script:SBTelemetryClient.InstrumentationKey = $global:SBApplicationInsightsKey - $script:SBTelemetryClient.Context.User.Id = $username - $script:SBTelemetryClient.Context.Session.Id = [System.GUID]::NewGuid().ToString() - $script:SBTelemetryClient.Context.Properties[[StoreBrokerTelemetryProperty]::Username] = $username - $script:SBTelemetryClient.Context.Properties[[StoreBrokerTelemetryProperty]::DayOfWeek] = (Get-Date).DayOfWeek - $script:SBTelemetryClient.Context.Component.Version = $MyInvocation.MyCommand.Module.Version.ToString() - } + # It's possible that the API returned JSON content in its error response. + if (-not [String]::IsNullOrWhiteSpace($rawContent)) + { + $output += $rawContent + } - return $script:SBTelemetryClient + $output += "Original body: $body" + $newLineOutput = ($output -join [Environment]::NewLine) + Write-Log -Message $newLineOutput -Level Error + throw $newLineOutput + } } function Set-TelemetryEvent @@ -449,49 +383,31 @@ function Set-TelemetryEvent A collection of name/value pair metrics (string/double) that should be associated with this event. - .PARAMETER NoStatus - If this switch is specified, long-running commands will run on the main thread - with no commandline status update. When not specified, those commands run in - the background, enabling the command prompt to provide status information. - .EXAMPLE Set-TelemetryEvent "zFooTest1" - Posts a "zFooTest1" event with the default set of properties and metrics. If the telemetry - client needs to be created to accomplish this, and the required assemblies are not available - on the local machine, the download status will be presented at the command prompt. + Posts a "zFooTest1" event with the default set of properties and metrics. .EXAMPLE Set-TelemetryEvent "zFooTest1" @{"Prop1" = "Value1"} Posts a "zFooTest1" event with the default set of properties and metrics along with an - additional property named "Prop1" with a value of "Value1". If the telemetry client - needs to be created to accomplish this, and the required assemblies are not available - on the local machine, the download status will be presented at the command prompt. - - .EXAMPLE - Set-TelemetryEvent "zFooTest1" -NoStatus - - Posts a "zFooTest1" event with the default set of properties and metrics. If the telemetry - client needs to be created to accomplish this, and the required assemblies are not available - on the local machine, the command prompt will appear to hang while they are downloaded. + additional property named "Prop1" with a value of "Value1". .NOTES Because of the short-running nature of this module, we always "flush" the events as soon as they have been posted to ensure that they make it to Application Insights. #> - [CmdletBinding(SupportsShouldProcess)] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidGlobalVars", "", Justification="We use global variables sparingly and intentionally for module configuration, and employ a consistent naming convention.")] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] + [CmdletBinding()] + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', + Justification='Function is not state changing')] param( [Parameter(Mandatory)] [string] $EventName, [hashtable] $Properties = @{}, - [hashtable] $Metrics = @{}, - - [switch] $NoStatus + [hashtable] $Metrics = @{} ) if ($global:SBDisableTelemetry) @@ -500,29 +416,41 @@ function Set-TelemetryEvent return } - Write-Log -Message "Executing: $($MyInvocation.Line)" -Level Verbose + Write-InvocationLog -ExcludeParameter @('Properties', 'Metrics') try { - $telemetryClient = Get-TelemetryClient -NoStatus:$NoStatus + $telemetryEvent = Get-BaseTelemetryEvent + Add-Member -InputObject $telemetryEvent.data.baseData -Name 'name' -Value $EventName -MemberType NoteProperty -Force - $propertiesDictionary = New-Object 'System.Collections.Generic.Dictionary[string, string]' - $propertiesDictionary[[StoreBrokerTelemetryProperty]::DayOfWeek] = (Get-Date).DayOfWeek - $Properties.Keys | ForEach-Object { $propertiesDictionary[$_] = $Properties[$_] } + # Properties + foreach ($property in $Properties.GetEnumerator()) + { + Add-Member -InputObject $telemetryEvent.data.baseData.properties -Name $property.Key -Value $property.Value -MemberType NoteProperty -Force + } - $metricsDictionary = New-Object 'System.Collections.Generic.Dictionary[string, double]' - $Metrics.Keys | ForEach-Object { $metricsDictionary[$_] = $Metrics[$_] } + # Measurements + if ($Metrics.Count -gt 0) + { + $measurements = @{} + foreach ($metric in $Metrics.GetEnumerator()) + { + $measurements[$metric.Key] = $metric.Value + } - $telemetryClient.TrackEvent($EventName, $propertiesDictionary, $metricsDictionary); + Add-Member -InputObject $telemetryEvent.data.baseData -Name 'measurements' -Value ([PSCustomObject] $measurements) -MemberType NoteProperty -Force + } - # Flushing should increase the chance of success in uploading telemetry logs - Flush-TelemetryClient -NoStatus:$NoStatus + $null = Invoke-SendTelemetryEvent -TelemetryEvent $telemetryEvent } catch { - # Telemetry should be best-effort. Failures while trying to handle telemetry should not - # cause exceptions in the app itself. - Write-Log -Message "Set-TelemetryEvent failed:" -Exception $_ -Level Error + Write-Log -Level Warning -Message @( + "Encountered a problem while trying to record telemetry events.", + "This is non-fatal, but it would be helpful if you could report this problem", + "to the StoreBroker team for further investigation:" + "", + $_.Exception) } } @@ -549,52 +477,26 @@ function Set-TelemetryException .PARAMETER Properties Additional properties that the caller may wish to be associated with this exception. - .PARAMETER NoFlush - It's not recommended to use this unless the exception is coming from Flush-TelemetryClient. - By default, every time a new exception is logged, the telemetry client will be flushed - to ensure that the event is published to the Application Insights. Use of this switch - prevents that automatic flushing (helpful in the scenario where the exception occurred - when trying to do the actual Flush). - - .PARAMETER NoStatus - If this switch is specified, long-running commands will run on the main thread - with no commandline status update. When not specified, those commands run in - the background, enabling the command prompt to provide status information. - .EXAMPLE Set-TelemetryException $_ Used within the context of a catch statement, this will post the exception that just - occurred, along with a default set of properties. If the telemetry client needs to be - created to accomplish this, and the required assemblies are not available on the local - machine, the download status will be presented at the command prompt. - - .EXAMPLE - Set-TelemetryException $_ -NoStatus - - Used within the context of a catch statement, this will post the exception that just - occurred, along with a default set of properties. If the telemetry client needs to be - created to accomplish this, and the required assemblies are not available on the local - machine, the command prompt will appear to hang while they are downloaded. + occurred, along with a default set of properties. .NOTES Because of the short-running nature of this module, we always "flush" the events as soon as they have been posted to ensure that they make it to Application Insights. #> - [CmdletBinding(SupportsShouldProcess)] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidGlobalVars", "", Justification="We use global variables sparingly and intentionally for module configuration, and employ a consistent naming convention.")] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] + [CmdletBinding()] + [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', + Justification='Function is not state changing.')] param( [Parameter(Mandatory)] [System.Exception] $Exception, [string] $ErrorBucket, - [hashtable] $Properties = @{}, - - [switch] $NoFlush, - - [switch] $NoStatus + [hashtable] $Properties = @{} ) if ($global:SBDisableTelemetry) @@ -603,104 +505,77 @@ function Set-TelemetryException return } - Write-Log -Message "Executing: $($MyInvocation.Line)" -Level Verbose + Write-InvocationLog -ExcludeParameter @('Exception', 'Properties') try { - $telemetryClient = Get-TelemetryClient -NoStatus:$NoStatus + $telemetryEvent = Get-BaseTelemetryEvent - $propertiesDictionary = New-Object 'System.Collections.Generic.Dictionary[string,string]' - $propertiesDictionary[[StoreBrokerTelemetryProperty]::Message] = $Exception.Message - $propertiesDictionary[[StoreBrokerTelemetryProperty]::HResult] = "0x{0}" -f [Convert]::ToString($Exception.HResult, 16) - $Properties.Keys | ForEach-Object { $propertiesDictionary[$_] = $Properties[$_] } + $telemetryEvent.data.baseType = 'ExceptionData' + Add-Member -InputObject $telemetryEvent.data.baseData -Name 'handledAt' -Value 'UserCode' -MemberType NoteProperty -Force + # Properties if (-not [String]::IsNullOrWhiteSpace($ErrorBucket)) { - $propertiesDictionary[[StoreBrokerTelemetryProperty]::ErrorBucket] = $ErrorBucket + Add-Member -InputObject $telemetryEvent.data.baseData.properties -Name 'ErrorBucket' -Value $ErrorBucket -MemberType NoteProperty -Force } - $telemetryClient.TrackException($Exception, $propertiesDictionary); - - # Flushing should increase the chance of success in uploading telemetry logs - if (-not $NoFlush) + Add-Member -InputObject $telemetryEvent.data.baseData.properties -Name 'Message' -Value $Exception.Message -MemberType NoteProperty -Force + Add-Member -InputObject $telemetryEvent.data.baseData.properties -Name 'HResult' -Value ("0x{0}" -f [Convert]::ToString($Exception.HResult, 16)) -MemberType NoteProperty -Force + foreach ($property in $Properties.GetEnumerator()) { - Flush-TelemetryClient -NoStatus:$NoStatus + Add-Member -InputObject $telemetryEvent.data.baseData.properties -Name $property.Key -Value $property.Value -MemberType NoteProperty -Force } - } - catch - { - # Telemetry should be best-effort. Failures while trying to handle telemetry should not - # cause exceptions in the app itself. - Write-Log -Message "Set-TelemetryException failed:" -Exception $_ -Level Error - } -} - -function Flush-TelemetryClient -{ -<# - .SYNOPSIS - Flushes the buffer of stored telemetry events to the configured Applications Insights instance. - - .DESCRIPTION - Flushes the buffer of stored telemetry events to the configured Applications Insights instance. - - The Git repo for this module can be found here: http://aka.ms/StoreBroker - - .PARAMETER NoStatus - If this switch is specified, long-running commands will run on the main thread - with no commandline status update. When not specified, those commands run in - the background, enabling the command prompt to provide status information. - - .EXAMPLE - Flush-TelemetryClient - - Attempts to push all buffered telemetry events for this telemetry client immediately to - Application Insights. If the telemetry client needs to be created to accomplish this, - and the required assemblies are not available on the local machine, the download status - will be presented at the command prompt. - - .EXAMPLE - Flush-TelemetryClient -NoStatus - - Attempts to push all buffered telemetry events for this telemetry client immediately to - Application Insights. If the telemetry client needs to be created to accomplish this, - and the required assemblies are not available on the local machine, the command prompt - will appear to hang while they are downloaded. -#> - [CmdletBinding(SupportsShouldProcess)] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidGlobalVars", "", Justification="We use global variables sparingly and intentionally for module configuration, and employ a consistent naming convention.")] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseApprovedVerbs", "", Justification="Internal-only helper method. Matches the internal method that is called.")] - [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] - param( - [switch] $NoStatus - ) - - if ($global:SBDisableTelemetry) - { - Write-Log -Message "Telemetry has been disabled via `$global:SBDisableTelemetry. Skipping reporting event." -Level Verbose - return - } - Write-Log -Message "Executing: $($MyInvocation.Line)" -Level Verbose + # Re-create the stack. We'll start with what's in Invocation Info since it's already + # been broken down for us (although it doesn't supply the method name). + $parsedStack = @( + [PSCustomObject] @{ + 'assembly' = $MyInvocation.MyCommand.Module.Name + 'method' = '' + 'fileName' = $Exception.ErrorRecord.InvocationInfo.ScriptName + 'level' = 0 + 'line' = $Exception.ErrorRecord.InvocationInfo.ScriptLineNumber + } + ) - $telemetryClient = Get-TelemetryClient -NoStatus:$NoStatus + # And then we'll try to parse ErrorRecord's ScriptStackTrace and make this as useful + # as possible. + $stackFrames = $Exception.ErrorRecord.ScriptStackTrace -split [Environment]::NewLine + for ($i = 0; $i -lt $stackFrames.Count; $i++) + { + $frame = $stackFrames[$i] + if ($frame -match '^at (.+), (.+): line (\d+)$') + { + $parsedStack += [PSCustomObject] @{ + 'assembly' = $MyInvocation.MyCommand.Module.Name + 'method' = $Matches[1] + 'fileName' = $Matches[2] + 'level' = $i + 1 + 'line' = $Matches[3] + } + } + } - try - { - $telemetryClient.Flush() - } - catch [System.Net.WebException] - { - Write-Log -Message "Encountered exception while trying to flush telemetry events:" -Exception $_ -Level Warning + # Finally, we'll build up the Exception data object. + $exceptionData = [PSCustomObject] @{ + 'id' = (Get-Date).ToFileTime() + 'typeName' = $Exception.GetType().FullName + 'message' = $Exception.Message + 'hasFullStack' = $true + 'parsedStack' = $parsedStack + } - Set-TelemetryException -Exception ($_.Exception) -ErrorBucket "TelemetryFlush" -NoFlush -NoStatus:$NoStatus + Add-Member -InputObject $telemetryEvent.data.baseData -Name 'exceptions' -Value @($exceptionData) -MemberType NoteProperty -Force + $null = Invoke-SendTelemetryEvent -TelemetryEvent $telemetryEvent } catch { - # Any other scenario is one that we want to identify and fix so that we don't miss telemetry - Write-Log -Level Warning -Exception $_ -Message @( + Write-Log -Level Warning -Message @( "Encountered a problem while trying to record telemetry events.", "This is non-fatal, but it would be helpful if you could report this problem", - "to the StoreBroker team for further investigation:") + "to the StoreBroker team for further investigation:", + "", + $_.Exception) } }