From 78de2523137fb6537fe492659a1eda3af8f212e0 Mon Sep 17 00:00:00 2001
From: Simon Rozsival <simon@rozsival.com>
Date: Fri, 11 Sep 2026 18:21:15 +0200
Subject: [PATCH] [androidsdk] Atomically replace SDK packages

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .../RemoveDirectoryBackups.cs                 |  36 ++++
 .../ReplaceDirectory.cs                       |  84 ++++++++
 .../RetryingDirectoryTask.cs                  | 103 ++++++++++
 src/androidsdk/androidsdk.targets             |  62 +++---
 .../AndroidSdkTargetsTests.cs                 | 116 ++++++++++++
 ...osoft.Android.Build.BaseTasks-Tests.csproj |   1 +
 .../ReplaceDirectoryTests.cs                  | 179 ++++++++++++++++++
 .../Resources/AndroidSdkTargetsTest.proj      |  22 +++
 8 files changed, 575 insertions(+), 28 deletions(-)
 create mode 100644 build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RemoveDirectoryBackups.cs
 create mode 100644 build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/ReplaceDirectory.cs
 create mode 100644 build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RetryingDirectoryTask.cs
 create mode 100644 tests/Microsoft.Android.Build.BaseTasks-Tests/AndroidSdkTargetsTests.cs
 create mode 100644 tests/Microsoft.Android.Build.BaseTasks-Tests/ReplaceDirectoryTests.cs
 create mode 100644 tests/Microsoft.Android.Build.BaseTasks-Tests/Resources/AndroidSdkTargetsTest.proj

diff --git a/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RemoveDirectoryBackups.cs b/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RemoveDirectoryBackups.cs
new file mode 100644
index 00000000000..0e687a7f387
--- /dev/null
+++ b/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RemoveDirectoryBackups.cs
@@ -0,0 +1,36 @@
+using System;
+using System.IO;
+using Microsoft.Build.Framework;
+
+namespace Xamarin.Android.Tools.BootstrapTasks
+{
+	public sealed class RemoveDirectoryBackups : RetryingDirectoryTask
+	{
+		[Required]
+		public ITaskItem [] Directories { get; set; } = [];
+
+		public override bool Execute ()
+		{
+			if (!ValidateRetryParameters ())
+				return false;
+
+			foreach (var item in Directories) {
+				var directory = NormalizeDirectoryPath (item.ItemSpec);
+				var parentDirectory = Path.GetDirectoryName (directory);
+				if (string.IsNullOrEmpty (parentDirectory) || !Directory.Exists (parentDirectory))
+					continue;
+
+				var directoryName = Path.GetFileName (directory);
+				foreach (var backupDirectory in Directory.GetDirectories (parentDirectory, $"{directoryName}.old-*", SearchOption.TopDirectoryOnly)) {
+					if (!TryDeleteDirectoryWithRetry (backupDirectory, out var deleteError)) {
+						Log.LogWarning (
+							$"Could not remove old directory '{backupDirectory}' after {RetryCount + 1} attempts: " +
+							$"{deleteError.Message}{GetRemainingEntries (backupDirectory)}");
+					}
+				}
+			}
+
+			return !Log.HasLoggedErrors;
+		}
+	}
+}
diff --git a/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/ReplaceDirectory.cs b/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/ReplaceDirectory.cs
new file mode 100644
index 00000000000..53e090f7e67
--- /dev/null
+++ b/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/ReplaceDirectory.cs
@@ -0,0 +1,84 @@
+using System;
+using System.IO;
+using Microsoft.Build.Framework;
+using Microsoft.Build.Utilities;
+
+namespace Xamarin.Android.Tools.BootstrapTasks
+{
+	public class ReplaceDirectory : RetryingDirectoryTask
+	{
+		[Required]
+		public string SourceDirectory { get; set; } = "";
+
+		[Required]
+		public string DestinationDirectory { get; set; } = "";
+
+		[Required]
+		public string RequiredFile { get; set; } = "";
+
+		public override bool Execute ()
+		{
+			if (!ValidateRetryParameters ())
+				return false;
+
+			var sourceDirectory = NormalizeDirectoryPath (SourceDirectory);
+			var destinationDirectory = NormalizeDirectoryPath (DestinationDirectory);
+			if (!Directory.Exists (sourceDirectory)) {
+				Log.LogError ($"Source directory '{sourceDirectory}' does not exist.");
+				return false;
+			}
+			if (!File.Exists (Path.Combine (sourceDirectory, RequiredFile))) {
+				Log.LogError ($"Source directory '{sourceDirectory}' does not contain required file '{RequiredFile}'.");
+				return false;
+			}
+
+			var parentDirectory = Path.GetDirectoryName (destinationDirectory);
+			if (!string.IsNullOrEmpty (parentDirectory))
+				Directory.CreateDirectory (parentDirectory);
+
+			string backupDirectory = null;
+			try {
+				if (Directory.Exists (destinationDirectory)) {
+					var candidate = destinationDirectory + $".old-{Guid.NewGuid ():N}";
+					MoveDirectoryWithRetry (destinationDirectory, candidate);
+					backupDirectory = candidate;
+				}
+
+				try {
+					MoveDirectoryWithRetry (sourceDirectory, destinationDirectory);
+				} catch {
+					RestoreBackup (backupDirectory, destinationDirectory);
+					throw;
+				}
+			} catch (Exception e) {
+				Log.LogError ($"Failed to replace directory '{destinationDirectory}' with '{sourceDirectory}': {e.Message}");
+				return false;
+			}
+
+			if (backupDirectory != null && !TryDeleteDirectoryWithRetry (backupDirectory, out var deleteError)) {
+				Log.LogWarning (
+					$"Installed '{destinationDirectory}', but could not remove old directory '{backupDirectory}' after {RetryCount + 1} attempts: " +
+					$"{deleteError.Message}{GetRemainingEntries (backupDirectory)}");
+			}
+
+			return !Log.HasLoggedErrors;
+		}
+
+		void RestoreBackup (string backupDirectory, string destinationDirectory)
+		{
+			if (backupDirectory == null || !Directory.Exists (backupDirectory))
+				return;
+			if (Directory.Exists (destinationDirectory)) {
+				Log.LogError ($"Cannot restore previous directory from '{backupDirectory}' because '{destinationDirectory}' exists.");
+				return;
+			}
+			try {
+				MoveDirectoryWithRetry (backupDirectory, destinationDirectory);
+				Log.LogMessage (MessageImportance.Normal, $"Restored previous directory from '{backupDirectory}'.");
+			} catch (Exception e) {
+				Log.LogError ($"Failed to restore previous directory from '{backupDirectory}': {e.Message}");
+			}
+		}
+
+	}
+}
diff --git a/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RetryingDirectoryTask.cs b/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RetryingDirectoryTask.cs
new file mode 100644
index 00000000000..895004ef9ed
--- /dev/null
+++ b/build-tools/Xamarin.Android.Tools.BootstrapTasks/Xamarin.Android.Tools.BootstrapTasks/RetryingDirectoryTask.cs
@@ -0,0 +1,103 @@
+using System;
+using System.IO;
+using System.Linq;
+using System.Threading;
+using Microsoft.Android.Build.Tasks;
+using Microsoft.Build.Framework;
+using Microsoft.Build.Utilities;
+
+namespace Xamarin.Android.Tools.BootstrapTasks
+{
+	public abstract class RetryingDirectoryTask : Task
+	{
+		public int RetryCount { get; set; } = 10;
+
+		public int RetryDelayMilliseconds { get; set; } = 200;
+
+		protected bool ValidateRetryParameters ()
+		{
+			if (RetryCount < 0) {
+				Log.LogError ($"{nameof (RetryCount)} must be greater than or equal to zero.");
+				return false;
+			}
+			if (RetryDelayMilliseconds < 0) {
+				Log.LogError ($"{nameof (RetryDelayMilliseconds)} must be greater than or equal to zero.");
+				return false;
+			}
+			return true;
+		}
+
+		protected void MoveDirectoryWithRetry (string source, string destination)
+		{
+			for (int attempt = 0; ; attempt++) {
+				try {
+					MoveDirectory (source, destination);
+					return;
+				} catch (Exception e) when ((e is IOException || e is UnauthorizedAccessException) && attempt < RetryCount) {
+					Log.LogMessage (
+						MessageImportance.Normal,
+						$"Could not move directory '{source}' to '{destination}' (attempt {attempt + 1} of {RetryCount + 1}): {e.Message} Retrying.");
+					Delay (RetryDelayMilliseconds * (attempt + 1));
+				}
+			}
+		}
+
+		protected bool TryDeleteDirectoryWithRetry (string directory, out Exception error)
+		{
+			error = null;
+			for (int attempt = 0; ; attempt++) {
+				try {
+					if (!Directory.Exists (directory))
+						return true;
+					if (Path.DirectorySeparatorChar == '\\')
+						Files.SetDirectoryWriteable (directory);
+					DeleteDirectory (directory);
+					return true;
+				} catch (DirectoryNotFoundException) {
+					return true;
+				} catch (Exception e) when (e is IOException || e is UnauthorizedAccessException) {
+					error = e;
+					if (attempt >= RetryCount)
+						return false;
+					Log.LogMessage (
+						MessageImportance.Normal,
+						$"Could not remove directory '{directory}' (attempt {attempt + 1} of {RetryCount + 1}): {e.Message} Retrying.");
+					Delay (RetryDelayMilliseconds * (attempt + 1));
+				}
+			}
+		}
+
+		protected static string GetRemainingEntries (string directory)
+		{
+			try {
+				var entries = Directory.EnumerateFileSystemEntries (directory, "*", SearchOption.AllDirectories)
+					.Take (10)
+					.Select (path => $"'{path}'")
+					.ToArray ();
+				return entries.Length == 0 ? "" : $" Remaining entries: {string.Join (", ", entries)}.";
+			} catch (Exception e) {
+				return $" Remaining entries could not be enumerated: {e.Message}";
+			}
+		}
+
+		protected static string NormalizeDirectoryPath (string directory)
+		{
+			return Path.TrimEndingDirectorySeparator (Path.GetFullPath (directory));
+		}
+
+		protected virtual void MoveDirectory (string source, string destination)
+		{
+			Directory.Move (source, destination);
+		}
+
+		protected virtual void DeleteDirectory (string directory)
+		{
+			Directory.Delete (directory, recursive: true);
+		}
+
+		protected virtual void Delay (int milliseconds)
+		{
+			Thread.Sleep (milliseconds);
+		}
+	}
+}
diff --git a/src/androidsdk/androidsdk.targets b/src/androidsdk/androidsdk.targets
index b9974e08caf..b3028f3f328 100644
--- a/src/androidsdk/androidsdk.targets
+++ b/src/androidsdk/androidsdk.targets
@@ -48,6 +48,8 @@
 
   <UsingTask AssemblyFile="$(BootstrapTasksAssembly)" TaskName="Xamarin.Android.Tools.BootstrapTasks.UnzipDirectoryChildren" TaskFactory="TaskHostFactory" Runtime="NET" />
   <UsingTask AssemblyFile="$(BootstrapTasksAssembly)" TaskName="Xamarin.Android.Tools.BootstrapTasks.EnsureAndroidSdkLicense" TaskFactory="TaskHostFactory" Runtime="NET" />
