Udostępnij za pośrednictwem

Start-Transaction

Moduł:
Microsoft.PowerShell.Management Module

Uruchamia transakcję.

Składnia

Default (Domyślna) 

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

Opis

Polecenie cmdlet Start-Transaction uruchamia transakcję, która jest serią poleceń zarządzanych jako jednostka. Transakcję można ukończyć lub zadeklarować. Alternatywnie można ją całkowicie cofnąć lub wycofać, aby wszystkie dane zmienione przez transakcję zostały przywrócone do pierwotnego stanu. Ponieważ polecenia w transakcji są zarządzane jako jednostka, wszystkie polecenia są zatwierdzane lub wszystkie polecenia są cofane.

Domyślnie jeśli jakiekolwiek polecenie w transakcji generuje błąd, transakcje są automatycznie wycofywane. Aby zmienić to zachowanie, możesz użyć parametru RollbackPreference.

Polecenia cmdlet używane w transakcji muszą być zaprojektowane tak, aby obsługiwały transakcje. Polecenia cmdlet obsługujące transakcje mają parametr UseTransaction. Aby wykonać transakcje u dostawcy, dostawca musi obsługiwać transakcje. Dostawca rejestru programu Windows PowerShell w systemie Windows Vista i nowszych wersjach systemu operacyjnego Windows obsługuje transakcje. Można również użyć klasy Microsoft.PowerShell.Commands.Management.TransactedString, aby uwzględnić wyrażenia w transakcjach w dowolnej wersji systemu Windows, która obsługuje program Windows PowerShell. Inni dostawcy programu Windows PowerShell mogą również obsługiwać transakcje.

Jednocześnie może być aktywna tylko jedna transakcja. Jeśli rozpoczniesz nową, niezależną transakcję, gdy transakcja jest w toku, nowa transakcja stanie się aktywną transakcją i musisz zatwierdzić lub wycofać nową transakcję przed wprowadzeniem jakichkolwiek zmian w oryginalnej transakcji.

Start-Transaction polecenie cmdlet to jeden z zestawów poleceń cmdlet, które obsługują funkcję transakcji w programie Windows PowerShell. Aby uzyskać więcej informacji, zobacz about_Transactions.

Przykłady

Przykład 1. Uruchamianie i wycofywanie transakcji

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

Te polecenia są uruchamiane, a następnie cofane transakcji. Ponieważ transakcja jest cofana, żadne zmiany nie są wprowadzane do rejestru.

Przykład 2. Rozpoczęcie i ukończenie transakcji

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

Te polecenia są uruchamiane, a następnie kończą transakcję. Do momentu użycia polecenia Complete-Transaction w rejestrze nie zostaną wprowadzone żadne zmiany.

Przykład 3. Używanie różnych preferencji wycofywania

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

W tym przykładzie pokazano efekt zmiany wartości parametru RollbackPreference.

W pierwszym zestawie poleceń Start-Transaction nie używa rollbackPreference. W związku z tym jest używana wartość domyślna (Błąd). Gdy w poleceniu transakcji wystąpi błąd, oznacza to, że określona ścieżka nie istnieje, transakcja zostanie automatycznie wycofana.

W drugim zestawie poleceń Start-Transaction używa RollbackPreference z wartością Nigdy. W związku z tym, gdy w poleceniu transakcji wystąpi błąd, transakcja jest nadal aktywna i może zostać ukończona pomyślnie.

Ponieważ większość transakcji musi być wykonywana bez błędu, zazwyczaj preferowana jest domyślna wartość RollbackPreference.

Przykład 4. Użyj tego polecenia cmdlet, gdy transakcja jest w toku

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

W tym przykładzie pokazano efekt używania Start-Transaction, gdy transakcja jest w toku. Efekt jest podobny do łączenia transakcji w toku.

Chociaż jest to uproszczone polecenie, ten scenariusz często występuje, gdy transakcja obejmuje uruchomienie skryptu zawierającego pełną transakcję.

Pierwsze Start-Transaction polecenie uruchamia transakcję. Pierwsze polecenie New-Item jest częścią transakcji.

Drugie polecenie Start-Transaction dodaje nowego subskrybenta do transakcji. Polecenie Get-Transaction zwraca teraz transakcję z liczbą subskrybentów 2. Drugie polecenie New-Item jest częścią tej samej transakcji.

Do momentu ukończenia całej transakcji nie zostaną wprowadzone żadne zmiany w rejestrze. Aby ukończyć transakcję, musisz wprowadzić dwa Complete-Transaction polecenia, po jednym dla każdego subskrybenta. Jeśli w dowolnym momencie wycofano transakcję, wszystkie transakcje zostaną wycofane dla obu subskrybentów.

Przykład 5. Uruchamianie niezależnej transakcji, gdy jedna jest w toku

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}

W tym przykładzie pokazano efekt użycia parametru IndependentStart-Transaction, aby rozpocząć transakcję, gdy inna transakcja jest w toku. W takim przypadku nowa transakcja zostanie wycofana bez wpływu na oryginalną transakcję.

Chociaż transakcje są logicznie niezależne, ponieważ tylko jedna transakcja może być aktywna naraz, należy wycofać lub zatwierdzić najnowszą transakcję przed wznowieniem pracy nad oryginalną transakcją.

Pierwszy zestaw poleceń uruchamia transakcję. Polecenie New-Item jest częścią pierwszej transakcji.

