Start-Transaction

Spustí transakci.

Syntax

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

Description

Rutina Start-Transaction spustí transakci, což je řada příkazů, které jsou spravovány jako jednotka. Transakce může být dokončena nebo potvrzena. Alternativně může být zcela vrácena zpět nebo vrácena zpět, aby se všechna data změněná transakcí obnovila do původního stavu. Vzhledem k tomu, že příkazy v transakci se spravují jako jednotka, jsou potvrzeny všechny příkazy nebo všechny příkazy jsou vráceny zpět.

Pokud některý příkaz v transakci ve výchozím nastavení vygeneruje chybu, transakce se automaticky vrátí zpět. Toto chování můžete změnit pomocí parametru RollbackPreference .

Rutiny používané v transakci musí být navrženy tak, aby podporovaly transakce. Rutiny, které podporují transakce, mají parametr UseTransaction . Aby bylo možné provádět transakce v poskytovateli, musí poskytovatel podporovat transakce. Poskytovatel registru Windows PowerShell ve Windows Vista a novějších verzích operačního systému Windows podporuje transakce. Pomocí třídy Microsoft.PowerShell.Commands.Management.TransactedString můžete také zahrnout výrazy do transakcí v libovolné verzi systému Windows, která podporuje Windows PowerShell. Ostatní poskytovatelé Windows PowerShell můžou také podporovat transakce.

Najednou může být aktivní pouze jedna transakce. Pokud spustíte novou nezávislou transakci, zatímco transakce probíhá, nová transakce se stane aktivní transakcí a musíte potvrdit nebo vrátit zpět novou transakci před provedením jakýchkoli změn původní transakce.

Start-Transactionrutina je jednou ze sady rutin, které podporují funkci transakcí v Windows PowerShell. Další informace najdete v tématu about_Transactions.

Příklady

Příklad 1: Zahájení a vrácení transakce zpět

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

Tyto příkazy se spustí a vrátí transakce zpět. Vzhledem k tomu, že transakce je vrácena zpět, v registru se neprovedou žádné změny.

Příklad 2: Zahájení a dokončení transakce

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

Tyto příkazy se spustí a pak dokončí transakci. V registru se neprovedou žádné změny, dokud se Complete-Transaction příkaz nepoužívá.

Příklad 3: Použití různých předvoleb vrácení zpět

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

Tento příklad ukazuje účinek změny hodnoty parametru RollbackPreference .

V první sadě příkazů Start-Transaction nepoužívá funkci RollbackPreference. V důsledku toho se použije výchozí hodnota (Chyba). Pokud dojde k chybě v příkazu transakce, to znamená, že zadaná cesta neexistuje, transakce se automaticky vrátí zpět.

Ve druhé sadě příkazů Start-Transaction používá funkce RollbackPreference s hodnotou Never. V důsledku toho, když dojde k chybě v příkazu transakce, transakce je stále aktivní a lze ji úspěšně dokončit.

Vzhledem k tomu, že většina transakcí musí být provedena bez chyby, je obvykle upřednostňovaná výchozí hodnota rollbackPreference .

Příklad 4: Tuto rutinu použijte, když probíhá transakce

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

Tento příklad ukazuje účinek použití Start-Transaction , zatímco transakce probíhá. Účinek se podobá spojení probíhající transakce.

I když se jedná o zjednodušený příkaz, tento scénář často dochází v případě, že transakce zahrnuje spuštění skriptu, který obsahuje úplnou transakci.

První Start-Transaction příkaz spustí transakci. První New-Item příkaz je součástí transakce.

Druhý Start-Transaction příkaz přidá do transakce nový odběratel. Příkaz Get-Transaction teď vrátí transakci s počtem odběratelů 2. Druhý New-Item příkaz je součástí stejné transakce.

V registru se neprovedou žádné změny, dokud nebude dokončena celá transakce. K dokončení transakce musíte zadat dva Complete-Transaction příkazy, jeden pro každého odběratele. Pokud byste chtěli vrátit transakci zpět v libovolném okamžiku, všechny transakce by se vrátily zpět pro oba předplatitele.

Příklad 5: Spuštění nezávislé transakce, zatímco probíhá jedna transakce

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}

Tento příklad ukazuje účinek použití nezávislého parametru Start-Transaction k zahájení transakce, zatímco probíhá jiná transakce. V tomto případě se nová transakce vrátí zpět, aniž by to ovlivnilo původní transakci.

Ačkoli transakce jsou logicky nezávislé, protože pouze jedna transakce může být aktivní najednou, musíte vrátit zpět nebo potvrdit nejnovější transakce před obnovením práce na původní transakci.

První sada příkazů spustí transakci. Příkaz New-Item je součástí první transakce.

Ve druhé sadě příkazů Start-Transaction používá příkaz nezávislý parametr. Následující Get-Transaction příkaz ukazuje objekt transakce aktivní transakce, což je nejnovější. Počet odběratelů se rovná 1, což ukazuje, že transakce nesouvisejí.

Když se aktivní transakce vrátí zpět pomocí Undo-Transaction příkazu, původní transakce se znovu aktivuje.

Příkaz New-ItemProperty , který je součástí původní transakce, dokončí bez chyby a původní transakce lze dokončit pomocí Complete-Transaction příkazu. V důsledku toho se registr změní.

Příklad 6: Spuštění příkazů, které nejsou součástí transakce

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                     {}

Tento příklad ukazuje, že příkazy, které jsou odeslány, zatímco transakce probíhá, lze zahrnout do transakce nebo není zahrnut. Součástí transakce jsou pouze příkazy, které používají parametr UseTransaction .

První a třetí New-Item příkazy používají parametr UseTransaction . Tyto příkazy jsou součástí transakce. Protože druhý New-Item příkaz nepoužívá parametr UseTransaction , není součástí transakce.

První příkaz Get-ChildItem ukazuje efekt. Druhý New-Item příkaz je dokončen okamžitě, ale první a třetí New-Item příkazy nejsou účinné, dokud transakce nebude potvrzena.

Příkaz Complete-Transaction potvrdí transakci. V důsledku toho druhý příkaz Get-ChildItem ukazuje, že všechny nové položky jsou přidány do registru.

Příklad 7: Vrácení transakce, která se nedokončí v zadaném čase

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

Tento příkaz používá parametr časového limituStart-Transaction ke spuštění transakce, která musí být dokončena do dvou minut. Pokud se transakce po vypršení časového limitu nedokončí, vrátí se automaticky zpět.

Když vyprší časový limit, nebudete upozorněni, ale vlastnost Status objektu transakce je nastavena na RolledBack a příkazy, které používají UseTransaction parametr selžou.

Parametry

-Confirm

Před spuštěním rutiny zobrazí výzvu k potvrzení.

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

-Independent

Označuje, že tato rutina spustí transakci, která je nezávislá na probíhajících transakcích. Pokud ve výchozím nastavení používáte Start-Transaction , zatímco probíhá jiná transakce, přidá se do probíhající transakce nový odběratel. Tento parametr má vliv pouze v případě, že transakce již probíhá v relaci.

Pokud ve výchozím nastavení používáte Start-Transaction probíhající transakci, použije se existující objekt transakce znovu a počet odběratelů se zvýší. Účinek se podobá spojení původní transakce. Undo-Transaction Příkaz vrátí zpět celou transakci. K dokončení transakce musíte zadat Complete-Transaction příkaz pro každého odběratele. Vzhledem k tomu, že většina probíhajících transakcí současně souvisí, je výchozí hodnota dostatečná pro většinu použití.

Pokud zadáte nezávislý parametr, tato rutina vytvoří novou transakci, která se dá dokončit nebo vrátit zpět, aniž by to mělo vliv na původní transakci. Protože však může být aktivní pouze jedna transakce najednou, musíte dokončit nebo vrátit zpět novou transakci před obnovením práce na původní transakci.

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

-RollbackPreference

Určuje podmínky, za kterých se transakce automaticky vrátí zpět. Tento parametr přijímá tyto hodnoty:

  • Error Transakce se automaticky vrátí, pokud dojde k ukončení nebo neukončující chybě.
  • TerminatingError Transakce se vrátí zpět automaticky, pokud dojde k ukončovací chybě.
  • Never Transakce se nikdy nevrátí zpět automaticky.

Výchozí hodnota je Error.

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

-Timeout

Určuje maximální dobu v minutách, po kterou je transakce aktivní. Po vypršení časového limitu se transakce automaticky vrátí zpět.

Ve výchozím nastavení neexistuje časový limit pro transakce, které jsou spuštěny na příkazovém řádku. Při spuštění transakcí skriptem je výchozí časový limit 30 minut.

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

-WhatIf

Zobrazuje, co by se stalo při spuštění rutiny. Rutina není spuštěna.

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

Vstupy

None

Vstup do této rutiny nelze převést.

Výstupy

None

Tato rutina negeneruje žádný výstup.