.NET MAUI Essentials 기능 가이드: Xamarin.Essentials 이전

- 1월 09, 2022

이 글은 2022년 Xamarin.Essentials 소개 글을 .NET MAUI의 플랫폼 통합 API 기준으로 전면 개정했습니다. 깨진 이미지를 제거하고 저장소, 연결 상태, 브라우저, 권한 사용 예제를 현재 네임스페이스로 바꿨습니다.

Xamarin.Essentials의 주요 기능은 .NET MAUI에 포함되어 있습니다. .NET MAUI 앱에서는 별도 Xamarin.Essentials 패키지를 추가하지 않고 Microsoft.Maui.ApplicationModel, Microsoft.Maui.Devices, Microsoft.Maui.Networking, Microsoft.Maui.Storage 등의 API를 사용합니다.

먼저 보는 핵심
설정값은 Preferences, 민감한 값은 SecureStorage, 네트워크 상태는 Connectivity, 웹 주소 열기는 Browser, 런타임 권한은 Permissions를 사용합니다. 플랫폼별 권한 선언은 코드와 별도로 필요합니다.

목적	대표 API	네임스페이스
일반 설정 저장	`Preferences`	`Microsoft.Maui.Storage`
민감한 값 저장	`SecureStorage`	`Microsoft.Maui.Storage`
네트워크 확인	`Connectivity`	`Microsoft.Maui.Networking`
브라우저 열기	`Browser`	`Microsoft.Maui.ApplicationModel`
권한 확인·요청	`Permissions`	`Microsoft.Maui.ApplicationModel`
기기 정보	`DeviceInfo`	`Microsoft.Maui.Devices`

1. Preferences로 일반 설정 저장

테마, 정렬 방식, 마지막 탭처럼 노출되어도 큰 문제가 없는 작은 값을 저장합니다.

using Microsoft.Maui.Storage;

Preferences.Default.Set("page_size", 20);
Preferences.Default.Set("dark_mode", true);

int pageSize = Preferences.Default.Get("page_size", 10);
bool darkMode = Preferences.Default.Get("dark_mode", false);

Preferences.Default.Remove("page_size");

토큰이나 비밀번호를 Preferences에 저장해서는 안 됩니다.

2. SecureStorage로 민감한 값 저장

using Microsoft.Maui.Storage;

await SecureStorage.Default.SetAsync("refresh_token", token);

string? savedToken = await SecureStorage.Default.GetAsync("refresh_token");

SecureStorage.Default.Remove("refresh_token");

보안 저장소 호출은 실패할 수 있습니다. 기기 잠금 설정, 백업 복원, 플랫폼 키 저장소 상태 등을 고려해 예외를 처리합니다.

try
{
    await SecureStorage.Default.SetAsync("refresh_token", token);
}
catch (Exception ex)
{
    // 로그에는 토큰 값을 남기지 않는다.
    await DisplayAlert("저장 실패", ex.Message, "확인");
}

3. 네트워크 상태 확인과 변경 감지

using Microsoft.Maui.Networking;

bool online = Connectivity.Current.NetworkAccess == NetworkAccess.Internet;

Connectivity.Current.ConnectivityChanged += OnConnectivityChanged;

void OnConnectivityChanged(object? sender, ConnectivityChangedEventArgs e)
{
    bool hasInternet = e.NetworkAccess == NetworkAccess.Internet;
    MainThread.BeginInvokeOnMainThread(() =>
    {
        StatusLabel.Text = hasInternet ? "온라인" : "오프라인";
    });
}

NetworkAccess.Internet은 연결 상태를 나타낼 뿐, 특정 서버 요청의 성공을 보장하지 않습니다. 실제 API 호출에는 시간 제한, 취소, 재시도 정책을 별도로 적용하세요. 페이지나 ViewModel을 해제할 때 이벤트도 구독 해제해야 합니다.

4. 브라우저로 안전하게 URL 열기

using Microsoft.Maui.ApplicationModel;

if (Uri.TryCreate(url, UriKind.Absolute, out Uri? uri) &&
    (uri.Scheme == Uri.UriSchemeHttps || uri.Scheme == Uri.UriSchemeHttp))
{
    await Browser.Default.OpenAsync(uri, BrowserLaunchMode.SystemPreferred);
}

외부 입력으로 받은 URL은 허용할 스킴과 호스트를 검증하세요. 로그인 콜백이나 앱 간 이동에는 플랫폼별 딥 링크 설정도 필요합니다.

5. 런타임 권한 요청

권한은 기능을 사용하는 시점에 설명한 뒤 요청합니다.

using Microsoft.Maui.ApplicationModel;

PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();

if (status != PermissionStatus.Granted)
{
    status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();
}

if (status != PermissionStatus.Granted)
{
    await DisplayAlert("권한 필요", "위치 기능을 사용하려면 권한이 필요합니다.", "확인");
    return;
}

Android의 AndroidManifest.xml, iOS의 Info.plist에는 해당 권한과 사용 목적을 선언해야 합니다. 거부된 권한을 반복 요청하기보다 설정 화면 안내나 기능 제한 방식을 제공하세요.

Xamarin.Essentials 코드 이전 순서

Xamarin.Essentials NuGet 참조를 제거합니다.
using Xamarin.Essentials;를 기능별 Microsoft.Maui.* 네임스페이스로 바꿉니다.
플랫폼별 권한과 설정을 새 프로젝트에 옮깁니다.
에뮬레이터뿐 아니라 실제 Android·iOS 기기에서 저장소와 권한을 확인합니다.
네이티브 .NET for Android/iOS 프로젝트라면 공식 문서의 UseMauiEssentials 설정과 초기화 절차를 따릅니다.

전체 기능 목록은 .NET MAUI 플랫폼 기능에서, 네이티브 프로젝트 이전 절차는 Xamarin.Essentials 코드 이전에서 확인할 수 있습니다.

정리

.NET MAUI에서는 Xamarin.Essentials의 핵심 기능을 별도 패키지 없이 사용할 수 있습니다. 저장할 데이터의 민감도를 먼저 구분하고, 권한 선언과 런타임 요청을 함께 구현하며, 네트워크 상태와 실제 요청 성공을 별개로 처리하면 운영 중 오류를 줄일 수 있습니다.

이 블로그 검색

won-solution.com