Start-Transaction

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. Transakcja może zostać ukończona lub zatwierdzona. 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ą wycofywane.

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 do obsługi transakcji. Polecenia cmdlet obsługujące transakcje mają parametr UseTransaction . Aby wykonać transakcje u dostawcy, dostawca musi obsługiwać transakcje. Dostawca rejestru 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 Windows PowerShell. Inni dostawcy 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-Transactionpolecenie cmdlet jest jednym z zestawów poleceń cmdlet, które obsługują funkcję transakcji w 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 wycofywały transakcję. Ponieważ transakcja jest wycofywane, żadne zmiany nie są wprowadzane do rejestru.

Przykład 2: Uruchamianie i wykonywanie 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 nie zostaną wprowadzone żadne zmiany w rejestrze Complete-Transaction .

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 jest używana funkcja 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ą Nigdy. W związku z tym, gdy wystąpi błąd w poleceniu transakcji, transakcja jest nadal aktywna i może zostać ukończona pomyślnie.

Ponieważ większość transakcji musi być wykonywana bez błędu, wartość domyślna 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 dołączania transakcji w toku.

Chociaż jest to uproszczone polecenie, ten scenariusz często występuje, gdy transakcja obejmuje uruchomienie skryptu, który zawiera 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ę, należy 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, co pokazuje, że transakcje nie są powiązane.

Gdy aktywna transakcja zostanie wycofana przy użyciu Undo-Transaction polecenia, oryginalna transakcja stanie się 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 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, gdy transakcja jest w toku, mogą być uwzględniane w transakcji lub nieuwzględnione. 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 Start-TransactionLimit czasu do uruchomienia transakcji, 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 ma wartość RolledBack i polecenia używające parametru UseTransaction kończą się niepowodzeniem.

Parametry

-Confirm

Monituje o potwierdzenie przed uruchomieniem polecenia cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters: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 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 , gdy transakcja jest w toku, istniejący obiekt transakcji jest ponownie używany i liczba subskrybentów jest zwiększana. Efekt jest podobny do przyłączenia oryginalnej transakcji. Polecenie Undo-Transaction cofa całą transakcję. Aby ukończyć transakcję, należy wprowadzić Complete-Transaction polecenie dla każdego subskrybenta. Ponieważ większość transakcji, które są w toku w tym samym czasie, jest powiązana, wartość domyślna jest wystarczająca dla większości zastosowań.

Jeśli określisz parametr Independent , to polecenie cmdlet tworzy 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, należy zakończyć lub wycofać nową transakcję przed wznowieniem pracy nad oryginalną transakcją.

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

-RollbackPreference

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

  • Error Transakcja jest wycofywane 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.

Wartość domyślna to Error.

Type:RollbackSeverity
Accepted values:Error, TerminatingError, Never
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters: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.

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

-WhatIf

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

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters: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.