Udostępnij za pośrednictwem

Start-Transaction

  • Odwołanie
Moduł:
Microsoft.PowerShell.Management

Uruchamia transakcję.

Składnia

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

Opis

Polecenie Start-Transaction cmdlet 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 Complete-Transaction użycia polecenia 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 funkcji 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 funkcji RollbackPreference z wartością Never. 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, domyślna wartość rollbackPreference jest zwykle preferowana.

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życia 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 New-Item polecenie jest częścią transakcji.

Drugie Start-Transaction polecenie dodaje nowego subskrybenta do transakcji. Polecenie Get-Transaction zwraca teraz transakcję z liczbą subskrybentów 2. Drugie New-Item polecenie 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 Independent w Start-Transaction celu uruchomienia transakcji, 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ń Start-Transaction polecenie używa parametru Independent . Poniższe Get-Transaction polecenie 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 Undo-Transaction polecenia, oryginalna transakcja ponownie stanie się 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 za pomocą Complete-Transaction polecenia . 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 używające parametru UseTransaction są częścią transakcji.

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

Pierwsze polecenie Get-ChildItem pokazuje efekt. Drugie New-Item polecenie jest wykonywane natychmiast, ale pierwsze i trzecie New-Item polecenia nie są 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 parametru Limit czasu dla Start-Transaction polecenia , 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 RolledBack i polecenia używające parametru UseTransaction kończą się niepowodzeniem.

Parametry

-Confirm

Monituje o potwierdzenie przed uruchomieniem polecenia cmdlet.

Typ:SwitchParameter
Aliasy:cf
Position:Named
Domyślna wartość:False
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych: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 innej transakcji w toku, nowy subskrybent zostanie dodany 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, a 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ę.

Typ:SwitchParameter
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-RollbackPreference

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

  • Error Transakcja zostanie wycofana automatycznie, jeśli wystąpi błąd zakończenia lub niepowodujący zakończenia.
  • TerminatingError Transakcja zostanie wycofana automatycznie, jeśli wystąpi błąd zakończenia.
  • Never Transakcja nigdy nie zostanie wycofana automatycznie.

Domyślna wartość to Error.

Typ:RollbackSeverity
Dopuszczalne wartości:Error, TerminatingError, Never
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych: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.

Typ:Int32
Aliasy:TimeoutMins
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-WhatIf

Pokazuje, co się stanie po uruchomieniu polecenia cmdlet. Polecenie cmdlet nie zostało uruchomione.

Typ:SwitchParameter
Aliasy:wi
Position:Named
Domyślna wartość:False
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

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.