클라이언트 재설정 - .NET SDK
이 페이지의 내용
개요
버전 10.17.0의 새로운 기능
클라이언트 재설정 오류는 클라이언트 영역이 애플리케이션 백엔드와 데이터를 동기화할 수 없는 시나리오입니다. 이 상태의 클라이언트는 계속 로컬에서 실행하고 데이터를 저장할 수 있지만 클라이언트 재설정을 수행할 때까지 동기화 변경 집합을 보내거나 받을 수 없습니다. Realm SDK는 대부분의 시나리오에서 클라이언트 재설정을 자동으로 처리하는 메서드를 제공합니다.
클라이언트 재설정 전략
클라이언트 재설정 시나리오는 서버의 기록이 클라이언트의 기록과 호환되지 않을 때 발생합니다. 클라이언트 재설정의 가장 일반적인 원인은 클라이언트재설정에 설명되어 있습니다.
.NET SDK에서는 FlexibleSyncConfiguration 및 PartitionSyncConfiguration 에서 클라이언트 재설정 전략을 지정할 수 있습니다. ClientResetHandler 속성은 다음 중 하나로 설정할 수 있습니다.
Handler | 전략 | 참고 사항 |
---|---|---|
동기화되지 않은 모든 로컬 변경 사항 복구 | 복구가 실패하면 이 핸들러는 DiscardUnsyncedChangesHandler 로 돌아가서 동기화되지 않은 모든 로컬 변경 사항을 삭제합니다. DiscardUnsyncedChangesHandler 복구가 실패하면 핸들러는 수동 복구 전략을 구현해야 하는 ManualRecoveryHandler 상태로 되돌아갑니다. | |
동기화되지 않은 모든 로컬 변경 사항 복구 | 복구가 실패하면 이 핸들러는 ManualRecoveryHandler 로 대체되며, 이 경우 수동 복구 전략을 구현해야 합니다. | |
동기화되지 않은 변경 내용 삭제 | 이 전략은 마지막 동기화에 성공한 이후 이루어진 모든 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제 합니다. | |
수동 복구 | 고유한 복구 전략을 구현할 수 있는 방법을 제공합니다. |
다음 섹션에서는 클라이언트 재설정을 처리하기 위한 다양한 전략과 각 ClientResetHandlers
를 사용하는 방법에 대해 설명합니다.
동기화되지 않은 로컬 변경 사항 복구
손상적인 스키마 변경을 포함하지 않는 클라이언트 재설정에서 SDK는 클라이언트 재설정 전에 동기화되지 않은 로컬에서 생성된 객체를 통합합니다. 다음 규칙은 백엔드와 클라이언트가 모두 동일한 객체를 변경할 때 충돌을 해결하는 방법을 결정합니다.
객체가 서버에서 삭제되었지만 복구 클라이언트에서 수정된 경우 삭제가 우선적으로 적용되고 클라이언트는 업데이트를 삭제합니다.
복구 클라이언트에서는 객체가 삭제되었지만 서버에서는 삭제되지 않은 경우 클라이언트는 삭제 명령을 적용합니다.
동일한 필드에 대한 업데이트가 충돌하는 경우 클라이언트 업데이트가 적용됩니다.
중요
호환성이 손상되는 변경
복구 프로세스 는 손상적인 스키마 변경을 처리하다 할 수 없습니다. 예를 예시 하나 이상의 Realm 객체 클래스를 비가산적으로 변경하면 복구 프로세스 가 실패합니다. 이 경우 사용자는 클라이언트 앱 을 업데이트 해야 합니다. 호환성이 손상되는 변경에 대한 자세한 내용은 단절적 변경과 단절 적이지 않은 변경 빠른 참조를 참조하세요.
동기화되지 않은 로컬 데이터를 자동으로 복구하려고 시도하는 두 가지 클라이언트 재설정 핸들러는 RecoverOrDiscardUnsyncedChangesHandler
및 RecoverUnsyncedChangesHandler
입니다.
RecoveryOrDiscardUnsyncedChangesHandler
이 핸들러는 가장 강력한 복구 프로세스를 제공하는 기본 핸들러입니다. 자동 복구 프로세스가 실패하면 동기화되지 않은 변경 사항 삭제 섹션 에 설명된 DiscardLocalReset
전략으로 돌아갑니다. 이 프로세스가 실패하면 수동 복구 섹션 에 설명된 수동 재설정 전략으로 다시 돌아갑니다. 이 핸들러는 다음과 같은 콜백 메서드를 제공합니다.
클라이언트 재설정 전에 SDK가 호출하는 OnBeforeReset 입니다. 이 콜백을 사용하여 클라이언트 재설정이 시작되기 전에 사용자에게 알릴 수 있습니다.
자동 재설정이 성공적으로 완료된 경우에만 SDK가 호출하는 OnAfterRecovery입니다. 이를 사용하여 클라이언트 재설정 이 완료되었음을 사용자에게 알릴 수 있습니다.
OnAfterDiscard - 자동 클라이언트 재설정 이 실패 하고 로컬 삭제 전략이 성공한 경우에만 SDK가 호출합니다. 폐기 전략이 실패하면 이 콜백 이 호출되지 않습니다.
자동 복구 및 삭제 전략이 실패한 경우에만 SDK가 호출하는 수동 재설정 폴백( ManualResetFallback)입니다. 이 콜백 을 구현 하여 재설정 실패를 처리하다 합니다. 여기서의 로직은 수동 복구 핸들러에 대해 설명된 로직과 유사해야 합니다 .
다음 예제에서는 이러한 각 콜백을 사용하는 방법을 보여 줍니다.
var conf = new FlexibleSyncConfiguration(user) { ClientResetHandler = new RecoverOrDiscardUnsyncedChangesHandler { // The following callbacks are optional OnBeforeReset = (beforeReset) => { // Executed before the client reset begins // Can be used to notify the user that a reset is going // to happen }, OnAfterRecovery = (beforeReset, afterReset) => { // Executed after the client reset is complete // Can be used to notify the user that the reset is done }, OnAfterDiscard = (beforeReset, afterReset) => { // Executed if the automatic recovery has failed // but the DiscardUnsyncedChanges fallback has completed // successfully }, ManualResetFallback = (err) => { // Automatic reset failed; handle the reset manually here } } };
RecoveryUnsyncedChangesHandler
RecoverOrDiscardUnsyncedChangesHandler
과 마찬가지로 이 핸들러는 동기화되지 않은 모든 로컬 변경 사항을 자동으로 복구하려고 시도합니다. 그러나 RecoverOrDiscardUnsyncedChangesHandler
과 달리 이 핸들러는 자동 복구가 실패할 경우 DiscardUnsyncedChangesHandler
로 대체되지 않습니다. 대신 수동 복구 섹션 에 설명된 수동 재설정 전략으로 돌아갑니다. 핸들러는 다음과 같은 콜백 메서드를 제공합니다.
OnBeforeReset: 재설정이 시작되기 전에 사용자에게 알리는 데 사용할 수 있습니다.
OnAfterReset: 재설정이 성공적으로 완료되었을 때 사용자에게 알리는 데 사용할 수 있습니다.
수동 재설정 실패를 처리하다 하기 위해 구현 합니다. 여기서의 로직은 수동 복구 핸들러에 대해 설명된 로직과 유사해야 합니다 .
다음 예제에서는 이러한 각 콜백을 사용하는 방법을 보여 줍니다.
var conf = new FlexibleSyncConfiguration(user) { ClientResetHandler = new RecoverUnsyncedChangesHandler { // The following callbacks are optional OnBeforeReset = (beforeReset) => { // Executed before the client reset begins // Can be used to notify the user that a reset is going // to happen }, OnAfterReset = (beforeReset, afterReset) => { // Executed after the client reset is complete // Can be used to notify the user that the reset is done }, ManualResetFallback = (err) => { // Automatic reset failed; handle the reset manually here } } };
동기화되지 않은 변경 내용 삭제
이 전략은 마지막 동기화 에 성공적인 이후 이루어진 모든 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제 합니다. DiscardUnsyncedChangesHandler
을 사용하기로 선택하면 SDK는 영역 을 닫지 않고 알림 이 완전히 작동하면서 로컬 영역 파일 을 동기화 가능한 상태 로 복원합니다. 이 프로세스 가 실패하면 수동 복구 섹션 에 설명된 수동 재설정 전략으로 돌아갑니다. 이 핸들러는 다음과 같은 콜백 메서드를 제공합니다.
클라이언트 재설정 전에 SDK가 호출하는 OnBeforeReset 입니다. 이 콜백을 사용하여 재설정이 시작되기 전에 사용자에게 알릴 수 있습니다.
재설정이 성공적으로 완료된 경우에만 SDK가 호출하는OnAfterReset 입니다. 재설정이 완료되면 이를 사용하여 사용자에게 알릴 수 있습니다.
재설정이 실패할 경우 SDK가 호출하는 수동 재설정 폴백( ManualResetFallback)입니다. 여기서의 로직은 수동 복구 핸들러에 대해 설명된 로직과 유사해야 합니다 .
다음 예는 DiscardUnsyncedChangesHandler
을 구현하는 방법을 보여줍니다.
{
var config = new FlexibleSyncConfiguration(user);
config.ClientResetHandler = new DiscardUnsyncedChangesHandler()
{
// The following callbacks are optional
OnBeforeReset = (beforeReset) =>
{ // Executed before the client reset begins // Can be used to notify the user that a reset is going // to happen },
OnAfterReset = (beforeReset, afterReset) => { // Executed after the client reset is complete // Can be used to notify the user that the reset is done },
ManualResetFallback = (err) =>
{ // Automatic reset failed; handle the reset manually here }
};
try {
var realm = await Realm.GetInstanceAsync(config); }
catch (Exception ex) { Console.WriteLine($@"Error creating or opening the realm file. {ex.Message}"); }
수동 복구
대부분의 경우 클라이언트 재설정에는 다른 전략 중 하나를 사용해야 합니다. 드물게 데이터 복구 프로세스 를 사용자 지정해야 하는 경우에는 수동 복구 핸들러 핸들러를 선택하세요.
참고
폴백
수동 전략은 특수한 경우에만 사용해야 하지만 다른 클라이언트 재설정 처리기는 수동 전략을 사용할 수 있습니다. 해당 핸들러에서 사용하는 로직은 여기에 설명된 로직과 유사합니다.
ManualRecoveryHandler
내에서 기존 Realm을 삭제한 다음 InitiateClientReset() 메서드를 호출합니다.
다음 예제에서는 ManualRecoveryHandler
을 구현하는 방법을 보여 줍니다.
private void SetupRealm()
{
var config = new FlexibleSyncConfiguration(user);
config.ClientResetHandler =
new ManualRecoveryHandler(HandleClientResetError);
var realm = await Realm.GetInstanceAsync(config);
}
private void HandleClientResetError(ClientResetException clientResetException)
{
Console.WriteLine($"Client Reset requested: {clientResetException.Message}");
// Prompt user to perform a client reset immediately. If they don't,
// they won't receive any data from the server until they restart the app
// and all changes they make will be discarded when the app restarts.
var didUserConfirmReset = ShowUserAConfirmationDialog();
if (didUserConfirmReset)
{
// Close the Realm before doing the reset. It must be
// deleted as part of the reset.
fsRealm.Dispose();
// perform the client reset
var didReset = clientResetException.InitiateClientReset();
if (didReset)
{
// Navigate the user back to the main page or reopen the
// the Realm and reinitialize the current page
}
else
{
// Reset failed - notify user that they'll need to
// update the app
}
}
}
클라이언트 재설정 처리 테스트
Device Sync를 종료했다가 다시 활성화하여 애플리케이션의 클라이언트 재설정 처리를 수동으로 테스트할 수 있습니다.
동기화를 종료했다가 다시 허용하면 이전에 동기화로 연결한 클라이언트는 클라이언트 재설정을 수행할 때까지 연결할 수 없습니다. 동기화를 종료하면 클라이언트의 동기화를 허용하는 메타데이터가 서버에서 삭제됩니다. 클라이언트는 서버에서 영역의 새 복사본을 다운로드해야 합니다. 서버는 이러한 클라이언트에 클라이언트 재설정 오류를 보냅니다. 따라서 동기화를 종료하면 trigger 클라이언트 재설정 조건이 됩니다.
클라이언트 재설정 처리를 테스트하려면 다음을 수행합니다.
클라이언트 애플리케이션에서 데이터를 쓰고 동기화될 때까지 기다립니다.
Realm Mobile Sync를 종료했다가 다시 활성화합니다.
클라이언트 앱을 다시 실행합니다. 앱이 서버에 연결하려고 할 때 클라이언트 재설정 오류가 발생해야 합니다.
경고
클라이언트 애플리케이션에서 클라이언트 재설정 처리를 반복하는 동안 동기화를 종료했다가 다시 활성화해야 할 수 있습니다. 동기화를 종료했다가 다시 활성화하면 클라이언트 재설정을 완료할 때까지 기존의 모든 클라이언트를 동기화할 수 없습니다. 프로덕션 환경에서 이를 방지하려면 개발 환경에서 클라이언트 재설정 처리를 테스트하세요.