Start-Transaction

  • Riferimento
Modulo:
Microsoft.PowerShell.Management

Avvia una transazione.

Sintassi

Start-Transaction
     [-Timeout <Int32>]
     [-Independent]
     [-RollbackPreference <RollbackSeverity>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Descrizione

Il Start-Transaction cmdlet avvia una transazione, ovvero una serie di comandi gestiti come unità. È possibile completare o eseguire il commit di una transazione. In alternativa, può essere completamente annullata o eseguito il rollback, in modo che tutti i dati modificati dalla transazione vengano ripristinati nello stato originale. Poiché i comandi di una transazione vengono gestiti come un'unità, deve essere eseguito su tutti il commit o il rollback.

Per impostazione predefinita, se un comando nella transazione genera un errore, viene eseguito automaticamente il rollback delle transazioni. È possibile usare il parametro RollbackPreference per modificare questo comportamento.

I cmdlet usati in una transazione devono essere progettati per supportare le transazioni. I cmdlet che supportano le transazioni hanno un parametro UseTransaction . Per eseguire transazioni in un provider, è necessario che il provider supporti le transazioni. Il provider del Registro di sistema di Windows PowerShell in Windows Vista e versioni successive del sistema operativo Windows supporta le transazioni. È anche possibile usare la classe Microsoft.PowerShell.Commands.Management.TransactedString per includere espressioni nelle transazioni in qualsiasi versione del sistema Windows che supporta Windows PowerShell. Anche altri provider di Windows PowerShell supportano le transazioni.

Può essere attiva solo una transazione alla volta. Se si avvia una nuova transazione indipendente mentre è in corso una transazione, la nuova transazione diventa la transazione attiva ed è necessario eseguire il commit o il rollback della nuova transazione prima di apportare modifiche alla transazione originale.

Start-Transaction il cmdlet è uno dei set di cmdlet che supportano la funzionalità transazioni in Windows PowerShell. Per altre informazioni, vedere about_Transactions.

Esempio

Esempio 1: Avviare ed eseguire il rollback di una transazione

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Undo-Transaction

Questi comandi avviano una transazione e quindi ne eseguono il rollback. Dopo il rollback della transazione, non vengono apportate modifiche al Registro di sistema.

Esempio 2: Avviare e completare una transazione

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-Transaction

Questi comandi avviano e quindi completano una transazione. Non vengono apportate modifiche al Registro di sistema finché non viene usato il Complete-Transaction comando .

Esempio 3: Usare preferenze di rollback diverse

Set-Location HKCU:\software
Start-Transaction
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item -Path . -Name "ContosoCompany" -UseTransaction
Start-Transaction -RollbackPreference never
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item -Path . -Name "ContosoCompany" -UseTransaction

# Start-Transaction (-rollbackpreference error)

Start-Transaction
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item : The registry key at the specified path does not exist.

At line:1 char:9
+ new-item <<<<  -Path NoPath -Name ContosoCompany -UseTransaction

New-Item -Path . -Name "Contoso" -UseTransaction

New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
At line:1 char:9
+ New-Item <<<<  -Path . -Name ContosoCompany -UseTransaction

# Start-Transaction (-rollbackpreference never)

Start-Transaction -RollbackPreference never
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction

New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ New-Item <<<<  -Path NoPath -Name "ContosoCompany" -UseTransaction

New-Item -Path . -Name "ContosoCompany" -UseTransaction

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany                 {}
Complete-Transaction

# Succeeds

In questo esempio viene illustrato l'effetto della modifica del valore del parametro RollbackPreference .

Nel primo set di comandi Start-Transaction non usa RollbackPreference. Di conseguenza, viene usato il valore predefinito (Errore). Quando si verifica un errore in un comando di transazione, ovvero il percorso specificato non esiste, viene eseguito automaticamente il rollback della transazione.

Nel secondo set di comandi Start-Transaction usa RollbackPreference con il valore Never. Di conseguenza, se si verifica un errore in un comando della transazione, la transazione sarà ancora attiva e potrà essere completata correttamente.

Poiché la maggior parte delle transazioni deve essere eseguita senza errori, il valore predefinito rollbackPreference è in genere preferibile.

Esempio 4: Usare questo cmdlet mentre è in corso una transazione

Set-Location HKCU:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
Start-Transaction
Get-Transaction
New-Item "ContosoCompany2" -UseTransaction
Complete-Transaction
Complete-Transaction
Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                2                 Active

In questo esempio viene illustrato l'effetto dell'utilizzo Start-Transaction mentre è in corso una transazione. L'effetto è molto simile a quello che si ottiene con l'aggiunta alla transazione in corso.

Anche se si tratta di un comando semplificato, questo scenario si verifica spesso quando la transazione comporta l'esecuzione di uno script che include una transazione completa.

Il primo Start-Transaction comando avvia la transazione. Il primo New-Item comando fa parte della transazione.

Il secondo Start-Transaction comando aggiunge un nuovo sottoscrittore alla transazione. Il Get-Transaction comando restituisce ora una transazione con un numero di sottoscrittori pari a 2. Il secondo New-Item comando fa parte della stessa transazione.

Non vengono apportate modifiche al Registro di sistema fino al completamento dell'intera transazione. Per completare la transazione, è necessario immettere due Complete-Transaction comandi, uno per ogni sottoscrittore. Se si esegue il rollback della transazione in qualsiasi momento, verrà eseguito il rollback di tutte le transazioni per entrambi i sottoscrittori.

Esempio 5: Avviare una transazione indipendente mentre è in corso

Set-Location HKCU:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
Start-Transaction -Independent
Get-Transaction
Undo-Transaction
New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-Transaction
Get-ChildItem contoso*
Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                1                 Active
Undo-Transaction
New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
MyKey
-----
123
Complete-Transaction
Get-ChildItem contoso*
Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   1 MyCompany                      {MyKey}

In questo esempio viene illustrato l'effetto dell'utilizzo del parametro Independent di Start-Transaction per avviare una transazione mentre è in corso un'altra transazione. In questo caso, viene eseguito il rollback della nuova transazione senza effetti su quella originale.

Anche se le transazioni sono logicamente indipendenti, poiché può essere attiva solo una transazione alla volta, è necessario eseguire il rollback o il commit della transazione più recente prima di riprendere le operazioni su quella originale.

Il primo set di comandi avvia una transazione. Il New-Item comando fa parte della prima transazione.

Nel secondo set di comandi il Start-Transaction comando usa il parametro Independent . Il Get-Transaction comando seguente mostra l'oggetto transazione per la transazione attiva, ovvero quello più recente. Il numero di sottoscrittori è uguale a 1, che indica che le transazioni non sono correlate.

Quando viene eseguito il rollback della transazione attiva tramite un Undo-Transaction comando, la transazione originale diventa nuovamente attiva.

Il New-ItemProperty comando, che fa parte della transazione originale, termina senza errori e la transazione originale può essere completata usando il Complete-Transaction comando . Di conseguenza, il Registro di sistema viene modificato.

Esempio 6: Eseguire comandi che non fanno parte di una transazione

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany1" -UseTransaction
New-Item "ContosoCompany2"
New-Item "ContosoCompany3" -UseTransaction
Get-ChildItem contoso*

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany2                {}

Complete-Transaction
Get-ChildItem contoso*

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany1                     {}
0   0 ContosoCompany2                     {}
0   0 ContosoCompany3                     {}

Questo esempio dimostra che i comandi inviati mentre è in corso una transazione possono essere o meno inclusi nella transazione. Solo i comandi che usano il parametro UseTransaction fanno parte della transazione.

Il primo e il terzo New-Item comando usano il parametro UseTransaction . Questi comandi fanno parte della transazione. Poiché il secondo New-Item comando non usa il parametro UseTransaction , non fa parte della transazione.

Il primo comando Get-ChildItem mostra l'effetto. Il secondo New-Item comando viene completato immediatamente, ma il primo e il terzo New-Item comando non sono validi fino a quando non viene eseguito il commit della transazione.

Il Complete-Transaction comando esegue il commit della transazione. Di conseguenza, il secondo comando Get-ChildItem mostra che tutti i nuovi elementi vengono aggiunti al Registro di sistema.

Esempio 7: Eseguire il rollback di una transazione che non termina in un intervallo di tempo specificato

Start-Transaction -Timeout 2

# Wait two minutes...

Get-Transaction
New-Item HKCU:\Software\ContosoCompany -UseTransaction
Start-Transaction -Timeout 2

# Wait two minutes...

Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   -----------
Error                1                 RolledBack

New-Item HKCU:\Software\ContosoCompany -UseTransaction

New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
At line:1 char:9
+ new-item <<<<  MyCompany -UseTransaction

Questo comando usa il parametro Timeout di Start-Transaction per avviare una transazione che deve essere completata entro due minuti. Se la transazione non viene completata alla scadenza del timeout, viene eseguito automaticamente il rollback.

Quando scade il timeout, non si riceve una notifica, ma la proprietà Status dell'oggetto transazione è impostata su RolledBack e i comandi che usano il parametro UseTransaction hanno esito negativo.

Parametri

-Confirm

Richiede conferma prima di eseguire il cmdlet.

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

-Independent

Indica che questo cmdlet avvia una transazione indipendente da qualsiasi transazione in corso. Per impostazione predefinita, se si usa Start-Transaction mentre è in corso un'altra transazione, viene aggiunto un nuovo sottoscrittore alla transazione in corso. Questo parametro ha effetto solo se nella sessione è già in corso una transazione.

Per impostazione predefinita, se si usa Start-Transaction mentre è in corso una transazione, l'oggetto transazione esistente viene riutilizzato e il conteggio dei sottoscrittori viene incrementato. L'effetto è molto simile a quello che si ottiene con l'aggiunta alla transazione originale. Un Undo-Transaction comando esegue il rollback dell'intera transazione. Per completare la transazione, è necessario immettere un Complete-Transaction comando per ogni sottoscrittore. Poiché la maggior parte delle transazioni in corso contemporaneamente sono correlate, il valore predefinito è sufficiente per la maggior parte degli utilizzi.

Se si specifica il parametro Independent , questo cmdlet crea una nuova transazione che può essere completata o annullata senza influire sulla transazione originale. Tuttavia, poiché può essere attiva solo una transazione alla volta, è necessario completare la nuova transazione o eseguirne il rollback prima di riprendere le operazioni su quella originale.

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

-RollbackPreference

Specifica le condizioni in base alle quali viene automaticamente eseguito il rollback di una transazione. I valori validi per questo parametro sono:

  • Error Il rollback della transazione viene eseguito automaticamente se si verifica un errore irreversibile o non irreversibile.
  • TerminatingError Il rollback della transazione viene eseguito automaticamente se si verifica un errore di terminazione.
  • Never La transazione non viene mai eseguito automaticamente il rollback.

Il valore predefinito è Error.

Type:RollbackSeverity
Accepted values:Error, TerminatingError, Never
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Timeout

Specifica l'intervallo di tempo massimo, in minuti, durante il quale la transazione è attiva. Allo scadere del timeout, viene automaticamente eseguito il rollback della transazione.

Per impostazione predefinita, non sono impostati timeout per le transazioni avviate dalla riga di comando. Se le transazioni vengono avviate con uno script, il timeout predefinito è di 30 minuti.

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

-WhatIf

Mostra gli effetti dell'esecuzione del cmdlet. Il cmdlet non viene eseguito.

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

Input

None

Non è possibile inviare input tramite pipe a questo cmdlet.

Output

None

Questo cmdlet non genera alcun output.