SQL Server Reporting Services PowerShell utilities
This project contains PowerShell scripts that allow you to perform various operations with SQL Server Reporting Services and Power BI Report Server. In order to use the scripts included in this project successfully, please download/clone the entire project as there are dependencies between the scripts.
All of our scripts were written with the assumption that you will be executing them against Power BI Report Server (PBIRS). However, we understand this may not be the case for you. So for each script, you will see that we have provided a way for you to specify the SQL Server Reporting Services (SSRS) version instead of PBIRS. Sometimes the instance name is also required. If you do not provide one, we will assume that you want to execute this against the default instance.
Note: SSRS 2017 and later, as well as PBIRS do not support changing the instance names from 'SSRS' and 'PBIRS' respectively.
Please ensure you're running PowerShell version 3.0+
$PSVersionTableInvoke-Expression (Invoke-WebRequest https://raw.githubusercontent.com/Microsoft/ReportingServicesTools/master/Install.ps1 -UseBasicParsing)or
Invoke-Expression (Invoke-WebRequest https://aka.ms/rstools -UseBasicParsing)or
Install-Module -Name ReportingServicesToolsNote: Using Install-Module is the preferred installation method for most users.
The ZIP installer requires Windows PowerShell 3.0 or later and .NET Framework 4.5
or later. It defaults to
Documents\WindowsPowerShell\Modules\ReportingServicesTools, even when you run
Install.ps1 from a local checkout. Its optional -Path is a container:
the installer creates or replaces only the ReportingServicesTools child directory.
An explicit container must be empty or contain only that identified module.
Checkouts, junctions, symbolic links, broad system/user directories and unrecognized
module directories are rejected. Existing module files absent from the selected
archive also block an update; move custom content aside before retrying.
The installer downloads and validates a ZIP in a unique staging directory before replacing the module. Replacement or import failures restore the previous installation. If rollback fails, the error identifies retained recovery files. This changes the old installer behavior: it no longer deletes all files in the supplied container or installs repository-level files alongside the module.
Publish-RsProject accepts the strings True and False for OverwriteDatasets and
OverwriteDataSources, including values piped from Get-RsDeploymentConfig.
With False, an existing shared item is skipped without uploading it or changing its
data-source references. Missing items are still created. With True, shared items
are created or replaced and newly deployed dataset references are configured.
If omitted, datasets are overwritten and existing data sources are retained, preserving
the command's previous defaults. Report deployment continues to overwrite reports.
Lookup failures other than HTTP 404 stop deployment rather than being treated as
missing items. -WhatIf makes no deployment requests.
Get-RsDeploymentConfig -RsProjectFile 'C:\Reports\Reports.rptproj' -ConfigurationToUse Release |
Add-Member -PassThru -MemberType NoteProperty -Name ReportPortal -Value 'http://localhost/reports/' |
Publish-RsProject -OverwriteDatasets False -OverwriteDataSources FalseCopy-RsSubscription -RsItem keeps the same explicit destination for every
subscription in an array or pipeline. Use -RsFolder to select destination reports
by their source names instead.
Write-RsRestCatalogItem preserves an .rsds file's Enabled value. If the element
is absent, the source defaults to enabled, matching the SOAP upload command.
Invalid XML Boolean values are rejected before upload.
The following is a list of commands which are available for you to use once you follow the steps in the Installation
| Command | Description |
|---|---|
| Backup-RsEncryptionKey | This command backs up the encryption key used by SQL Server Reporting Services to protect sensitive content. |
| Connect-RsReportServer | This command connects to Reporting Services and sets default connection information. |
| Copy-RsSubscription | This command adds a retrieved subscription to an existing report. For use with Get-RsSubscription. |
| Export-RsSubscriptionXml | This command exports a collection of subscriptions to an XML file on disk. |
| Get-RsFolderContent | This command lists all catalog items under a folder. |
| Get-RsDataSource | This command lists information about the data source located at the specified path. |
| Get-RsDeploymentConfig | This command retrieves a list of deployment configurations from a Reporting Services project file. |
| Get-RsItemReference | This command gets the item references of a report or a dataset. |
| Get-RsItemDataSource | This command fetches embedded data sources associated with a report. |
| Get-RsCatalogItemRole | This command retrieves access to catalog items for users or groups. |
| Get-RsRestCacheRefreshPlan | This function fetches a CacheRefreshPlan from a Power BI report. |
| Get-RsRestCacheRefreshPlanHistory | This function fetches the history of CacheRefreshPlan(s) from a Power BI report. |
| Get-RsRestDataSource | This function fetches the a datasource item from a folder. |
| Get-RsRestFolderContent | This function fetches data sources related to a catalog item from the Report Server. |
| Get-RsRestItem | This function fetches a catalog item from the Report Server using the REST API. |
| Get-RsRestItemAccessPolicy | This function retrieves access policies to SQL Server Reporting Services Instance or Power BI Report Server Instance from users/groups. |
| Get-RsRestItemDataModelParameters | This function fetches the Data Model Parameters related to a Catalog Item report from the Report Server. This is currently only applicable to Power BI Reports and only from ReportServer October/2020 or higher. |
| Get-RsRestItemDataSource | This command fetches embedded data sources associated with a Paginated report or a Power BI report using the REST Endpoint. |
| Get-RsSubscription | This command retrieves information about subscriptions for a report. |
| Grant-RsRestItemAccessPolicy | This function grants access policies on the SQL Server Reporting Services Instance or Power BI Report Server Instance to the specified user/group, using the REST Endpoint. |
| Grant-RsSystemRole | This command grants access to SQL Server Reporting Services to users or groups. Alias: Grant-AccessToRs |
| Grant-RsCatalogItemRole | This script grants access to catalog items to users or groups. Alias: Grant-AccessOnCatalogItem |
| Import-RsSubscriptionXml | This command imports a collection of subscriptions from an XML file on disk, typically created via Export-RsSubscriptionXml. |
| Initialize-Rs | This command initializes Report Server post-installation. The database MUST be configured and URLs MUST be reserved prior to running this command. |
| New-RsConfigurationSettingObject | This command creates a new RSConfigurationSettingObject which is used to interact with the WMI Provider. |
| New-RsDataSource | This command creates/overwrites the data source to the specified path. |
| New-RsFolder | This command creates a new folder in the specified path. |
| New-RsRestCacheRefreshPlan | This function creates a new CacheRefreshPlan for the specified Power BI Report. |
| New-RsRestCredentialsByUserObject | This command creates a CredentialsByUser object to be used by Set-RsRestItemDataSource command. |
| New-RsRestCredentialsInServerObject | This command creates a CredentialsInServer object to be used by Set-RsRestItemDataSource command. |
| New-RsRestFolder | This command creates a new folder in the specified path using the REST Endpoint. |
| New-RsRestSession | This command creates a session object to be specified for all subsequent calls to the REST Endpoint. |
| New-RsSubscription | This command adds a new subscription to an existing report. |
| New-RsScheduleXml | This command creates an XML string definition of a subscription schedule. For use with the -Schedule parameter or New-RsSubscription. |
| New-RsWebServiceProxy | This command creates a new Web Service Proxy which is used to interact with the SOAP Endpoint. |
| Out-RsCatalogItem | This command downloads a catalog item. |
| Out-RsFolderContent | This command downloads all catalog items in a folder. |
| Out-RsRestFolderContent | This command downloads all catalog items under a folder using the REST Endpoint. |
| Out-RsRestCatalogItem | This command downloads a catalog item using the REST Endpoint. |
| Publish-RsProject | This command deploys a Reporting Services project to a Power BI Report Server. |
| Register-PowerBI | This command registers Power BI information with SQL Server Reporting Services. Alias: Register-RSPowerBI |
| Remove-RsCatalogItem | This command removes the catalog item located at the specified path. |
| Remove-RsRestCatalogItem | This command removes catalog item located at the specified path using the REST Endpoint. |
| Remove-RsRestFolder | This command removes folder located at the specified path using the REST Endpoint. |
| Remove-RSSubscription | This command removes a subscription associated with a report. |
| Restore-RsEncryptionKey | This command restores the encryption key to the SQL Server Reporting Services. |
| Revoke-RsCatalogItemAccess | This command revokes access to a catalog item from users or groups. Alias: Revoke-AccessOnCatalogItem |
| Revoke-RsRestItemAccessPolicy | This function revokes access to catalog items from users/groups, using the REST Endpoint. |
| Revoke-RsSystemAccess | This command revokes access on SQL Server Reporting Services from users or groups. Alias: Revoke-AccessToRs |
| Set-RsDatabase | This command configures the database used by SQL Server Reporting Services. |
| Set-RsDatabaseCredentials | This command configures the credentials to use when connecting to the database used by SQL Server Reporting Services. |
| Set-RsDataSet | This command links a report to a dataset. Alias: Set-RsDataSetReference |
| Set-RsDataSource | This command updates information associated to a data source. Alias: Set-RsDataSourceReference |
| Set-RsDataSourcePassword | This command sets the password associated with a data source. |
| Set-RsEmailSettings | This command configures the SQL Server Reporting Services email settings to use basic authentication. Alias: Set-RsEmailSettingsAsBasicAuth, Set-RsEmailSettingsAsNoAuth, Set-RsEmailSettingsAsNTLMAuth |
| Set-RsItemDataSource | This command updates embedded data sources associated with a report. |
| Set-RsDataSourceReference | This command overrides the reference of a report or dataset to a shared data source. |
| Set-RsRestItemDataModelParameters | This function updates data sources related to a catalog item from the Report Server. |
| Set-RsRestItemDataSource | This command updates embedded data sources associated with a Paginated report or a Power BI Report using the REST endpoint. |
| Set-RsSharedDataSource | This command links a report or a dataset to a data source. |
| Set-RsUrlReservation | This command configures the SQL Server Reporting Services URLs. |
| Set-PbiRsUrlReservation | This command configures the Power BI Report Server URLs. |
| Set-RsSubscription | This command updates existing subscriptions piped from Get-RsSubscription. |
| Start-RsRestCacheRefreshPlan | This function fetches the CacheRefreshPlan of a report from the Report Server and refreshes them using the REST API. Alternatively, when a report has multiple CacheRefreshPlans you can specify which CacheRefreshPlan to refresh by passing the Id of the CacheRefreshPlan to the -Id parameter. |
| Test-RsRestItemDataSource | This function fetches the DataSources from a Paginated or Power BI report and tests them to see if the connection can be made. |
| Write-RsCatalogItem | This command uploads a report, a dataset, or a data source using the SOAP Endpoint. |
| Write-RsFolderContent | This uploads all reports, datasets, and data sources in a folder. |
| Write-RsRestCatalogItem | This command uploads a report, a dataset, or a mobile report using the REST Endpoint. |
| Write-RsRestFolderContent | This uploads all reports, datasets, data sources, mobile reports, and Power BI reports in a folder using the REST Endpoint. |
Some of the commands listed above allow you to optionally specify the version of your SQL Server Reporting Services instance. The following is a list of versions associated with each SQL Server Reporting Services release.
| SQL Server Release | Version |
|---|---|
| SQL Server 2012 | 11 |
| SQL Server 2014 | 12 |
| SQL Server 2016 | 13 |
| SQL Server 2017 | 14 |
| SQL Server 2019 | 15 |
| SQL Server 2022 | 16 |
| Power BI Report Server | 15 |
The motivation behind this project was to help users perform SQL Server Reporting Services operations via the command line.
Set-RsDatabase and Set-RsDatabaseCredentials use two separate SQL connections:
| Parameters | Connection affected |
|---|---|
Encrypt, TrustServerCertificate, HostNameInCertificate |
The setup connection used by Invoke-Sqlcmd to create the database or grant access. These parameters require SQLServer module version 22 or later. |
DatabaseEncryptMode, DatabaseMultiSubnetFailover, DatabaseTrustServerCertificate |
The report server runtime connection to its catalog database, configured through WMI. These parameters do not require SQLServer module version 22. |
For example, configure runtime encryption, certificate trust, and multi-subnet failover independently of setup:
Set-RsDatabase -DatabaseServerName SqlListener -Name ReportServer `
-IsExistingDatabase -DatabaseCredentialType ServiceAccount `
-Encrypt Mandatory -TrustServerCertificate `
-DatabaseEncryptMode Mandatory -DatabaseMultiSubnetFailover `
-DatabaseTrustServerCertificate $trueDatabaseEncryptMode accepts Optional, Mandatory, Strict, True, or False; True equals Mandatory and False equals Optional. The connected WMI provider must expose Encrypt; Strict also requires the EncryptMode input. Optional and Mandatory map to the older boolean Encrypt input when EncryptMode is unavailable. An unsupported runtime option causes an error before any setup SQL runs.
DatabaseMultiSubnetFailover requires the WMI MultiSubnetFailover input. Pass -DatabaseMultiSubnetFailover:$false to disable it. Omitting it leaves the stored failover setting unchanged. Changing failover alone preserves the current runtime encryption mode. Omitting all runtime option parameters preserves the stored runtime encryption, failover and certificate-trust settings; it does not add new defaults. Providers without the WMI Encrypt input keep the legacy five-argument call.
DatabaseTrustServerCertificate accepts $true or $false: $true writes TrustServerCertificate=True for the report server runtime connection, and $false clears it. Omit the parameter to preserve the stored value. This option requires a WMI provider that exposes the TrustServerCertificate input; the cmdlets fail before running setup SQL when the provider does not support it. When DatabaseEncryptMode is Strict, the SQL client ignores certificate trust.
Server-build requirement: Runtime certificate trust requires a report server build whose SetDatabaseConnection WMI method exposes the new optional Boolean TrustServerCertificate input. Updating this PowerShell module alone does not add that server API. Older providers reject an explicit $true or $false; omission continues to work without that input.
Security: Enabling runtime certificate trust bypasses SQL Server certificate validation except with Strict encryption. Prefer a valid, trusted certificate matching the SQL Server or listener name; enable trust only when you accept that validation bypass. No new parameter enables certificate trust by default.
Setup certificate trust: -TrustServerCertificate remains the separate Invoke-Sqlcmd setup connection switch. It does not set or clear runtime certificate trust. Use -DatabaseTrustServerCertificate for the report server catalog connection.
The WMI provider also supports SetDatabaseLogonTimeout and SetDatabaseQueryTimeout. These separate runtime settings are not exposed by these cmdlets; their existing QueryTimeout parameter controls setup SQL execution only.
All of the APIs used by this project are publicly available. There are 2 types of APIs used in this repository: SOAP and WMI. You can find more details about the SOAP API at https://msdn.microsoft.com/en-us/library/ms154052.aspx and the WMI API at https://msdn.microsoft.com/en-us/library/ms152836.aspx. In general, you will use SOAP API for operations you would perform using Report Server and Web Portal whereas you will use WMI API for operations you would perform using Reporting Services Configuration Manager.
To verify the versions installed
Get-Module -ListAvailable -Name ReportingServicesToolsAfter you clone the repo you can make local changes and install them in your local machine with
Remove-Module ReportingServicesTools
Import-Module .\ReportingServicesTools.psd1For debugging you can set the verbose logging with $VerbosePreference = "continue"
For running tests locally you need a local default instance of SQL Server Reporting Services and Pester
To install Pester execute
Install-Module -Name Pester -RequiredVersion 4.10.1To execute the tests run (this will execute the CatalogItems test only which doesn't change the local Reporting Services Installation)
.\Test.ps1The focused maintenance regression tests use mocks and temporary fixtures; they do not download an installer or contact SQL Server or a report server:
Import-Module Pester -RequiredVersion 4.10.1
Invoke-Pester -Script .\Tests\Unit -EnableExitThe database connection option unit tests use mocks and do not require SQL Server or a report server:
Import-Module Pester -RequiredVersion 4.10.1
Invoke-Pester -Script .\Tests\Unit\DatabaseConnectionOptions.Tests.ps1Workaround for newer versions of PowerShell (version 7.0+)
Import-Module ReportingServicesTools -UseWindowsPowerShellIf you have any scripts you would like to share, we request you to please format your scripts according to the guidelines created by the team behind the DSC Resource Kit. (https://github.com/PowerShell/DscResources/blob/master/StyleGuidelines.md) and the PowerShell verbs (https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands)
For contributions please provide the minimum possible increment per Pull Request so it can be reviewed and merged quickly.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.