Invoke-Sqlcmd

參考

模組:: SQLServer

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

語法

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>]
      [-ProgressAction <ActionPreference>]
      [<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>]
      [-ProgressAction <ActionPreference>]
      [<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、：listvar、：reset、:p erftrace 和：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 Engine 的具名實例，並執行基本 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 Database （或受控實例）

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 Database （或受控實例）

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 Database （或受控實例）

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).

Connect-AzAccount -Identity
$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'

範例 14：使用使用者指派的受控識別連線到 Azure SQL Database （或受控實例）

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).

Connect-AzAccount -Identity -AccountId '<your-user-assigned-managed-identity-client-id>'
$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'

範例 15：使用 -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 中的不同伺服器。順便說一句，觀察 -ApplicationName 和 -HostName 參數的使用方式，以可視化方式區分這兩個結果：這是一種常見技術，可用來追蹤連線及其意圖，但此處所說明的 -ApplicationIntent 範例之外。

範例 16：透過 -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 提供者統計數據。

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

# 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。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-AccessToken

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

例如，這可以用來使用 Service Principal 或 Managed Identity 連線到 SQL Azure DB 和 SQL Azure Managed Instance（請參閱此頁面底部的參考）

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

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ApplicationIntent

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

允許的值為：ReadOnly 和 ReadWrite。

類型:	ApplicationIntent
接受的值:	ReadWrite, ReadOnly
Position:	Named
預設值:	ReadWrite
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ApplicationName

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

類型:	String
Position:	Named
預設值:	.NET SqlClient Data Provider
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ConnectionString

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

類型:	String
Position:	Named
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-ConnectionTimeout

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

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Credential

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

類型:	PSCredential
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Database

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

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DedicatedAdministratorConnection

指出此 Cmdlet 會使用專用系統管理員連接（DAC）連接到 Database Engine 的實例。

系統管理員會使用 DAC 來進行動作，例如對不接受新標準連線的實例進行疑難解答。

實例必須設定為支援 DAC。

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DisableCommands

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

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

SQLCMDINI 文本變數中指定的啟動腳本不會執行。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DisableVariables

表示此 Cmdlet 會忽略 sqlcmd 腳本變數。當腳本包含許多 INSERT 語句時，這可能包含與變數具有相同格式的字串，例如 $（variable_name）。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Encrypt

線上到 SQL Server 時要使用的加密類型。

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

未指定時，預設值會 Mandatory。

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

類型:	String
接受的值:	Mandatory, Optional, Strict
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-EncryptConnection

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

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ErrorLevel

指定此 Cmdlet 只會顯示嚴重性層級等於或高於指定值的錯誤訊息。如果未指定此參數或設定為 0，則會顯示所有錯誤訊息。資料庫引擎錯誤嚴重性的範圍從 1 到 24。

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-FailoverPartner

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

類型:	String
Position:	Named
預設值:	""
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HostName

指定工作站名稱。工作站名稱是由sp_who系統預存程式和 sys.processes 目錄檢視的主機名數據行所報告。如果未指定此參數，則預設值為執行 Invoke-Sqlcmd 的計算機名稱。此參數可用來識別不同的 Invoke-Sqlcmd 會話。

類型:	String
別名:	WorkstationID
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HostNameInCertificate

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

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-IgnoreProviderContext

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-IncludeSqlUserErrors

指出此 Cmdlet 會傳回預設忽略的 SQL 使用者腳本錯誤。如果指定此參數，這個 Cmdlet 會比對 sqlcmd 公用程式的預設行為。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-InputFile

指定要作為此 Cmdlet 之查詢輸入的檔案。檔案可以包含 Transact-SQL 語句、XQuery 語句和 sqlcmd 命令和腳本變數。指定檔案的完整路徑。檔案應該使用UTF-8進行編碼。

您應該只執行來自受信任來源的腳稿。請確定所有輸入文本都受到適當的NTFS許可權保護。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-KeyVaultAccessToken

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ManagedHsmAccessToken

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaxBinaryLength

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

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaxCharLength

指定字元或 Unicode 資料類型之數據行傳回的最大字元數，例如 char、nchar、varchar 和 nvarchar。默認值為 4,000 個字元。

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MultiSubnetFailover

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

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-NewPassword

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-OutputAs

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

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

類型:	OutputType
別名:	As
接受的值:	DataSet, DataTables, DataRows
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-OutputSqlErrors

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

類型:	Boolean
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Password

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

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

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

將適當的NTFS許可權指派給檔案，以防止其他使用者讀取檔案。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ProgressAction

決定 PowerShell 如何回應腳本、Cmdlet 或提供者所產生的進度更新，例如 Write-Progress Cmdlet 所產生的進度列。 Write-Progress Cmdlet 會建立顯示命令狀態的進度列。

類型:	ActionPreference
別名:	proga
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Query

指定此 Cmdlet 執行的一或多個查詢。查詢可以是 Transact-SQL 或 XQuery 語句，或 sqlcmd 命令。您可以指定以分號分隔的多個查詢。請勿指定 sqlcmd GO 分隔符。逸出字串中包含的任何雙引號。請考慮使用括號標識碼，例如 [MyTable]，而不是引號標識碼，例如 “MyTable”。

類型:	String
Position:	0
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-QueryTimeout

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

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ServerInstance

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

類型:	PSObject
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	True
接受萬用字元:	False

-SeverityLevel

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

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

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

Database Engine 錯誤訊息的嚴重性層級從 1 到 24 不等。

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

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-StatisticsVariable

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

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

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-SuppressProviderContextWarning

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-TrustServerCertificate

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

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Username

指定對 Database Engine 實例進行 SQL Server 驗證連線的登入標識碼。

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

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Variable

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

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

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

Hashtable 類型的參數只能在模組的 v22+ 中使用。

類型:	PSObject
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

System.Management.Automation.PSObject

輸出

System.Object

共用方式為

Invoke-Sqlcmd

語法

Description

範例

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

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

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

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

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

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

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

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

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

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

範例 11：使用存取令牌連線到 Azure SQL Database （或受控實例）

範例 12：使用服務主體連線到 Azure SQL Database （或受控實例）

範例 13：使用系統指派的受控識別連線到 Azure SQL Database （或受控實例）

範例 14：使用使用者指派的受控識別連線到 Azure SQL Database （或受控實例）

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

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

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

參數

-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

-ProgressAction

-Query

-QueryTimeout

-ServerInstance

-SeverityLevel

-StatisticsVariable

-SuppressProviderContextWarning

-TrustServerCertificate

-Username

-Variable

輸入

輸出

相關連結

意見反應

其他資源

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