en/SqlServer-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-SqlNotebook</command:name> <command:verb>Invoke</command:verb> <command:noun>SqlNotebook</command:noun> <maml:description> <maml:para>Executes a SQL Notebook file (.ipynb) and outputs the materialized notebook.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The Invoke-SqlNotebook cmdlet executes a SQL Notebook file (.ipynb) and outputs the materialized notebook.</maml:para> <maml:para>The Notebook will be executed on the ServerInstance and Database provided.</maml:para> <maml:para>When the cmdlet is run, the resulting Notebook file will be in the location the user defines or in the same directory of the input notebook file.</maml:para> <maml:para>The cmdlet outfile may be omitted: if that's the case, it will be created with the input file name and the _out appended to the file.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-SqlNotebook</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>ConnectionString</maml:name> <maml:Description> <maml:para>Specifies a connection string to connect to the server.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:Description> <maml:para>By default, when the cmdlet writes the materialized notebook to a file, a check is performed to prevent the user from accidentally overwriting an existing file. Use `-Force` to bypass this check and allow the cmdlet to overwrite the existing file.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputFile</maml:name> <maml:Description> <maml:para>Specifies a Notebook File (.ipynb) that will be executed through the cmdlet.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:Description> <maml:para>Specifies the Notebook as a Json string that will be used as the input notebook.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>OutputFile</maml:name> <maml:Description> <maml:para>Specifies the desired output Notebook file for which the executed Notebook will be saved.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-SqlNotebook</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:Description> <maml:para>The PSCredential object whose Username and Password fields will be used to connect to the SQL instance.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Database</maml:name> <maml:Description> <maml:para>This cmdlet connects to this database in the instance that is specified in the ServerInstance parameter.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:Description> <maml:para>By default, when the cmdlet writes the materialized notebook to a file, a check is performed to prevent the user from accidentally overwriting an existing file. Use `-Force` to bypass this check and allow the cmdlet to overwrite the existing file.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputFile</maml:name> <maml:Description> <maml:para>Specifies a Notebook File (.ipynb) that will be executed through the cmdlet.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:Description> <maml:para>Specifies the Notebook as a Json string that will be used as the input notebook.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>OutputFile</maml:name> <maml:Description> <maml:para>Specifies the desired output Notebook file for which the executed Notebook will be saved.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Password</maml:name> <maml:Description> <maml:para>Specifies the password for the SQL Server Authentication login ID that was specified in the Username parameter.</maml:para> <maml:para>Passwords are case-sensitive. When possible, use Windows Authentication, or consider using the -Credential parameter instead.</maml:para> <maml:para>If you specify the Password parameter followed by your password, the password is visible to anyone who can see your monitor.</maml:para> <maml:para>If you code Password followed by your password in a .ps1 script, anyone reading the script file will see your password.</maml:para> <maml:para>Assign the appropriate NTFS permissions to the file to prevent other users from being able to read the file.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>ServerInstance</maml:name> <maml:Description> <maml:para>Specifies a character string or SQL Server Management Objects (SMO) object that specifies the name of an instance of the Database Engine.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Username</maml:name> <maml:Description> <maml:para>Specifies the login ID for making a SQL Server Authentication connection to an instance of the Database Engine.</maml:para> <maml:para>The password must be specified through the Password parameter.</maml:para> <maml:para>If Username and Password are not specified, this cmdlet attempts a Windows Authentication connection using the Windows account running the Windows PowerShell session. When possible, use Windows Authentication.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-SqlNotebook</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:Description> <maml:para>By default, when the cmdlet writes the materialized notebook to a file, a check is performed to prevent the user from accidentally overwriting an existing file. Use `-Force` to bypass this check and allow the cmdlet to overwrite the existing file.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputFile</maml:name> <maml:Description> <maml:para>Specifies a Notebook File (.ipynb) that will be executed through the cmdlet.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>OutputFile</maml:name> <maml:Description> <maml:para>Specifies the desired output Notebook file for which the executed Notebook will be saved.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-SqlNotebook</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:Description> <maml:para>By default, when the cmdlet writes the materialized notebook to a file, a check is performed to prevent the user from accidentally overwriting an existing file. Use `-Force` to bypass this check and allow the cmdlet to overwrite the existing file.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:Description> <maml:para>Specifies the Notebook as a Json string that will be used as the input notebook.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>OutputFile</maml:name> <maml:Description> <maml:para>Specifies the desired output Notebook file for which the executed Notebook will be saved.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>ConnectionString</maml:name> <maml:Description> <maml:para>Specifies a connection string to connect to the server.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:Description> <maml:para>The PSCredential object whose Username and Password fields will be used to connect to the SQL instance.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Database</maml:name> <maml:Description> <maml:para>This cmdlet connects to this database in the instance that is specified in the ServerInstance parameter.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:Description> <maml:para>By default, when the cmdlet writes the materialized notebook to a file, a check is performed to prevent the user from accidentally overwriting an existing file. Use `-Force` to bypass this check and allow the cmdlet to overwrite the existing file.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputFile</maml:name> <maml:Description> <maml:para>Specifies a Notebook File (.ipynb) that will be executed through the cmdlet.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:Description> <maml:para>Specifies the Notebook as a Json string that will be used as the input notebook.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>OutputFile</maml:name> <maml:Description> <maml:para>Specifies the desired output Notebook file for which the executed Notebook will be saved.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Password</maml:name> <maml:Description> <maml:para>Specifies the password for the SQL Server Authentication login ID that was specified in the Username parameter.</maml:para> <maml:para>Passwords are case-sensitive. When possible, use Windows Authentication, or consider using the -Credential parameter instead.</maml:para> <maml:para>If you specify the Password parameter followed by your password, the password is visible to anyone who can see your monitor.</maml:para> <maml:para>If you code Password followed by your password in a .ps1 script, anyone reading the script file will see your password.</maml:para> <maml:para>Assign the appropriate NTFS permissions to the file to prevent other users from being able to read the file.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>ServerInstance</maml:name> <maml:Description> <maml:para>Specifies a character string or SQL Server Management Objects (SMO) object that specifies the name of an instance of the Database Engine.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Username</maml:name> <maml:Description> <maml:para>Specifies the login ID for making a SQL Server Authentication connection to an instance of the Database Engine.</maml:para> <maml:para>The password must be specified through the Password parameter.</maml:para> <maml:para>If Username and Password are not specified, this cmdlet attempts a Windows Authentication connection using the Windows account running the Windows PowerShell session. When possible, use Windows Authentication.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSCredential</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>A good way to visualize a materialized Notebook is to use Azure Data Studio.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Execute a Notebook against the local server (default instance)</maml:title> <dev:code>PS C:\> Invoke-SqlNotebook -ServerInstance localhost -Database TestNotebook -InputFile C:\notebook.ipynb Directory: C:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 8/1/2019 1:00 PM 4656 notebook_out.ipynb</dev:code> <dev:remarks> <maml:para>This command runs the notebook against the default instance of SQL Server running on the the machine where the cmdlet is executed from. By default, since no -OutputFile was passed in, the materialized notebook is saved on disk with the same name as the InputFile with a _out as a suffix to the filename (notebook.ipynb -> notebook_out.ipynb)</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Execute Notebook on the local server (defaut instance) and saves the materialized Notebook to a specified file</maml:title> <dev:code>PS C:\> Invoke-SqlNotebook -ServerInstance localhost -Database TestNotebook -InputFile C:\notebook.ipynb -OutputFile C:\new_notebook.ipynb Directory: C:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 8/1/2019 1:00 PM 44656 new_notebook.ipynb</dev:code> <dev:remarks> <maml:para>This command runs the notebook against the default instance of SQL Server running on the the machine where the cmdlet is executed from. The executed notebook is then saved to the file specified with the -OutputFile parameter.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title> Example 3: Execute Notebook using -ConnectionString parameter </maml:title> <dev:code>PS C:\> Invoke-Sqlnotebook -ConnectionString 'Server=Localhost;Database=TestNotebook;Trusted_Connection=True;' -InputFile C:\notebook.ipynb Directory: C:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 8/1/2019 1:00 PM 44656 notebook_out.ipynb</dev:code> <dev:remarks> <maml:para>This is the same as Example 1, only that the connection to the server is specified via the -ConnectionString parameter.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-- Example 4: Execute Notebook Against All Registered Servers --</maml:title> <dev:code>dir 'SQLSERVER:\SQLRegistration\Database Engine Server Group' | WHERE { $_.Mode -ne 'd'} | foreach { $datetime = Get-Date -Format yyyyMMddhhmm; Get-SqlInstance -ServerInstance $_.Name | foreach { Invoke-SqlNotebook -ServerInstance $_.Name -Database master -InputFile '$home\Documents\SQL Server Management Studio\BPCheck.ipynb' ` -OutputFile "BPCheck_output_$($_.NetName)_$($datetime).ipynb"; } }</dev:code> <dev:remarks> <maml:para>Use Registered Servers or Central Management Server to run Invoke-SqlNotebook against multiple servers. In this example, the `NetName` property of the SQL Server instance will be included in the name of the output file; the materialized notebook is going to be time-stamped with year-month-day-hour-minute.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 5: Execute Notebook, Open Results in Azure Data Studio</maml:title> <dev:code>Invoke-SqlNotebook -ServerInstance ServerA -Database master -InputFile "$home\Documents\SQL Server Management Studio\BPCheck.ipynb" | Open-EditorFile</dev:code> <dev:remarks> <maml:para>Note: The `Open-EditorFile` command is only available in the PowerShell Integrated Console.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>SQL Notebooks in Azure Data Studio</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>PowerShell extension</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SQLServer_Cmdlets</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |