Invoke-Sqlcmd

參考

模組:: SQLServer

執行腳本，其中包含 sqlCMD 公用程式所支援的語句 SQL Server。

Syntax

Invoke-Sqlcmd
      [-ServerInstance <PSObject>]
      [-Database <String>]
      [-Encrypt <String>]
      [-EncryptConnection]
      [-Username <String>]
      [-AccessToken <String>]
      [-Password <String>]
      [-Credential <PSCredential>]
      [[-Query] <String>]
      [-QueryTimeout <Int32>]
      [-ConnectionTimeout <Int32>]
      [-ErrorLevel <Int32>]
      [-SeverityLevel <Int32>]
      [-MaxCharLength <Int32>]
      [-MaxBinaryLength <Int32>]
      [-AbortOnError]
      [-DedicatedAdministratorConnection]
      [-DisableVariables]
      [-DisableCommands]
      [-HostName <String>]
      [-ApplicationName <String>]
      [-ApplicationIntent <ApplicationIntent>]
      [-MultiSubnetFailover]
      [-FailoverPartner <String>]
      [-HostNameInCertificate <String>]
      [-TrustServerCertificate]
      [-NewPassword <String>]
      [-Variable <PSObject>]
      [-InputFile <String>]
      [-OutputSqlErrors <Boolean>]
      [-IncludeSqlUserErrors]
      [-SuppressProviderContextWarning]
      [-IgnoreProviderContext]
      [-OutputAs <OutputType>]
      [-StatisticsVariable <String>]
      [<CommonParameters>]

Invoke-Sqlcmd
      [-AccessToken <String>]
      [[-Query] <String>]
      [-QueryTimeout <Int32>]
      [-ErrorLevel <Int32>]
      [-SeverityLevel <Int32>]
      [-MaxCharLength <Int32>]
      [-MaxBinaryLength <Int32>]
      [-AbortOnError]
      [-DisableVariables]
      [-DisableCommands]
      [-Variable <PSObject>]
      [-InputFile <String>]
      [-OutputSqlErrors <Boolean>]
      [-IncludeSqlUserErrors]
      [-OutputAs <OutputType>]
      -ConnectionString <String>
      [-KeyVaultAccessToken <String>]
      [-ManagedHsmAccessToken <String>]
      [-StatisticsVariable <String>]
      [<CommonParameters>]

Description

Invoke-Sqlcmd Cmdlet 會執行腳本，其中包含 SQL Server SQLCMD 公用程式支援的語言和命令。

支援的命令是 Transact-SQL 語句，以及資料庫引擎所支援的 XQuery 語法子集。

此 Cmdlet 也接受 SQLCMD 原生支援的許多命令，例如 GO 和 QUIT。

此 Cmdlet 也接受 SQLCMD 腳本變數，例如 SQLCMDUSER。根據預設，此 Cmdlet 不會設定 SQLCMD 腳本變數。

此 Cmdlet 不支援使用主要與互動式腳本編輯相關的命令。

不支援的命令包括 :!!、:connect、:error、:out、:ed、:list、:listvar、:reset、:perftrace 和 :serverlist。

執行此 Cmdlet 時，腳本傳回的第一個結果集會顯示為格式化數據表。

如果後續的結果集包含的數據行清單與第一個數據行清單不同，則不會顯示這些結果集。

如果第一個集合之後的後續結果集具有相同的數據行清單，其數據列會附加至格式化數據表，其中包含第一個結果集所傳回的數據列。

您可以藉由指定 Verbose 參數來顯示 SQL Server 訊息輸出，例如 SQL PRINT 語句所產生的輸出。

範例

範例 1：連線到具名實例並執行腳本

Invoke-Sqlcmd -Query "SELECT GETDATE() AS TimeOfQuery" -ServerInstance "MyComputer\MainInstance"

TimeOfQuery
-----------
9/21/2017 2:48:24 PM

此命令會連線到計算機上 SQL Database 引擎的具名實例，並執行基本的 Transact-SQL 腳本。