+  <UsingTask AssemblyFile="$(BootstrapTasksAssembly)" TaskName="Xamarin.Android.Tools.BootstrapTasks.ReplaceDirectory" TaskFactory="TaskHostFactory" Runtime="NET" />
+  <UsingTask AssemblyFile="$(BootstrapTasksAssembly)" TaskName="Xamarin.Android.Tools.BootstrapTasks.RemoveDirectoryBackups" TaskFactory="TaskHostFactory" Runtime="NET" />
 
   <!--
     Catalog of platform APIs. Each item is downloaded as `<Identity>.zip`.
@@ -275,7 +277,7 @@
   </ItemGroup>
 
   <Target Name="_AddPlatformPackagesToInstall"
-      BeforeTargets="_DownloadAndroidSdkPackages;_ExtractAndroidSdkPackages;_GenerateAndroidPackageXmls;_CleanAndroidSdkComponents">
+      BeforeTargets="_DownloadAndroidSdkPackages;_ExtractAndroidSdkPackages;_GenerateAndroidPackageXmls;_CleanAndroidSdkPackageBackups;_CleanAndroidSdkComponents">
     <ItemGroup>
       <_AndroidSdkPackage Include="@(_PlatformPackage->'%(Identity).zip')"
           Condition=" '$(_InstallAllPlatforms)' == 'true' or
@@ -332,28 +334,25 @@
       <_StripComponents>%(_AndroidSdkPackage.StripComponents)</_StripComponents>
       <_StripComponents Condition=" '$(_StripComponents)' == '' ">1</_StripComponents>
       <_ZipPath>$([System.IO.Path]::Combine('$(AndroidToolchainCacheDirectory)', '%(_AndroidSdkPackage.Identity)'))</_ZipPath>
-      <_StagingDir>%(_AndroidSdkPackage.Destination).staging</_StagingDir>
-      <_DestDir>%(_AndroidSdkPackage.Destination)</_DestDir>
+      <_DestDir>$([System.Text.RegularExpressions.Regex]::Replace('%(_AndroidSdkPackage.Destination)', '[\\/]+$', ''))</_DestDir>
+      <_StagingDir>$(_DestDir).staging-$([System.Guid]::NewGuid().ToString('N'))</_StagingDir>
       <_NoSubdirectory Condition=" '$(_StripComponents)' == '1' ">false</_NoSubdirectory>
       <_NoSubdirectory Condition=" '$(_StripComponents)' == '0' ">true</_NoSubdirectory>
     </PropertyGroup>
