en-US/PSql.dll-help.xml
|
<?xml version="1.0" encoding="utf-8" ?> <helpItems schema="maml" xmlns="http://msh" 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"> <!-- Copyright 2021 Jeffrey Sharp Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Documentation: https://docs.microsoft.com/en-us/powershell/developer/help/how-to-create-the-cmdlet-help-file --> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <!-- Connect-Sql --> <command:command> <command:details> <command:name>Connect-Sql</command:name> <command:verb>Connect</command:verb> <command:noun>Sql</command:noun> <maml:description> <maml:para>Connects to SQL Server or Azure SQL Database.</maml:para> </maml:description> </command:details> <maml:description> <maml:para> The Connect-Sql cmdlet opens a new connection to the specifed SQL Server instance or Azure SQL Database resource. The cmdlet outputs the open connection. </maml:para> <maml:para> The connection remains open until explicitly closed. Use the Disconnect-Sql cmdlet to close connections. </maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Connect-Sql</maml:name> <command:parameter required="false" position="0" pipelineInput="True (ByValue)" globbing="false"> <maml:name>Context</maml:name> <command:parameterValue required="true">PSql.SqlContext</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>DatabaseName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" position="0" pipelineInput="True (ByValue)" globbing="false" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>An object specifying how to connect to the database. Obtain via the New-SqlContext cmdlet.</maml:para> </maml:description> <command:parameterValue required="true">PSql.SqlContext</command:parameterValue> <dev:type> <maml:name>PSql.SqlContext</maml:name> </dev:type> <dev:defaultValue>Default SQL Server instance on the local machine</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="DatabaseName"> <maml:name>DatabaseName</maml:name> <maml:description> <maml:para>The name of the database to which to connect. This parameter overrides any database specified via -Context and any default database for the credential.</maml:para> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSql.SqlContext</maml:name> </dev:type> <maml:description> <maml:para>An object specifying how to connect to the database. Obtain via the New-SqlContext cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.Data.SqlClient.SqlConnection</maml:name> </dev:type> <maml:description> <maml:para>A new, open connection to the specifed SQL Server instance or Azure SQL Database resource.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>PSql:</maml:linkText> <maml:uri>https://github.com/sharpjs/PSql</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <!-- Disconnect-Sql --> <command:command> <command:details> <command:name>Disconnect-Sql</command:name> <command:verb>Disconnect</command:verb> <command:noun>Sql</command:noun> <maml:description> <maml:para>Disconnects from SQL Server or Azure SQL Database.</maml:para> </maml:description> </command:details> <maml:description> <maml:para> The Disconnect-Sql cmdlet closes the specified connections to SQL Server instances and Azure SQL Database resources. </maml:para> <maml:para> Use this cmdlet to close connections opened by the Connect-Sql cmdlet. </maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Disconnect-Sql</maml:name> <command:parameter required="false" position="0" pipelineInput="True (ByValue, FromRemainingArguments)" globbing="false"> <maml:name>Connection</maml:name> <command:parameterValue required="true">Microsoft.Data.SqlClient.SqlConnection[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" position="0" pipelineInput="True (ByValue, FromRemainingArguments)" globbing="false" aliases="none"> <maml:name>Connection</maml:name> <maml:description> <maml:para>The connections to close.</maml:para> </maml:description> <command:parameterValue required="true">Microsoft.Data.SqlClient.SqlConnection[]</command:parameterValue> <dev:type> <maml:name>Microsoft.Data.SqlClient.SqlConnection[]</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>Microsoft.Data.SqlClient.SqlConnection[]</maml:name> </dev:type> <maml:description> <maml:para>The connections to close.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>PSql:</maml:linkText> <maml:uri>https://github.com/sharpjs/PSql</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <!-- Expand-SqlCmdDirectives --> <command:command> <command:details> <command:name>Expand-SqlCmdDirectives</command:name> <command:verb>Expand</command:verb> <command:noun>SqlCmdDirectives</command:noun> <maml:description> <maml:para>Performs limited SQLCMD-style preprocessing.</maml:para> </maml:description> </command:details> <maml:description> <maml:para> The Expand-SqlCmdDirectives cmdlet supports a limited subset of SQLCMD preprocessing features: </maml:para> <maml:list> <maml:listItem> <maml:para>GO batch separator</maml:para> </maml:listItem> <maml:listItem> <maml:para>$() sqlcmd variable expansion</maml:para> </maml:listItem> <maml:listItem> <maml:para>:setvar set a sqlcmd variable</maml:para> </maml:listItem> <maml:listItem> <maml:para>:r include a file</maml:para> </maml:listItem> </maml:list> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Expand-SqlCmdDirectives</maml:name> <command:parameter required="true" position="0" aliases="none" pipelineInput="True (ByValue)" globbing="false"> <maml:name>Sql</maml:name> <command:parameterValue required="true">string[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="1" pipelineInput="False" globbing="false" > <maml:name>Define</maml:name> <command:parameterValue required="true">hashtable</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" position="0" pipelineInput="True (ByValue)" globbing="false" aliases="none"> <maml:name>Sql</maml:name> <maml:description> <maml:para>The SQL scripts(s) to run.</maml:para> </maml:description> <command:parameterValue required="true">string[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Define</maml:name> <maml:description> <maml:para>SQLCMD preprocessor variables to define.</maml:para> </maml:description> <command:parameterValue required="true">hashtable</command:parameterValue> <dev:type> <maml:name>System.Collections.Hashtable[]</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>SQL scripts(s) to preprocess.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri/> <maml:description/> </dev:type> <maml:description> <maml:para>Preprocessed SQL batches.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>PSql:</maml:linkText> <maml:uri>https://github.com/sharpjs/PSql</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>sqlcmd Utility:</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/sql/tools/sqlcmd-utility</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <!-- Invoke-Sql --> <command:command> <command:details> <command:name>Invoke-Sql</command:name> <command:verb>Invoke</command:verb> <command:noun>Sql</command:noun> <maml:description> <maml:para>Runs SQL scripts on SQL Server or Azure SQL Database.</maml:para> </maml:description> </command:details> <maml:description> <maml:para> The Invoke-Sql cmdlet runs SQL scripts on SQL Server or Azure SQL Database and outputs each result row as a PowerShell custom object. Additionally, the Invoke-Sql cmdlet receives messages sent by the server and writes them to the information or warning streams, depending on severity. </maml:para> <maml:para> Invoke-Sql supports a limited subset of SQLCMD preprocessing features: </maml:para> <maml:list> <maml:listItem> <maml:para>GO batch separator</maml:para> </maml:listItem> <maml:listItem> <maml:para>$() sqlcmd variable expansion</maml:para> </maml:listItem> <maml:listItem> <maml:para>:setvar set a sqlcmd variable</maml:para> </maml:listItem> <maml:listItem> <maml:para>:r include a file</maml:para> </maml:listItem> </maml:list> <maml:para><!-- HACK: Get-Help does not put a blank line after the <list> --></maml:para> <maml:para> Use the -NoPreprocessing switch to disable preprocessing. </maml:para> <maml:para> By default, Invoke-Sql executes each SQL batch using an error-handling wrapper that prints the offending SQL batch if an error occurs, greatly improving the diagnostic experience. However, the wrapper conflicts with a few specific scenarios: </maml:para> <maml:list> <maml:listItem> <maml:para> Beginning a transaction without committing it in the same batch: this causes an error when using the wrapper. </maml:para> </maml:listItem> <maml:listItem> <maml:para> Committing a transaction that was not started in the same batch: this causes an error when using the wrapper. </maml:para> </maml:listItem> <maml:listItem> <maml:para> Creating a temporary table: the temporary table vanishes at the end of the batch when using the wrapper. </maml:para> </maml:listItem> </maml:list> <maml:para><!-- HACK: Get-Help does not put a blank line after the <list> --></maml:para> <maml:para> To support these scenarios, disable the error-handling wrapper when required. To disable the wrapper for a single SQL batch, include the line '--# NOWRAP' (without the quotes) anywhere in the batch. To disable the wrapper for all batches, use the -NoErrorHandling switch. </maml:para> <maml:para> After execution of each batch, if an error occurred, Invoke-Sql writes an object to the error stream. </maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-Sql</maml:name> <command:parameter required="true" position="0" aliases="none" pipelineInput="True (ByValue)" globbing="false"> <maml:name>Sql</maml:name> <command:parameterValue required="true">string[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="1" pipelineInput="False" globbing="false" > <maml:name>Define</maml:name> <command:parameterValue required="true">hashtable</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Context</maml:name> <command:parameterValue required="true">PSql.SqlContext</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>NoPreprocessing</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>NoErrorHandling</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>UseSqlTypes</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Timeout</maml:name> <command:parameterValue required="true">TimeSpan</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-Sql</maml:name> <command:parameter required="true" position="0" aliases="none" pipelineInput="True (ByValue)" globbing="false"> <maml:name>Sql</maml:name> <command:parameterValue required="true">string[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="1" pipelineInput="False" globbing="false" > <maml:name>Define</maml:name> <command:parameterValue required="true">hashtable</command:parameterValue> </command:parameter> <command:parameter required="true" position="named" pipelineInput="False" globbing="false"> <maml:name>Connection</maml:name> <command:parameterValue required="true">Microsoft.Data.SqlClient.SqlConnection</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>NoPreprocessing</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>NoErrorHandling</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>UseSqlTypes</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Timeout</maml:name> <command:parameterValue required="true">TimeSpan</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" position="0" pipelineInput="True (ByValue)" globbing="false" aliases="none"> <maml:name>Sql</maml:name> <maml:description> <maml:para>The SQL scripts(s) to run.</maml:para> </maml:description> <command:parameterValue required="true">string[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Define</maml:name> <maml:description> <maml:para>SQLCMD preprocessor variables to define.</maml:para> </maml:description> <command:parameterValue required="true">hashtable</command:parameterValue> <dev:type> <maml:name>System.Collections.Hashtable[]</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>An object specifying how to connect to the database. Obtain via the New-SqlContext cmdlet.</maml:para> </maml:description> <command:parameterValue required="true">PSql.SqlContext</command:parameterValue> <dev:type> <maml:name>PSql.SqlContext</maml:name> </dev:type> <dev:defaultValue>Default SQL Server instance on the local machine</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Connection</maml:name> <maml:description> <maml:para>The SQL connection on which to execute commands.</maml:para> </maml:description> <command:parameterValue required="true">Microsoft.Data.SqlClient.SqlConnection</command:parameterValue> <dev:type> <maml:name>Microsoft.Data.SqlClient.SqlConnection</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="NoSqlCmdMode"> <maml:name>NoPreprocessing</maml:name> <maml:description> <maml:para>Disables SQLCMD preprocessing support.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>NoErrorHandling</maml:name> <maml:description> <maml:para>Disables the error-handling wrapper.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Timeout</maml:name> <maml:description> <maml:para>The maximum duration to wait for each SQL batch to complete. If a batch exceeds this duration, the cmdlet ceases waiting on the batch and writes an error to the error stream. The batch might continue to execute on the database server. </maml:para> </maml:description> <command:parameterValue required="true">TimeSpan</command:parameterValue> <dev:type> <maml:name>System.TimeSpan</maml:name> </dev:type> <dev:defaultValue>00:00:30</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri/> <maml:description/> </dev:type> <maml:description> <maml:para>SQL scripts(s) to run.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSCustomObject[]</maml:name> <maml:uri/> <maml:description/> </dev:type> <maml:description> <maml:para>Result rows of the invoked scripts. The cmdlet converts each row to a PSCustomObject by mapping columns to properties.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>PSql:</maml:linkText> <maml:uri>https://github.com/sharpjs/PSql</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>sqlcmd Utility:</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/sql/tools/sqlcmd-utility</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <!-- New-SqlContext --> <command:command> <command:details> <command:name>New-SqlContext</command:name> <command:verb>New</command:verb> <command:noun>SqlContext</command:noun> <maml:description> <maml:para>Creates an object specifying how to connect to SQL Server or Azure SQL Database.</maml:para> </maml:description> </command:details> <maml:description> <maml:para> The PSql New-SqlContext cmdlet accepts parameters specifying how to connect to a SQL Server, Azure SQL Database, or compatible product, and outputs a context object containing the supplied values. Pass the context object to other PSql cmdlets via their -Context parameter to work with the specified database. </maml:para> </maml:description> <command:syntax> <!-- Generic parameter set --> <command:syntaxItem> <maml:name>New-SqlContext</maml:name> <command:parameter required="false" position="0" pipelineInput="False" globbing="false"> <maml:name>ServerName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="1" pipelineInput="False" globbing="false"> <maml:name>DatabaseName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Credential</maml:name> <command:parameterValue required="true">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>EncryptionMode</maml:name> <command:parameterValue required="true">{ Default | None | Unverified | Full }</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ServerPort</maml:name> <command:parameterValue required="true">ushort</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>InstanceName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ReadOnlyIntent</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ClientName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ApplicationName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ConnectTimeout</maml:name> <command:parameterValue required="true">TimeSpan</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ExposeCredentialInConnectionString</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Pooling</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>MultipleActiveResultSets</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Frozen</maml:name> </command:parameter> </command:syntaxItem> <!-- Azure parameter set --> <command:syntaxItem> <maml:name>New-SqlContext</maml:name> <command:parameter required="true" position="named" pipelineInput="False" globbing="false"> <maml:name>Azure</maml:name> </command:parameter> <command:parameter required="false" position="0" pipelineInput="False" globbing="false"> <maml:name>ResourceGroupName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="1" pipelineInput="False" globbing="false"> <maml:name>ServerResourceName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ServerName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="2" pipelineInput="False" globbing="false"> <maml:name>DatabaseName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>AuthenticationMode</maml:name> <command:parameterValue required="true">{ Default | SqlPassword | AadPassword | AadIntegrated | AadInteractive | AadServicePrincipal | AadDeviceCodeFlow | AadManagedIdentity }</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Credential</maml:name> <command:parameterValue required="true">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ReadOnlyIntent</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ClientName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ApplicationName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ConnectTimeout</maml:name> <command:parameterValue required="true">TimeSpan</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ExposeCredentialInConnectionString</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Pooling</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>MultipleActiveResultSets</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Frozen</maml:name> </command:parameter> </command:syntaxItem> <!-- Clone parameter set --> <command:syntaxItem> <maml:name>New-SqlContext</maml:name> <command:parameter required="true" position="named" pipelineInput="True (ByValue)" globbing="false"> <maml:name>Source</maml:name> <command:parameterValue required="true">PSql.SqlContext</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="True (False)" globbing="false"> <maml:name>ResourceGroupName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ServerResourceName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="0" pipelineInput="False" globbing="false"> <maml:name>ServerName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="1" pipelineInput="False" globbing="false"> <maml:name>DatabaseName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>AuthenticationMode</maml:name> <command:parameterValue required="true">{ Default | SqlPassword | AadPassword | AadIntegrated | AadInteractive | AadServicePrincipal | AadDeviceCodeFlow | AadManagedIdentity }</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Credential</maml:name> <command:parameterValue required="true">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>EncryptionMode</maml:name> <command:parameterValue required="true">{ Default | None | Unverified | Full }</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ServerPort</maml:name> <command:parameterValue required="true">ushort</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>InstanceName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ReadOnlyIntent</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ClientName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ApplicationName</maml:name> <command:parameterValue required="true">string</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ConnectTimeout</maml:name> <command:parameterValue required="true">TimeSpan</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>ExposeCredentialInConnectionString</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Pooling</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>MultipleActiveResultSets</maml:name> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false"> <maml:name>Frozen</maml:name> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Azure</maml:name> <maml:description> <maml:para>Specifies that the context connects to Azure SQL Database.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="True (ByValue)" globbing="false" aliases="none"> <maml:name>Source</maml:name> <maml:description> <maml:para>A context previously created by this cmdlet from which to copy property values into the created context. This parameter accepts pipeline input.</maml:para> </maml:description> <command:parameterValue required="true">PSql.PSqlContext</command:parameterValue> <dev:type> <maml:name>PSql.SqlContext</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="ResourceGroup,ServerResourceGroupName"> <maml:name>ResourceGroupName</maml:name> <maml:description> <maml:para>The name of the Azure resource group containing the database server. Requires the -Azure switch or an Azure -Source context.</maml:para> <maml:para>The context uses this value and -ServerResourceName to discover the DNS name of the database server if -ServerName is not specified.</maml:para> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Resource"> <maml:name>ServerResourceName</maml:name> <maml:description> <maml:para>The Azure resource name of the database server. Requires the -Azure switch or an Azure -Source context.</maml:para> <maml:para>The context uses this value and -ResourceGroupName to discover the DNS name of the database server if -ServerName is not specified.</maml:para> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="0" pipelineInput="False" globbing="false" aliases="Server"> <maml:name>ServerName</maml:name> <maml:description> <maml:para>The DNS name of the database server. The values . and (local) are recognized as aliases for the local machine.</maml:para> <maml:para>If not specified, the default is context-dependent:</maml:para> <maml:list class="bullet"> <maml:listItem> <maml:para>With -Azure switch or an Azure -Source context:</maml:para> <maml:para>The context uses -ResourceGroupName and -ServerResourceName to discover the DNS name of the database server.</maml:para> </maml:listItem> <maml:listItem> <maml:para>Otherwise:</maml:para> <maml:para>The context targets the local machine.</maml:para> </maml:listItem> </maml:list> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None with -Azure; otherwise, the local machine</dev:defaultValue> </command:parameter> <command:parameter required="false" position="1" pipelineInput="False" globbing="false" aliases="Database"> <maml:name>DatabaseName</maml:name> <maml:description> <maml:para>The name of the database.</maml:para> <maml:para>If not specified, connections will attempt to open in the default database of the authenticated user.</maml:para> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None (default database of the authenticated user)</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Auth"> <maml:name>AuthenticationMode</maml:name> <maml:description> <maml:para>The method to use to authenticate with Azure SQL Database. Requires the -Azure switch or an Azure -Source context.</maml:para> </maml:description> <command:parameterValue required="true">PSql.AuthenticationMode</command:parameterValue> <dev:type> <maml:name>PSql.AuthenticationMode</maml:name> </dev:type> <dev:defaultValue>Default</dev:defaultValue> <dev:possibleValues> <dev:possibleValue> <dev:value>Default</dev:value> <maml:description> <maml:para> The default authentication mode. Equivalent to SqlPassword if -Credential is specified, and AadIntegrated otherwise. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>SqlPassword</dev:value> <maml:description> <maml:para> SQL password authentication mode. -Credential is required and should match the name and password stored for a server login or contained database user. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>AadPassword</dev:value> <maml:description> <maml:para> Azure Active Directory password authentication mode. -Credential is required and should match the name and password of an Azure AD principal. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>AadIntegrated</dev:value> <maml:description> <maml:para> Azure Active Directory integrated authentication mode. The identity of the process should be an Azure AD principal. -Credential is not required. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>AadInteractive</dev:value> <maml:description> <maml:para> Azure Active Directory interactive authentication mode, also known as Universal Authentication with MFA. Authentication uses an interactive flow and supports multiple factors. -Credential is not required. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>AadServicePrincipal</dev:value> <maml:description> <maml:para> Azure Active Directory service principal authentication mode. -Credential is required and should match client ID and secret of an Azure AD service principal. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>AadDeviceCodeFlow</dev:value> <maml:description> <maml:para> Azure Active Directory device code flow authentication mode. Use this mode to connect to Azure SQL Database from devices that do not provide a web browser, using another device to perform interactive authentication. -Credential is not required. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>AadManagedIdentity</dev:value> <maml:description> <maml:para> Azure Active Directory managed identity authentication mode. For a user-assigned identity, -Credential is required and should match the object ID of the identity; the password is ignored. For a system-assigned identity, -Credential should be omitted. </maml:para> </maml:description> </dev:possibleValue> </dev:possibleValues> </command:parameter> <command:parameter required="false" position="3" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The credential to use to authenticate with the database server.</maml:para> <maml:para>When the -Azure switch is used, or when the -Source context is an Azure context, the use of the credential depends on the -AuthenticationMode parameter.</maml:para> <maml:para>Otherwise, connections will present the credential for SQL password authentication. If -Credential is not specified, connections will attempt to use integrated authentication.</maml:para> </maml:description> <command:parameterValue required="true">PSCredential</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSCredential</maml:name> </dev:type> <dev:defaultValue>None (mode-dependent with -Azure; otherwise, integrated authentication)</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Encryption"> <maml:name>EncryptionMode</maml:name> <maml:description> <maml:para>The transport encryption to use for connections.</maml:para> <maml:para>Ignored when the -Azure switch is used or when the -Source context is an Azure context. Azure contexts always use the Full encryption mode.</maml:para> </maml:description> <command:parameterValue required="true">PSql.EncryptionMode</command:parameterValue> <dev:type> <maml:name>PSql.EncryptionMode</maml:name> </dev:type> <dev:defaultValue>Default (non-Azure); Full (Azure)</dev:defaultValue> <dev:possibleValues> <dev:possibleValue> <dev:value>Default</dev:value> <maml:description> <maml:para> The default encrption mode. Equivalent to None for connections to the local machine, and Full for all other connections. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>None</dev:value> <maml:description> <maml:para> No connection encryption or server identity check. Data sent over the connection is exposed to other network devices. A malicious device could masquerade as a server. This encryption mode is appropriate for same-machine connections only. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>Unverified</dev:value> <maml:description> <maml:para> Connections are encrypted, but server identities are not verified. A malicious device could masquerade as a server. This encryption mode is appropriate only when the server uses a self-signed certificate. </maml:para> </maml:description> </dev:possibleValue> <dev:possibleValue> <dev:value>Full</dev:value> <maml:description> <maml:para> Connections are encrypted, and server identities are verified. This is the most secure encryption mode. </maml:para> </maml:description> </dev:possibleValue> </dev:possibleValues> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Port"> <maml:name>ServerPort</maml:name> <maml:description> <maml:para>The remote TCP port of the database server.</maml:para> <maml:para>If not specified, the underlying ADO.NET implementation will use a default port, typically 1433.</maml:para> </maml:description> <command:parameterValue required="true">ushort</command:parameterValue> <dev:type> <maml:name>System.UInt16</maml:name> </dev:type> <dev:defaultValue>None (underlying default)</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Instance"> <maml:name>InstanceName</maml:name> <maml:description> <maml:para>The name of the database engine instance.</maml:para> <maml:para>If not specified, connection attempts will target the default instance.</maml:para> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None (default instance)</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="ReadOnly"> <maml:name>ReadOnlyIntent</maml:name> <maml:description> <maml:para>Specifies that the client intends to perform only reads. The server might optimize connections for a read-only workload.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Client"> <maml:name>ClientName</maml:name> <maml:description> <maml:para>The name of the client device.</maml:para> <maml:para>If not specified, the underlying ADO.NET implementation will provide a default value.</maml:para> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None (underlying default)</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Application"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>The name of the client application.</maml:para> <maml:para>If not specified, the underlying ADO.NET implementation will provide a default value.</maml:para> </maml:description> <command:parameterValue required="true">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <dev:defaultValue>None (underlying default)</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Timeout"> <maml:name>ConnectTimeout</maml:name> <maml:description> <maml:para>The duration after which a connection attempt times out.</maml:para> <maml:para>If not specified, the underlying ADO.NET implementation default of 15 seconds is used.</maml:para> </maml:description> <command:parameterValue required="true">TimeSpan</command:parameterValue> <dev:type> <maml:name>System.TimeSpan</maml:name> </dev:type> <dev:defaultValue>None (underlying default of 15 seconds)</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>ExposeCredentialInConnectionString</maml:name> <maml:description> <maml:para>Specifies that the credential used for authentication should be exposed in connections' ConnectionString property. This is a potential security risk, so use only when necessary.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Pooling</maml:name> <maml:description> <maml:para>Specifies that connections may be pooled to reduce setup and teardown time. Pooling is useful when making many connections with identical connection strings.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="Mars"> <maml:name>MultipleActiveResultSets</maml:name> <maml:description> <maml:para>Specifies that connections support execution of multiple batches concurrently, with limitations.</maml:para> <maml:para>For more information, see Multiple Active Result Sets (MARS): https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/sql/multiple-active-result-sets-mars .</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" aliases="none"> <maml:name>Frozen</maml:name> <maml:description> <maml:para>Specifies that the created context should be frozen. A frozen context is immutable; attempting to set a property of a frozen context will cause an exception, leaving the context unchanged.</maml:para> <maml:para>Instead of modifying a frozen context, pass it to this cmdlet in the -Source parameter or as pipeline input. This cmdlet will create a copy of the context and will apply the specified modifications to the copy.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSql.SqlContext</maml:name> </dev:type> <maml:description> <maml:para>An object specifying how to connect to a SQL Server or compatible database.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>PSql:</maml:linkText> <maml:uri>https://github.com/sharpjs/PSql</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> </helpItems> |