範例 2：叫用腳本檔案中的命令，並將輸出儲存在文字檔中

Invoke-Sqlcmd -InputFile "C:\ScriptFolder\TestSqlCmd.sql" | Out-File -FilePath "C:\ScriptFolder\TestSqlCmd.rpt"
Output sent to TestSqlCmd.rpt.

此命令會讀取包含 Transact-SQL 語句和 SQLCMD 命令的檔案、執行檔案，並將輸出寫入另一個檔案。

輸出檔案可能包含專屬資訊，因此您應該使用適當的NTFS許可權來保護輸出檔案。

範例 3：叫用腳本，並從字串傳入變數值

$StringArray = "MYVAR1='String1'", "MYVAR2='String2'"
Invoke-Sqlcmd -Query "SELECT `$(MYVAR1) AS Var1, `$(MYVAR2) AS Var2" -Variable $StringArray

Var1     Var2
----     ----
String1  String2

此命令會使用字元字串數位做為 Variable 參數的輸入。

數位會定義多個 SQLCMD 變數。

在 SELECT 語句中識別 SQLCMD 變數的 $ 登入會使用回刻度 (') 字元逸出。

範例 4：叫用腳本，並從 SQL 資料庫引擎傳入變數

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance"
PS SQLSERVER:\SQL\MyComputer\MainInstance> Invoke-Sqlcmd -Query "SELECT SERVERPROPERTY('MachineName') AS ComputerName" -ServerInstance (Get-Item .)

ComputerName
------------
MyComputer

此命令會使用 Set-Location 流覽至 SQL Database Engine 實例的 SQL ServerWindows PowerShell 提供者路徑。

然後它會呼叫 Get-Item，以擷取 SQL Management Object Server 物件，以作為 Invoke-Sqlcmd 的 ServerInstance 參數使用。

範例 5：執行查詢並顯示詳細信息輸出

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance"
Invoke-SqlCmd -Query "PRINT N'abc'" -Verbose
VERBOSE: abc

此命令會使用 Windows PowerShellVerbose 參數傳回 SQL PRINT 命令的訊息輸出。

範例 6：使用位置字串作為輸入叫用命令

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance\Databases\MyDatabase"
PS SQLSERVER:\SQL\MyComputer\MainInstance> Invoke-Sqlcmd "SELECT DB_NAME() AS DatabaseName"
WARNING: Using provider context. Server = MyComputer\MainInstance, Database = MyDatabase.

DatabaseName
------------
MyDatabase

此命令會使用位置字串，將輸入提供給 Query 參數。

它也示範 Invoke-Sqlcmd 如何使用目前的路徑，將資料庫內容設定為 MyDatabase。

範例 7：將數據擷取至 DataSet 物件

$DS = Invoke-Sqlcmd -ServerInstance "MyComputer" -Query "SELECT  ID, Item FROM MyDB.dbo.MyTable" -As DataSet
$DS.Tables[0].Rows | %{ echo "{ $($_['ID']), $($_['Item']) }" }

{ 10, AAA }
{ 20, BBB }
{ 30, CCC }

此命令會使用 As DataSet 參數將數據擷取到 .Net System.Data.DataSet 物件，並將結果儲存在變數 '$DS'。對象可用於進一步處理。

範例 8：取得特定數據行集

$Tables = Invoke-Sqlcmd -ServerInstance "MyComputer" -Query "SELECT  Item, id FROM MyDatabase.dbo.MyTable; SELECT GETDATE() AS T" -As DataTables
$Tables[0].Rows | %{ echo $_.ID }
$Tables[1].Rows | %{ echo $_.T.DayOfWeek }

10
20
30

Monday

第一個命令會使用 As DataTables 參數，將數據擷取到 .Net System.Data.DataTable 物件的集合中。此命令會取得具有不同數據行集的兩個數據表。

每個數據表都可以根據自己的架構個別處理。

範例 9：取得連線的完整控制權

Invoke-Sqlcmd -Query "SELECT COUNT(*) AS Count FROM MyTable" -ConnectionString "Data Source=MYSERVER;Initial Catalog=MyDatabase;Integrated Security=True;ApplicationIntent=ReadOnly"
Count
-----
127432

此命令會使用者 -ConnectionString 參數，以取得此 Cmdlet 所建立之連線的完整控制權，而不是根據命令行上傳遞的參數來建置連接字串 Invoke-Sqlcmd。

這適用於您可能想要使用的較不通用屬性。

範例 10：執行預存程式並擷取 SQL 錯誤

$script_sp_with_errors = @'
CREATE PROCEDURE [dbo].[TestProcedure3]
AS 
BEGIN 
  CREATE TABLE [dbo].[TestTable] (col INT NOT NULL);
  INSERT INTO [dbo].[TestTable] VALUES (NULL); -- will cause an error
END
GO
'@

# Create a test database
Invoke-SqlCmd -ServerInstance MyServer -Query 'CREATE DATABASE TestDB'
# ... adds a stored procedure that has errors in it...
Invoke-SqlCmd -ServerInstance MyServer -Database 'TestDB' -Query $script_sp_with_errors
# ... executes the SP and collected the errors
Invoke-SqlCmd -ServerInstance MyServer -Database 'TestDB' -Query 'EXEC TestProcedure3' -OutputSqlErrors $true

Here's the output:
Invoke-SqlCmd : Cannot insert the value NULL into column 'col', table 'TestDB.dbo.TestTable'; column does not allow nulls. INSERT fails.
The statement has been terminated.
 Msg 515, Level 16, State 2, Procedure TestProcedure3, Line 5.
At line:1 char:1
...

此命令會使用者 -OutputSqlErrors 參數，向使用者報告錯誤。請注意，在此情況下的錯誤訊息會提供額外的資訊，例如SP名稱和發生錯誤的行號。

範例 11：使用存取令牌連接到 Azure SQL 資料庫 (或受控執行個體)

Import-Module SQLServer
Import-Module Az.Accounts -MinimumVersion 2.2.0

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that Service Principal and has granted it access to the database (in this example at least
#       the SELECT permission).

### Obtain the Access Token: this will bring up the login dialog
Connect-AzAccount
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token`
              -query 'select * from Table1'

範例 12：使用服務主體連線至 Azure SQL 資料庫 (或受控執行個體)

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that Service Principal and has granted it access to the database (in this example at least
#       the SELECT permission).

$clientid = "enter application id that corresponds to the Service Principal" # Do not confuse with its display name
$tenantid = "enter the tenant ID of the Service Principal"
$secret = "enter the secret associated with the Service Principal"

$request = Invoke-RestMethod -Method POST `
           -Uri "https://login.microsoftonline.com/$tenantid/oauth2/token"`
           -Body @{ resource="https://database.windows.net/"; grant_type="client_credentials"; client_id=$clientid; client_secret=$secret }`
           -ContentType "application/x-www-form-urlencoded"
$access_token = $request.access_token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token`
              -query 'select * from Table1'

範例 13：使用受控識別連線至 Azure SQL 資料庫 (或受控執行個體)

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that VM Identity you are running on and has granted it access to the database (in this 
#       example at least the SELECT permission).

## Obtain access token from the machine
if (Get-Command -All az -ErrorAction SilentlyContinue -CommandType Application) {
  # Obtain the Access Token from the Azure provider for database resources (using az az cli)
  az login
  $access_token = az account get-access-token --resource https://database.windows.net/ --query accessToken -o tsv
} else {
  # az cli not around: fall back and assume this is a VM in Azure
  $response = Invoke-WebRequest `
    -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fdatabase.windows.net'`
    -Method GET`
    -Headers @{Metadata="true"}
  $access_token = ($response.Content | ConvertFrom-Json).access_token
}

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token`
              -query 'select * from Table1'

此範例與上述範例類似。它只會顯示 AccessToken 參數的彈性。

範例 14：使用 -ApplicationIntent 連線至針對 Read-Only 路由設定的可用性群組

# In the following example:
# - MT_2009250511 is a listener for an AG configured for Read-Only Routing (port 5555)
# - AGDB_2_1 is the DB in the AG
# - VLM00226138 is the primary replica configured to only allow ReadWrite connections 
# - VLM00226137 is the secondary replica
# 
Invoke-Sqlcmd -ServerInstance "MT_2009250511,5555" -Database AGDB_2_1 `
     -HostName "PowershellBox1" -ApplicationName "ReadWrite" -ApplicationIntent ReadWrite `
     -Query "select HOST_NAME() AS HostName, APP_NAME() AS ApplicationIntent, @@SERVERNAME AS ServerName"

Invoke-Sqlcmd -ServerInstance "MT_2009250511,5555" -Database AGDB_2_1 `
     -HostName "PowershellBox2" -ApplicationName "ReadOnly" -ApplicationIntent ReadOnly `
     -Query "select HOST_NAME() AS HostName, APP_NAME() AS ApplicationIntent, @@SERVERNAME AS ServerName"  

# When you run the 2 cmdlets above, the output is going to be something like this:  
#  
# HostName       ApplicationIntent ServerName  
# --------       ----------------- ----------  
# PowershellBox1 ReadWrite         VLM00226138  
#  
# HostName       ApplicationIntent ServerName  
# --------       ----------------- ----------  
# PowershellBox2 ReadOnly          VLM00226137

這會顯示，視參數的值 -ApplicationIntent 而定，聯機會路由傳送至 AG 中的不同伺服器。此外，請觀察和 -HostName 參數的使用-ApplicationName方式，以可視化方式區分這兩個結果：這是可用來追蹤連接及其意圖的常見技術，除了此處說明的 -ApplicationIntent 範例之外。

範例 15：透過 -StatisticsVariable 參數擷取連線統計數據

Import-Module SQLServer
Invoke-Sqlcmd -ServerInstance localhost -StatisticsVariable stats `
              -Query 'CREATE TABLE #Table (ID int); INSERT INTO #Table VALUES(1), (2); INSERT INTO #Table VALUES(3); SELECT * FROM #Table'

Write-Host "Number of rows affected......: $($stats.IduRows)"
Write-Host "Number of insert statements..: $($stats.IduCount)"
Write-Host "Number of select statements..: $($stats.SelectCount)"
Write-Host "Total execution time.........: $($stats.ExecutionTime)ms"

# When you run the code fragment above, is going to be something like this:  
#
# Number of rows affected......: 3
# Number of insert statements..: 2
# Number of select statements..: 1
# Total execution time.........: 5ms

這個範例示範如何使用 -StatisticsVariable 參數來擷取連接、所執行語句，以及執行一些建立臨時表的 T-SQL 時執行時間、插入某些值，最後發出選取以取得所有插入的數據列。

注意：當對多部伺服器執行相同的查詢時， (例如，藉由將伺服器名稱傳送至 Cmdlet) ，就會 StatisticsVariable 擷取統計數據陣列，每個連線各一個。然後，您可以使用來匯總結果，例如 ($stats.IduRows | Measure-Object -Sum).Sum。

如需可用統計數據的詳細資訊，請參閱 SQL Server 提供者統計數據。

範例 16：執行查詢，以解密使用 Always Encrypted 加密的數據行擷取的數據。假設數據行主要金鑰儲存在 Azure 金鑰保存庫的金鑰保存庫中。

# Connect to Azure account.
Import-Module Az.Accounts -MinimumVersion 2.2.0
Connect-AzAccount

# Obtain an access token for key vaults. 
$keyVaultAccessToken = (Get-AzAccessToken -ResourceUrl https://vault.azure.net).Token

# Pass the token to the cmdlet, so that it can use it to authenticate to Azure when decrypting data protected with Always Encrypted.
$connString = 'Data Source=MYSERVER;Initial Catalog=MyDatabase;Integrated Security=True;ApplicationIntent=ReadOnly;Column Encryption Setting=Enabled'
Invoke-Sqlcmd -Query 'SELECT COUNT(*) AS Count FROM MyTable' -ConnectionString $connString -KeyVaultAccessToken $keyVaultAccessToken

參數

-AbortOnError

指出此 Cmdlet 會停止 SQL Server 命令，並在此 Cmdlet 發生錯誤時，將錯誤層級傳回至 Windows PowerShell ERRORLEVEL 變數。

如果錯誤的嚴重性高於 10，傳回的錯誤層級就是 1；如果錯誤的嚴重性為 10 以下，錯誤層級則為 0。

如果同時指定 ErrorLevel 參數，只有當錯誤訊息嚴重性也等於或高於 ErrorLevel 指定的值時，此 Cmdlet 才會傳回 1。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-AccessToken

用來驗證 SQL Server 的存取令牌，作為使用者/密碼或 Windows 驗證的替代方案。

例如，這可用來連線 SQL Azure DB 和使用 SQL Azure Managed InstanceService Principal 或 Managed Identity (查看此頁面底部的參考)

在常見的案例中，會使用類似 (取得 (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token 此參數，需要 Az.Account 模組)

使用此參數時，請勿指定 UserName、 Password 或 Credential 。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ApplicationIntent

線上到 SQL Server 可用性群組中的資料庫時，應用程式工作負載類型。

允許的值為：ReadOnly 和 ReadWrite。

Type:	ApplicationIntent
Accepted values:	ReadWrite, ReadOnly
Position:	Named
Default value:	ReadWrite
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ApplicationName

與連線相關聯的應用程式名稱。

Type:	String
Position:	Named
Default value:	.NET SqlClient Data Provider
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ConnectionString

指定要連線到伺服器的連接字串。

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ConnectionTimeout

指定當此 Cmdlet 無法成功連線到 Database Engine 實例時逾時的秒數。逾時值必須是介於 0 到 65534 之間的整數值。如果指定了 0，連線嘗試就不會逾時。

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

PSCredential 物件，其 [用戶名稱] 和 [密碼] 字段將用來連線到 SQL 實例。

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Database

指定資料庫的名稱。此 Cmdlet 會連接到 ServerInstance 參數中指定的實例中的這個資料庫。

如果未指定 Database 參數，則所使用的資料庫取決於目前路徑是否同時指定 SQLSERVER：\SQL 資料夾和資料庫名稱。如果路徑同時指定 SQL 資料夾和資料庫名稱，此 Cmdlet 會連線到路徑中指定的資料庫。如果路徑不是以 SQL 資料夾為基礎，或路徑不包含資料庫名稱，則此 Cmdlet 會連線到目前登入標識符的預設資料庫。如果您指定 IgnoreProviderContext 參數參數，這個 Cmdlet 不會考慮目前路徑中指定的任何資料庫，並連線到定義為目前登入標識符預設值的資料庫。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DedicatedAdministratorConnection

指出此 Cmdlet 會使用專用系統管理員連線 (DAC) 連線到 Database Engine 的實例。

DAC 可讓系統管理員用來進行一些動作，例如疑難排解不接受新標準連接的執行個體。

此執行個體必須設定為支援 DAC。

如果未啟用 DAC，此 Cmdlet 會報告錯誤，且不會執行。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableCommands

指出此 Cmdlet 會關閉一些在批處理文件中執行時可能會危害安全性的 sqlcmd 功能。

它可防止 Windows PowerShell 變數傳入 Invoke-Sqlcmd 腳本。

SQLCMDINI 指令碼變數中指定的啟動指令碼不會執行。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableVariables

表示這個 Cmdlet 會忽略 sqlcmd 腳本變數。當指令碼所包含的許多 INSERT 陳述式可能含有與變數 (例如 $(variable_name)) 相同格式的字串時，這就很有用。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Encrypt

連接到 SQL Server 時要使用的加密類型。

這個值會對應至 Encrypt Microsoft.Data.SqlClient 驅動程式之 SqlConnection 物件上的屬性 SqlConnectionEncryptOption 。

未指定時，預設值為 Mandatory。

這個參數是模組 v22 的新功能。如需詳細資訊，請參閱Strict Connection Encryption相關連結底下。

Type:	String
Accepted values:	Mandatory, Optional, Strict
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EncryptConnection

指出此 Cmdlet 使用安全套接字層 (SSL/TLS) 加密，以聯機到 ServerInstance 參數中指定的 Database Engine 實例。

從模組的 v22 開始，此參數已被取代。預設會加密 Connections。請考慮改用新的 -Encrypt 參數。如需詳細資訊，請參閱Strict Connection Encryption相關連結底下。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ErrorLevel

指定此 Cmdlet 只會顯示嚴重性層級等於或高於所指定值的錯誤訊息。如果未指定此參數或設定為 0，則會顯示所有錯誤訊息。 Database Engine 錯誤嚴重性的範圍介於 1 到 24 之間。

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FailoverPartner

如果主伺服器關閉，則要連線的夥伴伺服器名稱或位址。

Type:	String
Position:	Named
Default value:	""
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HostName

指定工作站名稱。工作站名稱是由 sp_who 系統預存程序所回報，而且位於 sys.processes 目錄檢視的 hostname 資料行中。如果未指定此參數，則預設值為執行 Invoke-Sqlcmd 的計算機名稱。此參數可用來識別不同的 Invoke-Sqlcmd 會話。

Type:	String
Aliases:	WorkstationID
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HostNameInCertificate

用於驗證 SQL Server TLS/SSL 憑證的主機名稱。如果您的 SQL Server 實例已啟用強制加密，而且您想要使用主機名/簡短名稱連線到實例，則必須傳遞此參數。如果省略此參數，則必須將完整域名 (FQDN) 傳遞至 -ServerInstance，才能連線到啟用強制加密的 SQL Server 實例。

這個參數是模組 v22 的新功能。如需詳細資訊，請參閱Strict Connection Encryption相關連結底下。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-IgnoreProviderContext

指出這個 Cmdlet 會忽略目前 SQLSERVER：\SQL 路徑所建立的資料庫內容。如果未指定 Database 參數，此 Cmdlet 會針對目前的登入標識碼或 Windows 帳戶使用預設資料庫。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-IncludeSqlUserErrors

表示此 Cmdlet 會傳回預設忽略的 SQL 使用者腳本錯誤。如果指定此參數，此 Cmdlet 會符合 sqlcmd 公用程式的預設行為。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InputFile

指定要作為此 Cmdlet 之查詢輸入的檔案。此檔案可以包含 Transact-SQL 陳述式、XQuery 陳述式以及 sqlcmd 命令和指令碼變數。請指定檔案的完整路徑。檔案路徑或檔案名稱中不允許使用空格。檔案預期會使用UTF-8進行編碼。

您應該只從信任的來源執行文稿。請利用適當的 NTFS 權限來確保所有輸入指令碼的安全。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-KeyVaultAccessToken

指定 Azure 金鑰保存庫中金鑰保存庫的存取令牌。如果使用儲存在 Azure 金鑰保存庫中金鑰保存庫中的數據行主要金鑰，以 Always Encrypted 保護要查詢的任何數據行，請使用此參數。或者，您可以在呼叫此 Cmdlet 之前，先使用 Add-SqlAzureAuthenticationContext 向 Azure 進行驗證。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ManagedHsmAccessToken

指定 Azure 金鑰保存庫中受控 HSM 的存取令牌。如果要查詢的任何數據行受到保護，請使用儲存在 Azure 金鑰保存庫受控 HSM 中的數據行主要密鑰 Always Encrypted，請使用此參數。或者，您可以在呼叫此 Cmdlet 之前，先使用 Add-SqlAzureAuthenticationContext 向 Azure 進行驗證。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxBinaryLength

指定針對具有二進位字串資料類型 (例如 binary 和 varbinary) 之資料行傳回的最大位元組數目。默認值為 1,024 個字節。

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxCharLength

指定針對具有字元或 Unicode 資料類型 (例如 char、nchar、varchar 和 nvarchar) 之資料行傳回的最大字元數目。默認值為 4,000 個字元。

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MultiSubnetFailover

如果您的應用程式連線到不同子網上的 AlwaysOn 可用性群組 (AG) ，則傳遞此參數可提供目前) 作用中伺服器 (的更快速偵測和連線。

注意：.NET Framework 4.6.1 或更新版本不需要傳遞 -MultiSubnetFailover。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-NewPassword

指定 SQL Server 驗證登入識別碼的新密碼。此 Cmdlet 會變更密碼，然後結束。您也必須指定 Username 和 Password 參數，以及指定登入目前密碼的密碼。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutputAs

指定這個 Cmdlet 取得的結果類型。

如果您未指定此參數的值，Cmdlet 會將值設定為 DataRows。

Type:	OutputType
Aliases:	As
Accepted values:	DataSet, DataTables, DataRows
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutputSqlErrors

指出此 Cmdlet 會在 Invoke-Sqlcmd 輸出中顯示錯誤訊息。

Type:	Boolean
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Password

指定 username 參數中指定的 SQL Server 驗證登入標識碼的密碼。密碼會區分大小寫。盡可能使用 Windows 驗證。請勿使用空白密碼，盡可能使用增強式密碼。

如果您指定 Password 參數後面接著密碼，則任何可以看到您監視的使用者都能看到密碼。

如果您在 .ps1 文本中編碼密碼後面接著密碼，則讀取腳本檔案的任何人都會看到您的密碼。

請將適當的 NTFS 權限指派給此檔案，防止其他使用者讀取此檔案。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Query

指定此 Cmdlet 執行的一或多個查詢。這些查詢可以是 Transact-SQL 或 XQuery 陳述式，或是 sqlcmd 命令。您可以指定多個以分號隔開的查詢。請勿指定 sqlcmd GO 分隔符號。請逸出字串中包含的任何雙引號。您可以考慮使用括號識別碼 (例如 [MyTable]) 而非引號識別碼 (例如 "MyTable")。

Type:	String
Position:	0
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-QueryTimeout

指定查詢逾時之前的秒數。如果未指定逾時值，查詢就不會逾時。逾時必須是介於 1 到 65535 之間的整數值。

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ServerInstance

指定字元字串或 SQL Server 管理物件 (SMO) 物件，指定 Database Engine 實例的名稱。針對預設實例，只指定計算機名稱：MyComputer。針對具名實例，請使用 ComputerName\InstanceName 格式。

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-SeverityLevel

指定錯誤訊息嚴重性層級的下限，此 Cmdlet 會傳回 ERRORLEVEL Windows PowerShell 變數。

此 Cmdlet 會從執行之查詢所產生的錯誤訊息傳回最高嚴重性層級，前提是嚴重性等於或高於 SeverityLevel 參數中指定的。

如果未指定 SeverityLevel 或設定為 0，此 Cmdlet 會將 0 傳回至 ERRORLEVEL。

Database Engine 錯誤訊息嚴重性層級的範圍介於 1 到 24 之間。

此 Cmdlet 不會針對嚴重性為 10 的資訊訊息回報嚴重性

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-StatisticsVariable

指定執行 Cmdlet 時，將指派 SQL Server 運行時間統計數據的 PowerShell 變數名稱。

此參數的常見用法是擷取 ExecutionTime (以毫秒為單位的累計 (時間量，) 提供者已花費處理 Cmdlet) ，或 IduRows (INSERT、DELETE 和 UPDATE 語句所影響的數據列總數) 。

如需詳細資訊，請參閱 SQL Server 提供者統計數據。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SuppressProviderContextWarning

指出此 Cmdlet 會隱藏此 Cmdlet 在目前 SQLSERVER：\SQL 路徑設定的資料庫內容中使用的警告，以建立 Cmdlet 的資料庫內容。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TrustServerCertificate

指出通道是否會在略過憑證鏈結以驗證信任時加密。

這個參數是模組 v22 的新功能。如需詳細資訊，請參閱Strict Connection Encryption相關連結底下。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Username

指定用於建立 Database Engine 執行個體之 SQL Server 驗證連接的登入識別碼。

密碼必須透過Password參數指定。

如果未指定 Username 和 Password，此 Cmdlet 會嘗試使用執行 Windows PowerShell 會話的 Windows 帳戶進行 Windows 驗證連線。盡可能使用 Windows 驗證。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Variable

指定一組用於 sqlcmd 腳本的 sqlcmd 腳本變數，並設定變數的值。

使用 Windows PowerShell 陣列來指定多個變數及其值;或者，使用 Hashtable ，其中索引鍵代表變數名稱和變數值。

使用陣列時，會修剪參數值。此行為會保留在模組的 v22 中，以便與 v21 回溯相容性。不建議依賴此行為，這可能會在未來的主要模組版本中變更。

類型的 Hashtable 參數僅適用於模組的 v22+ 。

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

輸入

System.Management.Automation.PSObject

輸出

System.Object

Invoke-Sqlcmd

Syntax

Description

範例

範例 1：連線到具名實例並執行腳本

範例 2：叫用腳本檔案中的命令，並將輸出儲存在文字檔中

範例 3：叫用腳本，並從字串傳入變數值

範例 4：叫用腳本，並從 SQL 資料庫引擎傳入變數

範例 5：執行查詢並顯示詳細信息輸出

範例 6：使用位置字串作為輸入叫用命令

範例 7：將數據擷取至 DataSet 物件

範例 8：取得特定數據行集

範例 9：取得連線的完整控制權

範例 10：執行預存程式並擷取 SQL 錯誤

範例 11：使用存取令牌連接到 Azure SQL 資料庫 (或 受控執行個體)

範例 12：使用服務主體連線至 Azure SQL 資料庫 (或 受控執行個體)

範例 13：使用受控識別連線至 Azure SQL 資料庫 (或 受控執行個體)

範例 14：使用 -ApplicationIntent 連線至針對 Read-Only 路由設定的可用性群組

範例 15：透過 -StatisticsVariable 參數擷取連線統計數據

範例 16：執行查詢，以解密使用 Always Encrypted 加密的數據行擷取的數據。 假設數據行主要金鑰儲存在 Azure 金鑰保存庫 的金鑰保存庫中。

參數

-AbortOnError

-AccessToken

-ApplicationIntent

-ApplicationName

-ConnectionString

-ConnectionTimeout

-Credential

-Database

-DedicatedAdministratorConnection

-DisableCommands

-DisableVariables

-Encrypt

-EncryptConnection

-ErrorLevel

-FailoverPartner

-HostName

-HostNameInCertificate

-IgnoreProviderContext

-IncludeSqlUserErrors

-InputFile

-KeyVaultAccessToken

-ManagedHsmAccessToken

-MaxBinaryLength

-MaxCharLength

-MultiSubnetFailover

-NewPassword

-OutputAs

-OutputSqlErrors

-Password

-Query

-QueryTimeout

-ServerInstance

-SeverityLevel

-StatisticsVariable

-SuppressProviderContextWarning

-TrustServerCertificate

-Username

-Variable

輸入

輸出

相關連結

其他資源

範例 11：使用存取令牌連接到 Azure SQL 資料庫 (或受控執行個體)

範例 12：使用服務主體連線至 Azure SQL 資料庫 (或受控執行個體)

範例 13：使用受控識別連線至 Azure SQL 資料庫 (或受控執行個體)

範例 16：執行查詢，以解密使用 Always Encrypted 加密的數據行擷取的數據。假設數據行主要金鑰儲存在 Azure 金鑰保存庫的金鑰保存庫中。