-    <RemoveDir Directories="$(_DestDir);$(_StagingDir)" />
-    <MakeDir Directories="$(_DestDir)" />
+    <MakeDir Directories="$(_StagingDir)" />
     <!-- Windows: LibZipSharp via UnzipDirectoryChildren BootstrapTask. -->
     <UnzipDirectoryChildren
         Condition=" '$(HostOS)' == 'Windows' "
         SourceFiles="$(_ZipPath)"
-        DestinationFolder="$(_DestDir)"
+        DestinationFolder="$(_StagingDir)"
         NoSubdirectory="$(_NoSubdirectory)"
     />
     <!--
       Unix: `unzip` (preserves symlinks; LibZipSharp does not, which the NDK needs)
-      into a sibling .staging directory, then `<Move/>` every file into
-      $(_DestDir). When StripComponents=1, glob from inside the single
-      top-level directory of the zip so that `%(RecursiveDir)` already excludes
-      it - no path-rewriting required. Empty staging dirs are pruned afterwards.
+      into a unique sibling staging directory. When StripComponents=1, install
+      the single top-level directory; otherwise install the staging directory
+      itself. The staged directory atomically replaces the destination.
     -->
-    <MakeDir Condition=" '$(HostOS)' != 'Windows' " Directories="$(_StagingDir)" />
     <Exec
         Condition=" '$(HostOS)' != 'Windows' "
         Command="unzip -q -o &quot;$(_ZipPath)&quot; -d &quot;$(_StagingDir)&quot;"
@@ -362,27 +361,34 @@
       <_StagedTopDir Remove="@(_StagedTopDir)" />
       <_StagedTopDir Include="$([System.IO.Directory]::GetDirectories('$(_StagingDir)'))" />
     </ItemGroup>
-    <PropertyGroup Condition=" '$(HostOS)' != 'Windows' ">
-      <_GlobRoot Condition=" '$(_StripComponents)' == '1' ">@(_StagedTopDir)</_GlobRoot>
-      <_GlobRoot Condition=" '$(_StripComponents)' == '0' ">$(_StagingDir)</_GlobRoot>
+    <PropertyGroup>
+      <_InstallSourceDir Condition=" '$(HostOS)' == 'Windows' Or '$(_StripComponents)' == '0' ">$(_StagingDir)</_InstallSourceDir>
+      <_InstallSourceDir Condition=" '$(HostOS)' != 'Windows' And '$(_StripComponents)' == '1' ">@(_StagedTopDir)</_InstallSourceDir>
     </PropertyGroup>
-    <ItemGroup Condition=" '$(HostOS)' != 'Windows' And '$(_GlobRoot)' != '' ">
-      <_StagedFile Remove="@(_StagedFile)" />
-      <_StagedFile Include="$(_GlobRoot)\**\*" />
-    </ItemGroup>
-    <Move
-        Condition=" '$(HostOS)' != 'Windows' "
-        SourceFiles="@(_StagedFile)"
-        DestinationFiles="@(_StagedFile->'$(_DestDir)\%(RecursiveDir)%(Filename)%(Extension)')"
-    />
-    <RemoveDir Condition=" '$(HostOS)' != 'Windows' " Directories="$(_StagingDir)" />
-    <Error
-        Condition=" !Exists('$(_DestDir)\source.properties') "
-        Text="Expected Android SDK package '%(_AndroidSdkPackage.Identity)' to extract source.properties under '$(_DestDir)'."
+    <ReplaceDirectory
+        SourceDirectory="$(_InstallSourceDir)"
+        DestinationDirectory="$(_DestDir)"
+        RequiredFile="source.properties"
     />
+    <RemoveDir Condition=" Exists('$(_StagingDir)') " Directories="$(_StagingDir)" />
     <!-- Unzip preserves archive mtimes, so refresh the sentinel used by MSBuild Outputs. -->
     <Touch Files="$(_DestDir)\source.properties" />
     <Touch Files="$(_DestDir)\.extracted-%(_AndroidSdkPackage.Identity)-%(_AndroidSdkPackage.Hash)" AlwaysCreate="true" />
+    <OnError ExecuteTargets="_CleanAndroidSdkPackageStaging" />
+  </Target>
+
+  <Target Name="_CleanAndroidSdkPackageStaging">
+    <RemoveDir
+        Condition=" '$(_StagingDir)' != '' And Exists('$(_StagingDir)') "
+        Directories="$(_StagingDir)"
+        ContinueOnError="WarnAndContinue"
+    />
+  </Target>
+
+  <Target Name="_CleanAndroidSdkPackageBackups"
+      AfterTargets="_ExtractAndroidSdkPackages"
+      BeforeTargets="_CleanAndroidSdkComponents">
+    <RemoveDirectoryBackups Directories="@(_AndroidSdkPackage->'%(Destination)')" />
   </Target>
 
   <!--