W drugim zestawie poleceń polecenie Start-Transaction używa parametru Independent. Poniższe polecenie Get-Transaction pokazuje obiekt transakcji dla aktywnej transakcji, która jest najnowsza. Liczba subskrybentów jest równa 1, która pokazuje, że transakcje nie są powiązane.

Gdy aktywna transakcja zostanie wycofana przy użyciu polecenia Undo-Transaction, oryginalna transakcja zostanie ponownie aktywna.

Polecenie New-ItemProperty, które jest częścią oryginalnej transakcji, kończy się bez błędu, a oryginalna transakcja może zostać ukończona przy użyciu polecenia Complete-Transaction. W związku z tym rejestr zostanie zmieniony.

Przykład 6. Uruchamianie poleceń, które nie są częścią transakcji

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

W tym przykładzie pokazano, że polecenia przesyłane podczas wykonywania transakcji mogą być uwzględniane w transakcji lub nieuwzględniane. Tylko polecenia korzystające z parametru UseTransaction są częścią transakcji.

Pierwsze i trzecie polecenia New-Item używają parametru UseTransaction. Te polecenia są częścią transakcji. Ponieważ drugie polecenie New-Item nie używa parametru UseTransaction, nie jest częścią transakcji.

Pierwsze polecenie Get-ChildItem pokazuje efekt. Drugie polecenie New-Item jest wykonywane natychmiast, ale pierwsze i trzecie New-Item polecenia nie będą skuteczne, dopóki transakcja nie zostanie zatwierdzona.

Polecenie Complete-Transaction zatwierdza transakcję. W rezultacie drugie polecenie Get-ChildItem pokazuje, że wszystkie nowe elementy są dodawane do rejestru.

Przykład 7: Wycofywanie transakcji, która nie kończy się w określonym czasie

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

To polecenie używa limitu czasu parametru Start-Transaction, aby uruchomić transakcję, która musi zostać ukończona w ciągu dwóch minut. Jeśli transakcja nie zostanie zakończona po wygaśnięciu limitu czasu, zostanie ona wycofana automatycznie.

Po wygaśnięciu limitu czasu otrzymasz powiadomienie, ale właściwość Status obiektu transakcji jest ustawiona na wartość RolledBack i polecenia, które używają parametru UseTransaction.

Parametry

-Confirm

Prosi o potwierdzenie przed uruchomieniem cmdletu.

Właściwości parametru

Typ:SwitchParameter
Domyślna wartość:False
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:por

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-Independent

Wskazuje, że to polecenie cmdlet uruchamia transakcję, która jest niezależna od wszelkich transakcji w toku. Domyślnie, jeśli używasz Start-Transaction podczas wykonywania innej transakcji, nowy subskrybent jest dodawany do transakcji w toku. Ten parametr ma wpływ tylko wtedy, gdy transakcja jest już w toku w sesji.

Domyślnie, jeśli używasz Start-Transaction podczas wykonywania transakcji, istniejący obiekt transakcji jest ponownie używany i liczba subskrybentów jest zwiększana. Efekt jest podobny do łączenia oryginalnej transakcji. Polecenie Undo-Transaction powoduje wycofanie całej transakcji. Aby ukończyć transakcję, musisz wprowadzić Complete-Transaction polecenie dla każdego subskrybenta. Ponieważ większość transakcji, które są w toku w tym samym czasie, są powiązane, wartość domyślna jest wystarczająca dla większości zastosowań.

Jeśli określisz parametr Independent, to polecenie cmdlet utworzy nową transakcję, którą można ukończyć lub cofnąć bez wpływu na oryginalną transakcję. Jednak ponieważ tylko jedna transakcja może być aktywna w danym momencie, przed wznowieniem pracy nad oryginalną transakcją należy zakończyć lub wycofać nową transakcję.

Właściwości parametru

Typ:SwitchParameter
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-RollbackPreference

Określa warunki, w których transakcja jest automatycznie cofana. Dopuszczalne wartości tego parametru to:

  • Error Transakcja jest cofana automatycznie w przypadku wystąpienia błędu zakończenia lub zakończenia.
  • TerminatingError Transakcja zostanie wycofana automatycznie, jeśli wystąpi błąd zakończenia.
  • Never Transakcja nigdy nie zostanie wycofana automatycznie.

Wartość domyślna to Error.

Właściwości parametru

Typ:RollbackSeverity
Domyślna wartość:None
Dopuszczalne wartości:Error, TerminatingError, Never
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-Timeout

Określa maksymalny czas w minutach, że transakcja jest aktywna. Po wygaśnięciu limitu czasu transakcja zostanie automatycznie wycofana.

Domyślnie nie ma limitu czasu dla transakcji uruchamianych w wierszu polecenia. Gdy transakcje są uruchamiane przez skrypt, domyślny limit czasu wynosi 30 minut.

Właściwości parametru

Typ:Int32
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:Limit czasuMins

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-WhatIf

Pokazuje, co się stanie, jeśli polecenie cmdlet zostanie uruchomione. Cmdlet nie jest uruchomiony.

Właściwości parametru

Typ:SwitchParameter
Domyślna wartość:False
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:Wi

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

CommonParameters

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Dane wejściowe

None

Nie można przekazać danych wejściowych potoku do tego polecenia cmdlet.

Dane wyjściowe

None

To polecenie cmdlet nie generuje żadnych danych wyjściowych.