@@ -411,7 +417,7 @@
 
   <Target Name="_InstallAndroidSdkComponents"
       BeforeTargets="Build"
-      DependsOnTargets="_ExtractAndroidSdkPackages;_GenerateAndroidPackageXmls"
+      DependsOnTargets="_ExtractAndroidSdkPackages;_CleanAndroidSdkPackageBackups;_GenerateAndroidPackageXmls"
   />
 
   <Target Name="_AcceptAndroidSdkLicenses"
diff --git a/tests/Microsoft.Android.Build.BaseTasks-Tests/AndroidSdkTargetsTests.cs b/tests/Microsoft.Android.Build.BaseTasks-Tests/AndroidSdkTargetsTests.cs
new file mode 100644
index 00000000000..db2b5410b11
--- /dev/null
+++ b/tests/Microsoft.Android.Build.BaseTasks-Tests/AndroidSdkTargetsTests.cs
@@ -0,0 +1,116 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.IO.Compression;
+using System.Linq;
+using NUnit.Framework;
+using Xamarin.Android.Tools.BootstrapTasks;
+
+namespace Microsoft.Android.Build.BaseTasks.Tests
+{
+	[TestFixture]
+	public class AndroidSdkTargetsTests
+	{
+		string tempDirectory;
+
+		[SetUp]
+		public void SetUp ()
+		{
+			tempDirectory = Path.Combine (Path.GetTempPath (), $"{nameof (AndroidSdkTargetsTests)}-{Guid.NewGuid ():N}");
+			Directory.CreateDirectory (tempDirectory);
+		}
+
+		[TearDown]
+		public void TearDown ()
+		{
+			if (Directory.Exists (tempDirectory))
+				Directory.Delete (tempDirectory, recursive: true);
+		}
+
+		[Test]
+		public void ExtractAndroidSdkPackageAtomicallyReplacesDestinationAndRemainsIncremental ()
+		{
+			var packageRoot = Path.Combine (tempDirectory, "package");
+			var archiveRoot = Path.Combine (packageRoot, "android-test");
+			var cacheDirectory = Path.Combine (tempDirectory, "cache");
+			var sdkDirectory = Path.Combine (tempDirectory, "sdk");
+			var destination = Path.Combine (sdkDirectory, "platforms", "android-test");
+			Directory.CreateDirectory (archiveRoot);
+			Directory.CreateDirectory (cacheDirectory);
+			Directory.CreateDirectory (Path.Combine (destination, "data", "res"));
+			File.WriteAllText (Path.Combine (archiveRoot, "source.properties"), "Pkg.Revision=1");
+			File.WriteAllText (Path.Combine (archiveRoot, "android.jar"), "new");
+			File.WriteAllText (Path.Combine (destination, "data", "res", "old.xml"), "old");
+			ZipFile.CreateFromDirectory (packageRoot, Path.Combine (cacheDirectory, "fake-platform.zip"));
+
+			RunMsbuild (cacheDirectory, sdkDirectory, destination + Path.DirectorySeparatorChar, expectSuccess: true);
+
+			FileAssert.Exists (Path.Combine (destination, "android.jar"));
+			FileAssert.DoesNotExist (Path.Combine (destination, "data", "res", "old.xml"));
+			FileAssert.Exists (Path.Combine (destination, ".extracted-fake-platform.zip-TESTHASH"));
+			Assert.IsFalse (Directory.GetDirectories (Path.GetDirectoryName (destination), "android-test.old-*").Any (), "Old package backups should be removed.");
+			Assert.IsFalse (Directory.GetDirectories (Path.GetDirectoryName (destination), "android-test.staging-*").Any (), "Staging directories should be removed.");
+
+			var marker = Path.Combine (destination, "incremental-marker");
+			var staleBackup = destination + ".old-stale";
+			File.WriteAllText (marker, "");
+			Directory.CreateDirectory (staleBackup);
+			File.WriteAllText (Path.Combine (staleBackup, "stale.txt"), "");
+			RunMsbuild (cacheDirectory, sdkDirectory, destination + Path.DirectorySeparatorChar, expectSuccess: true);
+			FileAssert.Exists (marker);
+			Assert.IsFalse (Directory.Exists (staleBackup), "Incremental builds should clean stale package backups.");
+		}
+
+		[Test]
+		public void ExtractAndroidSdkPackageCleansStagingAfterExtractionFailure ()
+		{
+			var cacheDirectory = Path.Combine (tempDirectory, "cache");
+			var sdkDirectory = Path.Combine (tempDirectory, "sdk");
+			var destination = Path.Combine (sdkDirectory, "platforms", "android-test");
+			Directory.CreateDirectory (cacheDirectory);
+			File.WriteAllText (Path.Combine (cacheDirectory, "fake-platform.zip"), "not a zip");
+
+			RunMsbuild (cacheDirectory, sdkDirectory, destination, expectSuccess: false);
+
+			var destinationParent = Path.GetDirectoryName (destination);
+			if (Directory.Exists (destinationParent))
+				Assert.IsFalse (Directory.GetDirectories (destinationParent, "android-test.staging-*").Any (), "Failed extraction should clean its staging directory.");
+		}
+
+		void RunMsbuild (string cacheDirectory, string sdkDirectory, string destination, bool expectSuccess)
+		{
+			var repositoryRoot = Path.GetFullPath (Path.Combine (TestContext.CurrentContext.TestDirectory, "..", ".."));
+			var project = Path.Combine (repositoryRoot, "tests", "Microsoft.Android.Build.BaseTasks-Tests", "Resources", "AndroidSdkTargetsTest.proj");
+			var hostOS = OperatingSystem.IsWindows () ? "Windows" : OperatingSystem.IsMacOS () ? "Darwin" : "Linux";
+			var startInfo = new ProcessStartInfo ("dotnet") {
+				RedirectStandardError = true,
+				RedirectStandardOutput = true,
+				UseShellExecute = false,
+			};
+			startInfo.ArgumentList.Add ("msbuild");
+			startInfo.ArgumentList.Add (project);
+			startInfo.ArgumentList.Add ("-nologo");
+			startInfo.ArgumentList.Add ("-t:_InstallAndroidSdkComponents");
+			startInfo.ArgumentList.Add ("-v:minimal");
+			startInfo.ArgumentList.Add ($"-p:TestHostOS={hostOS}");
+			startInfo.ArgumentList.Add ($"-p:TestSdkDirectory={sdkDirectory}");
+			startInfo.ArgumentList.Add ($"-p:TestNdkDirectory={Path.Combine (tempDirectory, "ndk")}");
+			startInfo.ArgumentList.Add ($"-p:TestCacheDirectory={cacheDirectory}");
+			startInfo.ArgumentList.Add ($"-p:TestDestination={destination}");
+			startInfo.ArgumentList.Add ($"-p:TestBootstrapTasksAssembly={typeof (ReplaceDirectory).Assembly.Location}");
+
+			using (var process = Process.Start (startInfo)) {
+				Assert.IsNotNull (process, "Could not start dotnet msbuild.");
+				if (process == null)
+					return;
+				var standardOutputTask = process.StandardOutput.ReadToEndAsync ();
+				var standardErrorTask = process.StandardError.ReadToEndAsync ();
+				process.WaitForExit ();
+				var standardOutput = standardOutputTask.GetAwaiter ().GetResult ();
+				var standardError = standardErrorTask.GetAwaiter ().GetResult ();
+				var expectedExitCode = expectSuccess ? 0 : 1;
+				Assert.AreEqual (expectedExitCode, process.ExitCode, standardOutput + Environment.NewLine + standardError);
+			}
+		}
+	}
+}
diff --git a/tests/Microsoft.Android.Build.BaseTasks-Tests/Microsoft.Android.Build.BaseTasks-Tests.csproj b/tests/Microsoft.Android.Build.BaseTasks-Tests/Microsoft.Android.Build.BaseTasks-Tests.csproj
index d557d063f94..b6913e6e024 100644
--- a/tests/Microsoft.Android.Build.BaseTasks-Tests/Microsoft.Android.Build.BaseTasks-Tests.csproj
+++ b/tests/Microsoft.Android.Build.BaseTasks-Tests/Microsoft.Android.Build.BaseTasks-Tests.csproj
@@ -20,6 +20,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\build-tools\Xamarin.Android.Tools.BootstrapTasks\Xamarin.Android.Tools.BootstrapTasks.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.Android.Build.BaseTasks\Microsoft.Android.Build.BaseTasks.csproj" />
   </ItemGroup>
 
diff --git a/tests/Microsoft.Android.Build.BaseTasks-Tests/ReplaceDirectoryTests.cs b/tests/Microsoft.Android.Build.BaseTasks-Tests/ReplaceDirectoryTests.cs
new file mode 100644
index 00000000000..f60521c56de
--- /dev/null
+++ b/tests/Microsoft.Android.Build.BaseTasks-Tests/ReplaceDirectoryTests.cs
@@ -0,0 +1,179 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using Microsoft.Android.Build.BaseTasks.Tests.Utilities;
+using Microsoft.Build.Framework;
+using NUnit.Framework;
+using Xamarin.Android.Tools.BootstrapTasks;
+
+namespace Microsoft.Android.Build.BaseTasks.Tests
+{
+	[TestFixture]
+	public class ReplaceDirectoryTests
+	{
+		string tempDirectory;
+		List<BuildErrorEventArgs> errors;
+		List<BuildWarningEventArgs> warnings;
+		List<BuildMessageEventArgs> messages;
+
+		[SetUp]
+		public void SetUp ()
+		{
+			tempDirectory = Path.Combine (Path.GetTempPath (), $"{nameof (ReplaceDirectoryTests)}-{Guid.NewGuid ():N}");
+			Directory.CreateDirectory (tempDirectory);
+			errors = new List<BuildErrorEventArgs> ();
+			warnings = new List<BuildWarningEventArgs> ();
+			messages = new List<BuildMessageEventArgs> ();
+		}
+
+		[TearDown]
+		public void TearDown ()
+		{
+			if (Directory.Exists (tempDirectory))
+				Directory.Delete (tempDirectory, recursive: true);
+		}
+
+		[Test]
+		public void ReplacesNonEmptyDestinationAndRetriesBackupCleanup ()
+		{
+			var source = Path.Combine (tempDirectory, "source");
+			var destination = Path.Combine (tempDirectory, "platforms", "android-36.1");
+			Directory.CreateDirectory (source);
+			File.WriteAllText (Path.Combine (source, "source.properties"), "Pkg.Revision=1");
+			File.WriteAllText (Path.Combine (source, "android.jar"), "new");
+			Directory.CreateDirectory (Path.Combine (destination, "data", "res"));
+			File.WriteAllText (Path.Combine (destination, "data", "res", "old.xml"), "old");
+
+			var task = new RetryDeleteReplaceDirectory {
+				BuildEngine = new MockBuildEngine (TestContext.Out, errors, warnings, messages),
+				SourceDirectory = source,
+				DestinationDirectory = destination,
+				RequiredFile = "source.properties",
+				FailuresBeforeSuccess = 2,
+				RetryDelayMilliseconds = 0,
+			};
+
+			Assert.IsTrue (task.Execute (), "Task should succeed.");
+			Assert.AreEqual (3, task.DeleteAttempts, "Backup cleanup should be retried.");
+			Assert.IsFalse (Directory.Exists (source), "Source directory should be moved.");
+			FileAssert.Exists (Path.Combine (destination, "android.jar"));
+			FileAssert.DoesNotExist (Path.Combine (destination, "data", "res", "old.xml"));
+			Assert.IsTrue (task.DeletedDirectories.All (path => path.StartsWith (destination + ".old-", StringComparison.Ordinal)), "The live destination should be renamed, not recursively deleted.");
+			Assert.IsTrue (messages.Any (message => message.Message.Contains ("Retrying.", StringComparison.Ordinal)), "Expected retry diagnostics.");
+			Assert.IsEmpty (warnings);
+			Assert.IsEmpty (errors);
+		}
+
+		[Test]
+		public void ReportsBackupCleanupFailureWithoutDiscardingInstalledDirectory ()
+		{
+			var source = Path.Combine (tempDirectory, "source");
+			var destination = Path.Combine (tempDirectory, "destination");
+			Directory.CreateDirectory (source);
+			File.WriteAllText (Path.Combine (source, "source.properties"), "Pkg.Revision=1");
+			Directory.CreateDirectory (Path.Combine (destination, "data", "res"));
+			File.WriteAllText (Path.Combine (destination, "data", "res", "old.xml"), "old");
+
+			var task = new RetryDeleteReplaceDirectory {
+				BuildEngine = new MockBuildEngine (TestContext.Out, errors, warnings, messages),
+				SourceDirectory = source,
+				DestinationDirectory = destination,
+				RequiredFile = "source.properties",
+				FailuresBeforeSuccess = int.MaxValue,
+				RetryCount = 1,
+				RetryDelayMilliseconds = 0,
+			};
+
+			Assert.IsTrue (task.Execute (), "A committed installation should not fail because backup cleanup failed.");
+			FileAssert.Exists (Path.Combine (destination, "source.properties"));
+			Assert.IsTrue (warnings.Any (warning =>
+				warning.Message.Contains ("could not remove old directory", StringComparison.Ordinal) &&
+				warning.Message.Contains ("Directory not empty.", StringComparison.Ordinal) &&
+				warning.Message.Contains ("Remaining entries:", StringComparison.Ordinal)), "Expected actionable cleanup diagnostics.");
+			Assert.IsEmpty (errors);
+		}
+
+		[Test]
+		public void MissingRequiredFilePreservesDestination ()
+		{
+			var source = Path.Combine (tempDirectory, "source");
+			var destination = Path.Combine (tempDirectory, "destination");
+			Directory.CreateDirectory (source);
+			Directory.CreateDirectory (destination);
+			File.WriteAllText (Path.Combine (destination, "original.txt"), "original");
+
+			var task = new ReplaceDirectory {
+				BuildEngine = new MockBuildEngine (TestContext.Out, errors, warnings, messages),
+				SourceDirectory = source,
+				DestinationDirectory = destination,
+				RequiredFile = "source.properties",
+			};
+
+			Assert.IsFalse (task.Execute (), "Task should fail.");
+			FileAssert.Exists (Path.Combine (destination, "original.txt"));
+			Assert.IsTrue (Directory.Exists (source), "Invalid source should not be moved.");
+			Assert.IsTrue (errors.Any (error => error.Message.Contains ("source.properties", StringComparison.Ordinal)), "Expected missing-file diagnostics.");
+		}
+
+		[Test]
+		public void MoveFailureRestoresDestination ()
+		{
+			var source = Path.Combine (tempDirectory, "source");
+			var destination = Path.Combine (tempDirectory, "destination");
+			Directory.CreateDirectory (source);
+			File.WriteAllText (Path.Combine (source, "source.properties"), "Pkg.Revision=1");
+			Directory.CreateDirectory (destination);
+			File.WriteAllText (Path.Combine (destination, "original.txt"), "original");
+
+			var task = new FailInstallReplaceDirectory (source) {
+				BuildEngine = new MockBuildEngine (TestContext.Out, errors, warnings, messages),
+				SourceDirectory = source,
+				DestinationDirectory = destination,
+				RequiredFile = "source.properties",
+				RetryCount = 0,
+			};
+
+			Assert.IsFalse (task.Execute (), "Task should fail.");
+			FileAssert.Exists (Path.Combine (destination, "original.txt"));
+			Assert.IsTrue (Directory.Exists (source), "Source should remain available after rollback.");
+			Assert.IsTrue (messages.Any (message => message.Message.Contains ("Restored previous directory", StringComparison.Ordinal)), "Expected rollback diagnostics.");
+			Assert.IsNotEmpty (errors);
+		}
+
+		sealed class RetryDeleteReplaceDirectory : ReplaceDirectory
+		{
+			public int DeleteAttempts { get; private set; }
+
+			public int FailuresBeforeSuccess { get; set; }
+
+			public List<string> DeletedDirectories { get; } = new List<string> ();
+
+			protected override void DeleteDirectory (string directory)
+			{
+				DeleteAttempts++;
+				DeletedDirectories.Add (directory);
+				if (DeleteAttempts <= FailuresBeforeSuccess)
+					throw new IOException ("Directory not empty.");
+				base.DeleteDirectory (directory);
+			}
+		}
+
+		sealed class FailInstallReplaceDirectory : ReplaceDirectory
+		{
+			readonly string sourceDirectory;
+
+			public FailInstallReplaceDirectory (string sourceDirectory)
+			{
+				this.sourceDirectory = new DirectoryInfo (sourceDirectory).FullName;
+			}
+
+			protected override void MoveDirectory (string source, string destination)
+			{
+				if (string.Equals (source, sourceDirectory, StringComparison.Ordinal))
+					throw new IOException ("Install move failed.");
+				base.MoveDirectory (source, destination);
+			}
+		}
+	}
+}
diff --git a/tests/Microsoft.Android.Build.BaseTasks-Tests/Resources/AndroidSdkTargetsTest.proj b/tests/Microsoft.Android.Build.BaseTasks-Tests/Resources/AndroidSdkTargetsTest.proj
new file mode 100644
index 00000000000..ab04ef46f1b
--- /dev/null
+++ b/tests/Microsoft.Android.Build.BaseTasks-Tests/Resources/AndroidSdkTargetsTest.proj
@@ -0,0 +1,22 @@
+<Project>
+  <PropertyGroup>
+    <HostOS>$(TestHostOS)</HostOS>
+    <AndroidSdkFullPath>$(TestSdkDirectory)</AndroidSdkFullPath>
+    <AndroidNdkDirectory>$(TestNdkDirectory)</AndroidNdkDirectory>
+    <AndroidToolchainCacheDirectory>$(TestCacheDirectory)</AndroidToolchainCacheDirectory>
+    <BootstrapTasksAssembly>$(TestBootstrapTasksAssembly)</BootstrapTasksAssembly>
+  </PropertyGroup>
+
+  <Import Project="..\..\..\src\androidsdk\androidsdk.targets" />
+
+  <ItemGroup>
+    <_AndroidSdkPackage Remove="@(_AndroidSdkPackage)" />
+    <_AndroidSdkPackage Include="fake-platform.zip">
+      <Hash>TESTHASH</Hash>
+      <Destination>$(TestDestination)</Destination>
+    </_AndroidSdkPackage>
+  </ItemGroup>
+
+  <Target Name="_AddPlatformPackagesToInstall" />
+  <Target Name="_DownloadAndroidSdkPackages" />
+</Project>