1⃣ 사용자가 “Google로 로그인” 버튼을 클릭

Navigation.NavigateTo(..., forceLoad: true)

Blazor의 내부 라우팅이 아닌, 브라우저가 직접 해당 URL(api/auth/Challenge/Google...)로 GET 요청보낸다.

private void LoginWithGoogle()
{
    var returnUrl = "/"; // 로그인 성공 후 돌아올 주소
    var googleLoginUrl = $"/api/auth/Challenge/Google?returnUrl={Uri.EscapeDataString(returnUrl)}";

    // 이 주소로 브라우저가 페이지를 새로고침하며 이동
    Navigation.NavigateTo(googleLoginUrl, forceLoad: true);
}

2⃣ 백엔드의 인증 시작 (AuthController – Challenge)

// AuthController.cs
[HttpGet("Challenge/{provider}")]
public IActionResult Challenge(string provider, string? returnUrl = null)
{
    // ...
    var redirectUrl = Url.Action("Callback", "Auth", ...); // 1. Google이 인증 후 돌아올 우리 API 주소(Callback)를 지정
    var properties = _signInManager.ConfigureExternalAuthenticationProperties(provider, redirectUrl); // 2. 인증 요청에 필요한 속성 구성

    return Challenge(properties, provider); // 3. Google 로그인 페이지로 리디렉션하는 응답 생성
}

• AuthController.cs의 Challenge 메서드가 실행됩니다.
  provider 매개변수에는 “Google”이 전달
• _signInManager는 ASP.NET Core Identity의 핵심 기능으로, 외부 로그인 과정을 도와줌
• return Challenge(properties, provider);는 브라우저에게 HTTP 302 Redirect 응답을 보냄
  이 응답 헤더에는 사용자가 이동해야 할 Google의 로그인 페이지 주소가 포함

3⃣ 외부 공급자 인증 (Google)

사용자는 Google 로그인 페이지로 이동

• 사용자는 자신의 Google 계정으로 로그인하고, 우리 애플리케이션이 요청하는 정보(이메일, 프로필 등)에 대한 접근 권한을 허용
• 인증이 성공적으로 완료되면, Google은 2단계에서 백엔드가 지정했던 콜백 URL(api/Auth/Callback)로 사용자를 다시 리디렉션
  이때 인증 코드 또는 토큰과 함께 사용자를 보냄

4⃣ 백엔드의 콜백 처리 및 로그인/회원가입 (AuthController – Callback)

Google이 사용자를 우리 백엔드의 Callback 엔드포인트로 돌려보냄

AuthController.cs의 Callback (라우팅 경로: externalLogin) 메서드가 실행

// AuthController.cs
[HttpGet("externalLogin")]
public async Task<IActionResult> Callback(...)
{
    // 1. Google이 보내준 정보로 외부 로그인 정보를 가져옴
    var info = await _signInManager.GetExternalLoginInfoAsync();
    if (info == null) { /* 에러 처리 */ }

    // 2. 이 외부 정보(공급자, 키)로 우리 DB에 연결된 사용자가 있는지 확인하고 로그인 시도
    var result = await _signInManager.ExternalLoginSignInAsync(info.LoginProvider, info.ProviderKey, ...);

    if (result.Succeeded)
    {
        // 3a. 성공! 이미 가입하고 연동된 사용자. 로그인 처리 후 returnUrl로 리디렉션
        return LocalRedirect(returnUrl);
    }
    else
    {
        // 3b. 실패. 신규 사용자이거나, 이메일은 같지만 연동되지 않은 사용자.
        return await HandleUserCreationOrLinking(info, returnUrl);
    }
}

HandleUserCreationOrLinking 메서드는 다음 두 가지 시나리오를 처리

• 시나리오 A: 이메일은 존재하지만 소셜 연동이 안 된 경우 (LinkExistingUser)
  • Google에서 받은 이메일로 우리 DB에서 사용자를 찾습니다. (_userManager.FindByEmailAsync)
  • 기존 사용자가 있다면, 해당 계정에 이 Google 로그인 정보를 추가로 연결합니다. (_userManager.AddLoginAsync)
  • 연결 후, 사용자를 로그인시키고 returnUrl로 리디렉션합니다.
• 시나리오 B: 완전히 새로운 사용자인 경우 (CreateNewUserAsync)
  • Google에서 받은 이메일과 이름으로 새로운 ApplicationUser 객체를 만듭니다. 이때 EmailConfirmed는 true로 설정합니다. (소셜 로그인은 이미 이메일이 인증된 것으로 간주)
  • _userManager.CreateAsync(user)로 DB에 새 사용자를 저장합니다.
  • 새로 생성된 사용자 계정에 Google 로그인 정보를 연결합니다. (_userManager.AddLoginAsync)
  • 새 사용자를 로그인시키고 returnUrl로 리디렉션합니다.

5⃣ 완료

로그인 또는 회원가입 및 연동이 모두 성공적으로 끝나면, 백엔드는 최종적으로 LocalRedirect(returnUrl)을 통해 사용자를 맨 처음 Login.razor에서 지정했던 주소(/)로 리디렉션합니다.

이제 사용자는 로그인된 상태로 메인 페이지를 보게 됩니다.

6⃣ AuthController.cs

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.WebUtilities;
using Microsoft.IdentityModel.Tokens;
using Neco.BaseTemplate.Shared.Data;
using Neco.BaseTemplete.Data;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using System.Text.Encodings.Web;

namespace Neco.BaseTemplete.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class AuthController : ControllerBase
    {
        private readonly UserManager<ApplicationUser> _userManager;
        private readonly SignInManager<ApplicationUser> _signInManager;
        private readonly IUserStore<ApplicationUser> _userStore;
        private readonly IEmailSender<ApplicationUser> _emailSender;
        private readonly ILogger<AuthController> _logger;

        public AuthController(
            UserManager<ApplicationUser> userManager,
            SignInManager<ApplicationUser> signInManager,
            IUserStore<ApplicationUser> userStore,
            IEmailSender<ApplicationUser> emailSender,
            ILogger<AuthController> logger)
        {
            _userManager = userManager;
            _signInManager = signInManager;
            _userStore = userStore;
            _emailSender = emailSender;
            _logger = logger;
        }

        #region Basic Authentication

        /// <summary>
        /// Handles user login.
        /// </summary>
        /// <param name="model">Login request DTO (email, password, RememberMe option)</param>
        /// <returns>The login result</returns>
        [HttpPost("login")]
        public async Task<IActionResult> Login([FromBody] LoginUserRequestDTO model)
        {
            try
            {
                var result = await _signInManager.PasswordSignInAsync(
                    model.Email,
                    model.Password,
                    model.RememberMe,
                    lockoutOnFailure: true);

                if (result.Succeeded)
                {
                    _logger.LogInformation("User logged in: {Email}", model.Email);
                    return Ok(new { Success = true });
                }

                if (result.RequiresTwoFactor)
                {
                    return Ok(new { RequiresTwoFactor = true });
                }

                if (result.IsLockedOut)
                {
                    _logger.LogWarning("User account locked out: {Email}", model.Email);
                    return BadRequest("Account locked out");
                }

                return BadRequest("Invalid login attempt");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Login error for {Email}", model.Email);
                return StatusCode(500, "An error occurred");
            }
        }

        /// <summary>
        /// Handles new user registration.
        /// </summary>
        /// <param name="model">Registration request DTO</param>
        /// <returns>The registration result</returns>
        [HttpPost("register")]
        public async Task<IActionResult> Register([FromBody] CreateUserRequestDTO model)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(new RegisterUserResponseDTO
                {
                    Status = RegisterUserResponseDTO.ResponseStatus.Fail_RequestInvalid,
                    Errors = ModelState.Values.SelectMany(v => v.Errors).Select(e => e.ErrorMessage)
                });
            }

            var user = CreateUser();
            await _userStore.SetUserNameAsync(user, model.Email, CancellationToken.None);
            var emailStore = GetEmailStore();
            await emailStore.SetEmailAsync(user, model.Email, CancellationToken.None);

            var result = await _userManager.CreateAsync(user, model.Password);

            if (!result.Succeeded)
            {
                _logger.LogInformation("User registration failed: {Email}", model.Email);

                // Handle duplicate email error
                if (result.Errors.Any(e => e.Code == "DuplicateUserName"))
                {
                    return BadRequest(new RegisterUserResponseDTO
                    {
                        Status = RegisterUserResponseDTO.ResponseStatus.Fail_DuplicateEmail,
                    });
                }

                // Handle general Identity errors
                return BadRequest(new RegisterUserResponseDTO
                {
                    Status = RegisterUserResponseDTO.ResponseStatus.Fail_General,
                    Errors = result.Errors.Select(e => e.Description)
                });
            }

            _logger.LogInformation("User created a new account with a password.");

            // Send email confirmation link
            try
            {
                var userId = await _userManager.GetUserIdAsync(user);
                var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);
                code = WebEncoders.Base64UrlEncode(Encoding.UTF8.GetBytes(code));

                // NOTE: For security, it's recommended to configure a fixed base URL
                // from your application's settings rather than relying on the request host.
                var baseUrl = model.BaseUrl ?? $"{Request.Scheme}://{Request.Host.Value}";
                var callbackUrl = $"{baseUrl}/Account/ConfirmEmail?userId={userId}&code={code}";

                await _emailSender.SendConfirmationLinkAsync(user, model.Email, HtmlEncoder.Default.Encode(callbackUrl));
            }
            catch (Exception)
            {
                // Account created successfully but email sending failed.
                return Ok(new RegisterUserResponseDTO
                {
                    Status = RegisterUserResponseDTO.ResponseStatus.Success_EmailWarning,
                    Message = "The account was created, but the verification email sending failed."
                });
            }

            return Ok(new RegisterUserResponseDTO
            {
                Status = RegisterUserResponseDTO.ResponseStatus.Success_NeedConfirmation
            });
        }

        /// <summary>
        /// Resends the email confirmation link.
        /// </summary>
        /// <param name="model">Email confirmation request DTO</param>
        /// <returns>The result of the process</returns>
        [HttpPost("emailConfirm")]
        public async Task<IActionResult> ResendEmailConfirm([FromBody] RequestEmailConfirmDTO model)
        {
            if (!ModelState.IsValid)
            {
                // Always return a success response for security (to avoid user enumeration).
                return Ok(new ResponseEmailConfirmDTO
                {
                    Status = ResponseEmailConfirmDTO.ResponseStatus.Success,
                    Message = "The confirmation email has been sent successfully."
                });
            }

            try
            {
                var user = await _userManager.FindByEmailAsync(model.Email);

                // Even if the user doesn't exist or is already confirmed, return a success response for security.
                if (user == null || user.EmailConfirmed)
                {
                    return Ok(new ResponseEmailConfirmDTO
                    {
                        Status = ResponseEmailConfirmDTO.ResponseStatus.Success,
                        Message = "The confirmation email has been sent successfully."
                    });
                }

                // Generate and send the email confirmation link
                var userId = await _userManager.GetUserIdAsync(user);
                var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);
                code = WebEncoders.Base64UrlEncode(Encoding.UTF8.GetBytes(code));

                // NOTE: It is recommended to use a pre-configured base URL.
                var baseUrl = model.BaseUrl ?? $"{Request.Scheme}://{Request.Host.Value}";
                var callbackUrl = $"{baseUrl}/Account/ConfirmEmail?userId={userId}&code={code}";

                await _emailSender.SendConfirmationLinkAsync(user, model.Email, HtmlEncoder.Default.Encode(callbackUrl));

                return Ok(new ResponseEmailConfirmDTO
                {
                    Status = ResponseEmailConfirmDTO.ResponseStatus.Success,
                    Message = "The confirmation email has been sent successfully."
                });
            }
            catch (Exception)
            {
                // Mail server or other exception occurred.
                return BadRequest(new ResponseEmailConfirmDTO
                {
                    Status = ResponseEmailConfirmDTO.ResponseStatus.Fail,
                    Message = $"An error occurred while processing your request. (Server Error)"
                });
            }
        }

        /// <summary>
        /// Handles password reset requests.
        /// </summary>
        /// <param name="model">Password reset request DTO</param>
        /// <returns>The result of the process</returns>
        [HttpPost("resetPassword")]
        public async Task<IActionResult> ResetPassword([FromBody] ResetPasswordRequestDTO model)
        {
            var user = await _userManager.FindByEmailAsync(model.Email);
            if (user == null)
            {
                return BadRequest("User not found");
            }

            var resetToken = await _userManager.GeneratePasswordResetTokenAsync(user);
            var callbackUrl = $"{model.BaseUrl}/Account/ResetPassword?email={model.Email}&token={resetToken}";

            await _emailSender.SendPasswordResetLinkAsync(user, model.Email, callbackUrl);

            return Ok("Password reset link sent");
        }

        /// <summary>
        /// Handles user logout.
        /// </summary>
        /// <returns>The logout result</returns>
        [HttpPost("logout")]
        public async Task<IActionResult> Logout()
        {
            await _signInManager.SignOutAsync();
            return Ok("Logged out successfully");
        }

        /// <summary>
        /// Handles the generation of a JWT token.
        /// </summary>
        /// <param name="model">Login request DTO (email, password)</param>
        /// <returns>Token information</returns>
        [HttpPost("token")]
        public async Task<IActionResult> GenerateToken([FromBody] LoginUserRequestDTO model)
        {
            var user = await _userManager.FindByEmailAsync(model.Email);
            if (user == null || !await _userManager.CheckPasswordAsync(user, model.Password))
            {
                return Unauthorized("Invalid credentials");
            }

            var claims = new[]
            {
                new Claim(ClaimTypes.Name, user.UserName),
                new Claim(ClaimTypes.Email, user.Email)
            };

            // WARNING: Do not hard-code the key in production.
            // Move this to a secure configuration file (e.g., appsettings.json)
            // and use a strong, randomly generated key.
            var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A_Very_Strong_And_Secret_Key_For_JWT_Auth"));
            var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

            var token = new JwtSecurityToken(
                issuer: "yourdomain.com",
                audience: "yourdomain.com",
                claims: claims,
                expires: DateTime.Now.AddMinutes(30),
                signingCredentials: creds);

            return Ok(new { token = new JwtSecurityTokenHandler().WriteToken(token) });
        }

        #endregion

        #region External Authentication (OAuth)

        /// <summary>
        /// Initiates a challenge request to an external authentication provider (e.g., Google).
        /// </summary>
        /// <param name="provider">The name of the authentication provider (e.g., "Google")</param>
        /// <param name="returnUrl">The URL to redirect to after successful authentication</param>
        /// <returns>A challenge result to the external provider</returns>
        [HttpGet("Challenge/{provider}")]
        public IActionResult Challenge(string provider, string? returnUrl = null)
        {
            _logger.LogInformation("Starting {Provider} login", provider);

            if (string.IsNullOrWhiteSpace(provider))
            {
                return BadRequest(new { error = "Provider not specified." });
            }

            // Normalize and validate returnUrl
            returnUrl = NormalizeReturnUrl(returnUrl);

            // Set the callback URL
            var redirectUrl = Url.Action("Callback", "Auth", new { returnUrl }, Request.Scheme);

            // Configure authentication properties
            var properties = _signInManager.ConfigureExternalAuthenticationProperties(provider, redirectUrl);

            return Challenge(properties, provider);
        }

        /// <summary>
        /// Handles the callback from an external authentication provider.
        /// </summary>
        /// <param name="returnUrl">The URL to redirect to after successful authentication</param>
        /// <param name="remoteError">Error message from the external provider</param>
        /// <returns>An appropriate response based on the authentication result</returns>
        [HttpGet("externalLogin")]
        public async Task<IActionResult> Callback(string? returnUrl = null, string? remoteError = null)
        {
            try
            {
                returnUrl = NormalizeReturnUrl(returnUrl);

                if (!string.IsNullOrEmpty(remoteError))
                {
                    _logger.LogError("External provider error: {RemoteError}", remoteError);
                    return Redirect($"/login?error={Uri.EscapeDataString(remoteError)}");
                }

                var info = await _signInManager.GetExternalLoginInfoAsync();
                if (info == null)
                {
                    _logger.LogError("Could not retrieve external login info");
                    return Redirect("/login?error=external_login_failed");
                }

                // Attempt to sign in an existing user
                var result = await _signInManager.ExternalLoginSignInAsync(
                    info.LoginProvider,
                    info.ProviderKey,
                    isPersistent: false,
                    bypassTwoFactor: true);

                if (result.Succeeded)
                {
                    var user = await _userManager.FindByLoginAsync(info.LoginProvider, info.ProviderKey);
                    _logger.LogInformation("User {Email} successfully logged in", user?.Email);
                    return LocalRedirect(returnUrl);
                }

                if (result.IsLockedOut)
                {
                    _logger.LogWarning("Attempt to log in with a locked-out account");
                    return Redirect("/login?error=locked_out");
                }

                // New user or linking an existing user
                return await HandleUserCreationOrLinking(info, returnUrl);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error occurred while processing external login");
                return Redirect("/login?error=server_error");
            }
        }

        #endregion

        #region Helper Methods

        /// <summary>
        /// Normalizes and validates the returnUrl.
        /// </summary>
        private string NormalizeReturnUrl(string? returnUrl)
        {
            if (string.IsNullOrWhiteSpace(returnUrl))
                return "/";

            if (Uri.TryCreate(returnUrl, UriKind.Absolute, out var uri))
                returnUrl = uri.PathAndQuery;

            return Url.IsLocalUrl(returnUrl) ? returnUrl : "/";
        }

        /// <summary>
        /// Handles new user creation or linking an existing user to an external login.
        /// </summary>
        private async Task<IActionResult> HandleUserCreationOrLinking(ExternalLoginInfo info, string returnUrl)
        {
            var email = info.Principal.FindFirstValue(ClaimTypes.Email);
            if (string.IsNullOrEmpty(email))
            {
                _logger.LogError("Missing email information from external provider {Provider}", info.LoginProvider);
                return Redirect("/login?error=email_required");
            }

            var existingUser = await _userManager.FindByEmailAsync(email);
            return existingUser != null
                ? await LinkExistingUser(existingUser, info, returnUrl)
                : await CreateNewUserAsync(info, returnUrl);
        }

        /// <summary>
        /// Links external login information to an existing user.
        /// </summary>
        private async Task<IActionResult> LinkExistingUser(ApplicationUser user, ExternalLoginInfo info, string returnUrl)
        {
            var addLoginResult = await _userManager.AddLoginAsync(user, info);
            if (addLoginResult.Succeeded)
            {
                _logger.LogInformation("Successfully linked {Provider} login to existing user {Email}", info.LoginProvider, user.Email);
                await _signInManager.SignInAsync(user, isPersistent: false, info.LoginProvider);
                return LocalRedirect(returnUrl);
            }

            _logger.LogError("Failed to link external login to existing user: {Errors}",
                string.Join(", ", addLoginResult.Errors.Select(e => e.Description)));
            return Redirect("/login?error=link_failed");
        }

        /// <summary>
        /// Creates a new user based on external login information.
        /// </summary>
        private async Task<IActionResult> CreateNewUserAsync(ExternalLoginInfo info, string returnUrl)
        {
            var email = info.Principal.FindFirstValue(ClaimTypes.Email);
            if (string.IsNullOrEmpty(email))
            {
                _logger.LogError("Missing email information from external provider");
                return BadRequest(new { error = "Email information was not provided." });
            }

            var userName = email.Split('@')[0];
            var user = new ApplicationUser
            {
                UserName = email,
                Email = email,
                NickName = userName,
                EmailConfirmed = true // Email is already confirmed via external provider
            };

            var createResult = await _userManager.CreateAsync(user);
            if (!createResult.Succeeded)
            {
                _logger.LogError("User creation failed: {Errors}",
                    string.Join(", ", createResult.Errors.Select(e => e.Description)));

                // Attempt to create an alternative user name on a naming conflict
                if (createResult.Errors.Any(e => e.Code == "DuplicateUserName"))
                {
                    user.UserName = $"{userName}_{Guid.NewGuid().ToString("N").Substring(0, 4)}";
                    createResult = await _userManager.CreateAsync(user);

                    if (!createResult.Succeeded)
                    {
                        return BadRequest(new
                        {
                            error = "Account creation failed",
                            details = createResult.Errors.Select(e => e.Description)
                        });
                    }
                }
                else
                {
                    return BadRequest(new
                    {
                        error = "Account creation failed",
                        details = createResult.Errors.Select(e => e.Description)
                    });
                }
            }

            // Link external login information
            var addLoginResult = await _userManager.AddLoginAsync(user, info);
            if (!addLoginResult.Succeeded)
            {
                _logger.LogError("Failed to add login information: {Errors}",
                    string.Join(", ", addLoginResult.Errors.Select(e => e.Description)));

                // Rollback: Delete the created user
                await _userManager.DeleteAsync(user);

                return BadRequest(new
                {
                    error = "Failed to link external login information",
                    details = addLoginResult.Errors.Select(e => e.Description)
                });
            }

            _logger.LogInformation("New user created and logged in successfully: {Email}", email);
            await _signInManager.SignInAsync(user, isPersistent: false, info.LoginProvider);

            return LocalRedirect(returnUrl);
        }

        private ApplicationUser CreateUser()
        {
            try
            {
                return Activator.CreateInstance<ApplicationUser>();
            }
            catch
            {
                throw new InvalidOperationException($"Can't create an instance of '{nameof(ApplicationUser)}'. " +
                    $"Ensure that '{nameof(ApplicationUser)}' is not an abstract class and has a parameterless constructor.");
            }
        }

        private IUserEmailStore<ApplicationUser> GetEmailStore()
        {
            if (!_userManager.SupportsUserEmail)
            {
                throw new NotSupportedException("The default UI requires a user store with email support.");
            }
            return (IUserEmailStore<ApplicationUser>)_userStore;
        }

        #endregion

        #region Profile Management

        /// <summary>
        /// Handles user profile updates.
        /// </summary>
        /// <param name="model">Update request DTO</param>
        /// <returns>The result of the process</returns>
        [HttpPut("updateProfile")]
        public async Task<IActionResult> UpdateProfile([FromBody] UpdateUserProfileDTO model)
        {
            var user = await _userManager.FindByIdAsync(model.Email);
            if (user == null)
            {
                return NotFound("User not found");
            }

            user.NickName = model.Nickname;
            user.PhoneNumber = model.PhoneNumber;

            var result = await _userManager.UpdateAsync(user);
            if (!result.Succeeded)
            {
                return BadRequest(result.Errors.Select(e => e.Description));
            }

            return Ok("Profile updated successfully");
        }

        /// <summary>
        /// Handles user deletion.
        /// </summary>
        /// <param name="userId">The ID of the user to delete</param>
        /// <returns>The result of the process</returns>
        [HttpDelete("deleteUser/{userId}")]
        public async Task<IActionResult> DeleteUser(string userId)
        {
            var user = await _userManager.FindByIdAsync(userId);
            if (user == null)
            {
                return NotFound("User not found");
            }

            var result = await _userManager.DeleteAsync(user);
            if (!result.Succeeded)
            {
                return BadRequest(result.Errors.Select(e => e.Description));
            }

            return Ok("User deleted successfully");
        }

        #endregion
    }
}

private void LoginWithGoogle()
{
    try
    {
        var returnUrl = "/";
        var googleLoginUrl = $"/api/auth/Challenge/Google?returnUrl={Uri.EscapeDataString(returnUrl)}";

        // Redirect in the current window instead of a popup
        // This is a placeholder for a client-side navigation method, e.g., in Blazor
        // Navigation.NavigateTo(googleLoginUrl, forceLoad: true);
    }
    catch (Exception ex)
    {
        // Error handling
        Console.WriteLine($"Google login error: {ex.Message}");
    }
}

The post ASP.NET Core Identity를 활용한 구글 로그인(OAuth) 전체 흐름 분석 appeared first on 어제와 내일의 나 그 사이의 이야기.

ASP.NET Core IdentityOptions 개요

https://github.com/dotnet/aspnetcore/blob/3f1acb59718cadf111a0a796681e3d3509bb3381/src/Identity/Extensions.Core/src/IdentityOptions.cs#L17C65-L65C66

ASP.NET Core의 IdentityOptions는 시스템의 설정을 한 곳에 몰아서 관리하는 클래스입니다. (중앙 집중식 구성)

이를 통해 패스워드 정책, 사용자 설정, 로그인 정책, 잠금 정책 등을 세밀하게 제어할 수 있습니다.

주요 구성 요소

1⃣ Password 옵션 (PasswordOptions)

패스워드 복잡성 요구사항을 설정합니다.

// Program.cs 또는 Startup.cs

// 개발 환경용 - 간단한 패스워드
public void ConfigureDevelopmentPassword(IdentityOptions options)
{
    options.Password.RequireDigit = false;
    options.Password.RequireLowercase = false;
    options.Password.RequireUppercase = false;
    options.Password.RequireNonAlphanumeric = false;
    options.Password.RequiredLength = 4;
}

// 프로덕션 환경용 - 강력한 패스워드
public void ConfigureProductionPassword(IdentityOptions options)
{
    options.Password.RequireDigit = true;
    options.Password.RequireLowercase = true;
    options.Password.RequireUppercase = true;
    options.Password.RequireNonAlphanumeric = true;
    options.Password.RequiredLength = 12;
    options.Password.RequiredUniqueChars = 4;
}

2⃣ Lockout 옵션 (LockoutOptions)

계정 잠금 정책을 설정합니다.

public void ConfigureProgressiveLockout(IdentityOptions options)
{
    options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(1);   // 1분부터 시작
    options.Lockout.MaxFailedAccessAttempts = 3;                        // 3회 실패시 잠금
    options.Lockout.AllowedForNewUsers = true;
}

// 커스텀 잠금 시간 증가 로직 (서비스에서 구현)
public class CustomLockoutService
{
    public TimeSpan CalculateLockoutDuration(int failedAttempts)
    {
        return failedAttempts switch
        {
            <= 3 => TimeSpan.FromMinutes(5),
            <= 6 => TimeSpan.FromMinutes(15),
            <= 10 => TimeSpan.FromHours(1),
            _ => TimeSpan.FromHours(24)
        };
    }
}

public void ConfigureProgressiveLockout(IdentityOptions options)
{
    options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(1);   // 1분부터 시작
    options.Lockout.MaxFailedAccessAttempts = 3;                        // 3회 실패시 잠금
    options.Lockout.AllowedForNewUsers = true;
}

// 커스텀 잠금 시간 증가 로직 (서비스에서 구현)
public class CustomLockoutService
{
    public TimeSpan CalculateLockoutDuration(int failedAttempts)
    {
        return failedAttempts switch
        {
            <= 3 => TimeSpan.FromMinutes(5),
            <= 6 => TimeSpan.FromMinutes(15),
            <= 10 => TimeSpan.FromHours(1),
            _ => TimeSpan.FromHours(24)
        };
    }
}

3⃣ SignIn 옵션 (SignInOptions)

로그인 관련 설정을 구성합니다.

// 이메일 인증 필수 설정
public void ConfigureEmailConfirmation(IdentityOptions options)
{
    options.SignIn.RequireConfirmedEmail = true;
}

// 회원가입 컨트롤러
[HttpPost]
public async Task<IActionResult> Register(RegisterViewModel model)
{
    var user = new ApplicationUser { UserName = model.Email, Email = model.Email };
    var result = await _userManager.CreateAsync(user, model.Password);
    
    if (result.Succeeded)
    {
        // 이메일 인증 토큰 생성
        var token = await _userManager.GenerateEmailConfirmationTokenAsync(user);
        var confirmationLink = Url.Action("ConfirmEmail", "Account", 
            new { userId = user.Id, token = token }, Request.Scheme);
        
        // 이메일 발송
        await _emailSender.SendEmailAsync(model.Email, "이메일 인증", 
            $"다음 링크를 클릭하여 계정을 활성화하세요: {confirmationLink}");
        
        return View("EmailConfirmationSent");
    }
    
    return View(model);
}

// 이메일 인증 필수 설정
public void ConfigureEmailConfirmation(IdentityOptions options)
{
    options.SignIn.RequireConfirmedEmail = true;
}

// 회원가입 컨트롤러
[HttpPost]
public async Task<IActionResult> Register(RegisterViewModel model)
{
    var user = new ApplicationUser { UserName = model.Email, Email = model.Email };
    var result = await _userManager.CreateAsync(user, model.Password);
    
    if (result.Succeeded)
    {
        // 이메일 인증 토큰 생성
        var token = await _userManager.GenerateEmailConfirmationTokenAsync(user);
        var confirmationLink = Url.Action("ConfirmEmail", "Account", 
            new { userId = user.Id, token = token }, Request.Scheme);
        
        // 이메일 발송
        await _emailSender.SendEmailAsync(model.Email, "이메일 인증", 
            $"다음 링크를 클릭하여 계정을 활성화하세요: {confirmationLink}");
        
        return View("EmailConfirmationSent");
    }
    
    return View(model);
}

4⃣ User 옵션 (UserOptions)

사용자 계정 관련 설정을 구성합니다.

builder.Services.Configure<IdentityOptions>(options =>
{
    // 사용자 설정
    options.User.AllowedUserNameCharacters = 
        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+";
    options.User.RequireUniqueEmail = true;  // 중복 이메일 방지
});


사용자명 정책 예제:
public void ConfigureUserPolicies(IdentityOptions options)
{
    // 한국어 사용자명 허용
    options.User.AllowedUserNameCharacters = 
        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+가-힣";
    
    // 이메일을 고유하게 설정
    options.User.RequireUniqueEmail = true;
}

// 커스텀 사용자명 검증
public class CustomUserValidator<TUser> : IUserValidator<TUser> 
    where TUser : class
{
    public Task<IdentityResult> ValidateAsync(UserManager<TUser> manager, TUser user)
    {
        var userName = manager.GetUserNameAsync(user).Result;
        
        // 사용자명이 숫자로만 구성되면 안됨
        if (userName.All(char.IsDigit))
        {
            return Task.FromResult(
                IdentityResult.Failed(new IdentityError
                {
                    Code = "NumericUserName",
                    Description = "사용자명은 숫자로만 구성될 수 없습니다."
                }));
        }
        
        return Task.FromResult(IdentityResult.Success);
    }
}

5⃣ Stores 옵션 (StoreOptions)

사용자 계정 관련 설정을 구성합니다.

builder.Services.Configure<IdentityOptions>(options =>
{
    // 저장소 설정
    options.Stores.MaxLengthForKeys = 128;              // 키 최대 길이
    options.Stores.ProtectPersonalData = false;         // 개인정보 암호화 여부
});

실제 활용 시나리오

1⃣ 다단계 인증 설정

public void ConfigureTwoFactorAuthentication(IdentityOptions options)
{
    options.SignIn.RequireConfirmedPhoneNumber = true;  // 전화번호 인증 필수
    options.Tokens.AuthenticatorTokenProvider = TokenOptions.DefaultAuthenticatorProvider;
}

// 2FA 활성화 코드
[HttpPost]
public async Task<IActionResult> EnableTwoFactorAuthentication()
{
    var user = await _userManager.GetUserAsync(User);
    await _userManager.SetTwoFactorEnabledAsync(user, true);
    
    return RedirectToAction("ShowRecoveryCodes");
}

2⃣ 소셜 로그인과 연계

public void ConfigureExternalLogins(IdentityOptions options)
{
    // 외부 로그인 시에는 이메일 인증 건너뛰기
    options.SignIn.RequireConfirmedEmail = false;
    
    // 하지만 고유 이메일은 필수
    options.User.RequireUniqueEmail = true;
}

// 외부 로그인 처리
[HttpPost]
public IActionResult ExternalLogin(string provider)
{
    var redirectUrl = Url.Action("ExternalLoginCallback");
    var properties = _signInManager.ConfigureExternalAuthenticationProperties(provider, redirectUrl);
    return Challenge(properties, provider);
}

3⃣ 커스텀 검증 규칙 적용

// 커스텀 패스워드 검증기
public class CustomPasswordValidator : IPasswordValidator<ApplicationUser>
{
    public Task<IdentityResult> ValidateAsync(UserManager<ApplicationUser> manager, 
        ApplicationUser user, string password)
    {
        // 사용자명과 패스워드가 너무 유사하면 안됨
        if (password.Contains(user.UserName, StringComparison.OrdinalIgnoreCase))
        {
            return Task.FromResult(IdentityResult.Failed(new IdentityError
            {
                Code = "PasswordContainsUserName",
                Description = "패스워드에 사용자명이 포함될 수 없습니다."
            }));
        }
        
        return Task.FromResult(IdentityResult.Success);
    }
}

// 서비스 등록
builder.Services.AddTransient<IPasswordValidator<ApplicationUser>, CustomPasswordValidator>();

참고 사항

1⃣ 모니터링 및 로깅

보안 이벤트 로깅

public class SecurityEventLogger
{
    private readonly ILogger<SecurityEventLogger> _logger;
    
    public SecurityEventLogger(ILogger<SecurityEventLogger> logger)
    {
        _logger = logger;
    }
    
    public void LogFailedLogin(string userName, string ipAddress)
    {
        _logger.LogWarning("Failed login attempt for user {UserName} from IP {IpAddress}", 
            userName, ipAddress);
    }
    
    public void LogAccountLocked(string userName)
    {
        _logger.LogWarning("Account locked for user {UserName}", userName);
    }
}

2⃣ 환경별 설정 관리

appsettings.json을 활용한 설정

{
  "Identity": {
    "Password": {
      "RequiredLength": 8,
      "RequireDigit": true,
      "RequireUppercase": true,
      "RequireNonAlphanumeric": false
    },
    "Lockout": {
      "MaxFailedAccessAttempts": 5,
      "DefaultLockoutTimeSpanMinutes": 15
    },
    "SignIn": {
      "RequireConfirmedEmail": true
    }
  }
}

// 설정 바인딩
public class IdentityConfig
{
    public PasswordConfig Password { get; set; }
    public LockoutConfig Lockout { get; set; }
    public SignInConfig SignIn { get; set; }
}

// Program.cs에서 적용
var identityConfig = builder.Configuration.GetSection("Identity").Get<IdentityConfig>();

builder.Services.Configure<IdentityOptions>(options =>
{
    options.Password.RequiredLength = identityConfig.Password.RequiredLength;
    options.Password.RequireDigit = identityConfig.Password.RequireDigit;
    // ... 기타 설정
});

The post ASP.NET Core IdentityOptions 기본 예제 appeared first on 어제와 내일의 나 그 사이의 이야기.

ASP.NET Core Route Constraints (라우트 제한 조건)

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-8.0

ASP.NET Core의 라우팅 시스템에서 라우트 제한 조건(Route Constraints)은 URL 경로의 특정 세그먼트(라우팅 매개변수)에 대한 유효성 검사 규칙을 정의하는 강력한 기능입니다.

이를 통해 특정 URL 패턴이 매칭되기 위한 조건을 명시하고, 잘못된 형식의 URL 요청이 특정 라우트에 매칭되는 것을 방지할 수 있습니다.

1⃣ 라우트 제한 조건의 필요성

1. 정확한 라우트 매칭:
동일한 경로 프리픽스를 가지는 여러 라우트 중에서 가장 적절한 라우트를 선택할 수 있도록 돕습니다.

• 예: /products/123 (ID로 조회)와 /products/shoes (이름으로 조회)를 구분

2. 유효성 검사:
특정 매개변수가 예상하는 형식(예: 숫자, GUID, 날짜)인지 강제하여, 컨트롤러 액션 또는 핸들러에서 타입 변환 오류를 줄입니다.

3. 보안 및 견고성:
잘못된 형식의 입력으로 인한 잠재적인 오류나 공격 시도를 줄이는 데 기여합니다.

4. URL 디자인 강화:
더욱 명확하고 의미론적인 URL 구조를 유지할 수 있도록 돕습니다.

2⃣ 라우트 제한 조건 정의 방법

라우트 제한 조건은 라우트 템플릿 내에서 라우팅 매개변수 이름 뒤에 콜론(:)을 붙이고 제한 조건 이름을 지정하여 정의합니다.

{매개변수명:제한조건이름}

// Program.cs 또는 Startup.cs의 UseEndpoints 블록
endpoints.MapGet("/products/{id:int}", (int id) => Results.Ok($"Product ID: {id}"));

3⃣ 주요 라우트 제한 조건 종류 및 예시

ASP.NET Core는 다양한 내장 라우트 제한 조건을 제공합니다.

타입 기반 제한 조건

ASP.NET Core는 다양한 내장 라우트 제한 조건을 제공합니다.

// Program.cs 또는 Startup.cs
app.UseEndpoints(endpoints =>
{
    // 정수형 ID만 허용
    endpoints.MapGet("/products/{id:int}", (int id) => Results.Ok($"Getting product by ID: {id}"));

    // GUID 형식의 아이템 ID만 허용
    endpoints.MapGet("/items/{itemId:guid}", (Guid itemId) => Results.Ok($"Getting item by GUID: {itemId}"));

    // 특정 날짜 형식의 이벤트만 허용
    endpoints.MapGet("/events/on/{date:datetime}", (DateTime date) => Results.Ok($"Events on: {date.ToShortDateString()}"));
});

길이 및 범위 기반 제한 조건

매개변수 값의 길이 또는 숫자 범위를 제한합니다.

app.UseEndpoints(endpoints =>
{
    // 연령이 18세 이상인 사용자만 허용
    endpoints.MapGet("/users/age/{age:min(18)}", (int age) => Results.Ok($"Adult user, age: {age}"));

    // 재고 수량이 10개에서 100개 사이인 경우에만 유효
    endpoints.MapGet("/inventory/{count:range(10,100)}", (int count) => Results.Ok($"Checking inventory count: {count}"));

    // 최소 5자, 최대 10자의 사용자 이름만 허용
    endpoints.MapGet("/profile/{username:length(5,10)}", (string username) => Results.Ok($"Profile for user: {username}"));
});

정규식 기반 제한 조건

정규 표현식(Regular Expression)을 사용하여 매개변수 값의 패턴을 지정합니다.

이는 가장 유연한 제한 조건입니다.

app.UseEndpoints(endpoints =>
{
    // "abc"로 시작하고 숫자로 끝나는 코드만 허용
    endpoints.MapGet("/validate/{code:regex(abc\\d+)}", (string code) => Results.Ok($"Validated code: {code}"));

    // 상품 코드가 "PROD-"로 시작하고 4자리 숫자로 끝나는 경우만 허용
    endpoints.MapGet("/productcodes/{productCode:regex(^PROD-\\d{{4}}$)}", (string productCode) => Results.Ok($"Valid product code: {productCode}"));
    // 참고: 정규식 내의 중괄호는 이스케이프 필요 ({{, }})
});

다른 일반적인 제한 조건

app.UseEndpoints(endpoints =>
{
    // 이름은 알파벳만 허용
    endpoints.MapGet("/greet/{name:alpha}", (string name) => Results.Ok($"Hello, {name}!"));

    // 토큰은 알파벳 또는 숫자만 허용
    endpoints.MapGet("/verify/{token:alphanum}", (string token) => Results.Ok($"Verifying token: {token}"));

    // 국가 매개변수는 반드시 제공되어야 함
    endpoints.MapGet("/country/{country:required}", (string country) => Results.Ok($"Selected country: {country}"));
});

사용자 지정 라우트 제한 조건 (Custom Route Constraints)

내장된 제한 조건만으로는 부족할 때, IRouteConstraint 인터페이스를 구현하여 자신만의 커스텀 라우트 제한 조건을 만들 수 있습니다.

IRouteConstraint 인터페이스 구현

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;
using System.Globalization;

public class CustomYearConstraint : IRouteConstraint
{
    public bool Match(HttpContext? httpContext, IRouter? route, string routeKey, RouteValueDictionary values, RouteDirection routeDirection)
    {
        // routeKey는 매개변수 이름 (예: "year")
        // values는 모든 라우팅 매개변수와 그 값들을 담고 있는 딕셔너리
        if (values.TryGetValue(routeKey, out object? value))
        {
            if (value is string yearString && int.TryParse(yearString, out int year))
            {
                // 2000년 이후의 연도만 허용하는 예시
                return year >= 2000 && year <= DateTime.Now.Year + 1;
            }
        }
        return false;
    }
}

제한 조건 등록

Startup.cs의 ConfigureServices 또는 Program.cs에서 AddRouting 메서드를 사용하여 커스텀 제한 조건을 등록합니다.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRouting(options =>
{
    options.ConstraintMap.Add("customYear", typeof(CustomYearConstraint));
});

var app = builder.Build();

app.UseRouting();
app.UseEndpoints(endpoints =>
{
    // /articles/2023 와 같이 customYear 제한 조건을 사용
    endpoints.MapGet("/articles/{year:customYear}", (int year) => Results.Ok($"Articles from year: {year}"));
});

app.Run();

//  사용 예시:
//  /articles/2023 -> 매칭됨
//  /articles/1999 -> 매칭되지 않음
//  /articles/2026 (현재 연도가 2025년이라면) -> 매칭되지 않음 (DateTime.Now.Year + 1 조건에 따라)

4⃣ Endpoint Selection Order (엔드포인트 선택 순서)

라우팅 시스템이 여러 엔드포인트 중 어떤 엔드포인트를 현재 요청에 매칭시킬지 결정하는 방식에 대한 내용입니다.

이는 라우트 제한 조건(Route Constraints)의 라우트 순서와 밀접하게 관련되어 있습니다.

ASP.NET Core의 Endpoint Selection Order는 주로 다음 원칙에 따라 이루어집니다.

명시적 순서 (Order Property)

가장 직접적인 제어 방법은 엔드포인트에 Order 속성을 부여하는 것입니다. 숫자가 낮을수록 우선순위가 높습니다.

이는 MapControllerRoute나 MapRazorPages와 같은 메서드에는 직접 적용하기 어렵고, 주로 MapGet 등의 Minimal API 엔드포인트나 사용자 지정 RouteEndpoint를 만들 때 사용됩니다.

app.UseEndpoints(endpoints =>
{
    // Order가 -10인 엔드포인트 (가장 높은 우선순위)
    app.MapGet("/priority-test", () => "High priority").WithOrder(-10);

    // Order가 0인 기본 엔드포인트 (기본값)
    endpoints.MapGet("/test", () => "Normal priority");
});

Note:
WithMetadata를 통해 RouteEndpointBuilder에 직접 Order를 지정하는 것은 일반적인 사용법은 아니며, 실제로는 내부적으로 복잡한 로직을 통해 우선순위가 결정되거나 RouteEndpoint.Order 속성이 설정됩니다.
예를 들어, MapRazorPages나 MapControllers에서 생성되는 엔드포인트는 내부적으로 우선순위를 가집니다.)

라우트 템플릿의 구체성 (Specificity):

이것이 가장 일반적이고 중요한 순서 결정 기준입니다.

라우팅 시스템은 요청 URL과 가장 “구체적으로” 일치하는 라우트 템플릿을 선호합니다.

구체성은 다음과 같은 요소에 의해 결정됩니다:

리터럴 세그먼트의 수: 더 많은 리터럴(고정된 문자열) 세그먼트를 포함하는 라우트가 더 높은 우선순위를 가집니다.

• /products/all (2개의 리터럴)이 /products/{id} (1개의 리터럴, 1개의 매개변수)보다 우선순위가 높습니다.

라우트 제한 조건의 사용: 제한 조건이 있는 매개변수는 제한 조건이 없는 매개변수보다 더 구체적인 것으로 간주됩니다.

• /products/{id:int}는 /products/{id}보다 우선순위가 높습니다. (/products/123이 주어지면, id:int가 먼저 매칭됨)

선택적 매개변수: 선택적 매개변수가 없는 라우트가 더 구체적인 것으로 간주됩니다.

• /users/{id}가 /users/{id?}보다 우선순위가 높습니다.

Catch-all 매개변수 (* 또는 **): 가장 덜 구체적인 것으로 간주되어 거의 항상 마지막에 매칭됩니다.

• /files/{*path}는 일반적으로 다른 모든 구체적인 라우트 뒤에 위치해야 합니다.

정의 순서 (Declaration Order):

동일한 구체성을 가진 두 개 이상의 라우트가 있을 경우, UseEndpoints 또는 Map() 계열 메서드에서 먼저 정의된 라우트가 우선순위를 가집니다.

이 때문에 “라우트 순서” 섹션에서 언급했듯이, 더 구체적인 라우트를 항상 먼저 정의하는 것이 중요합니다.

app.UseEndpoints(endpoints =>
{
    // 이 라우트가 먼저 정의됨
    endpoints.MapGet("/products/special", () => "Special Product Page");

    // 이 라우트는 구체성이 동일하지만 나중에 정의됨
    endpoints.MapGet("/products/{name}", (string name) => $"Product by Name: {name}");

    // /products/special 요청 시, "Special Product Page"가 반환됨
    // 만약 순서가 바뀌면 "/products/{name}"에 매칭되어 "Product by Name: special"이 반환될 수 있음
});

Endpoint Selection Order는 복합적인 요소들의 상호작용으로 결정됩니다.

라우트 제한 조건은 이 선택 과정에서 라우트의 “구체성”을 높여 특정 URL 패턴에 대한 우선순위를 부여하는 핵심적인 방법입니다.

개발자는 이러한 원칙을 이해하고 라우트를 신중하게 정의하여 예상치 못한 라우팅 문제를 방지해야 합니다.

The post ASP.NET Core Route Constraints appeared first on 어제와 내일의 나 그 사이의 이야기.

미들웨어(Middleware)

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware/?view=aspnetcore-8.0

ASP.NET Core의 미들웨어는 모든 HTTP 요청과 응답 파이프라인을 형성하는 일련의 구성 요소입니다.

각 미들웨어 구성 요소는 다음을 수행할 수 있습니다:

• 들어오는 요청을 검사합니다.
• 요청 또는 응답을 수정합니다 (필요한 경우).
• 파이프라인의 다음 미들웨어를 호출하거나, 프로세스를 단락(short-circuit)시키고 자체적으로 응답을 생성합니다.

이러한 파이프라인을 통해 애플리케이션의 로직을 모듈화하고, 인증, 로깅, 오류 처리, 라우팅 등과 같은 기능을 깔끔하고 유지 관리하기 쉬운 방식으로 추가할 수 있습니다.

미들웨어 체인 (요청 파이프라인)

ASP.NET Core 요청 파이프라인은 차례로 호출되는 일련의 요청 대리자로 구성됩니다.

요청 파이프라인을 일련의 연결된 파이프라고 상상해 보세요.

각 미들웨어 조각은 이 파이프라인의 밸브와 같아서, 정보의 흐름을 제어하고 다양한 단계에서 특정 작업을 적용할 수 있습니다.

미들웨어를 등록하는 순서는 매우 중요하며, 등록된 순서대로 실행됩니다.

각 델리게이트는 다음 델리게이트를 호출하기 전과 후에 작업을 수행할 수 있습니다.

예외 처리 델리게이트는 파이프라인의 후반 단계에서 발생하는 예외를 Catch할 수 있도록 파이프라인의 초기에 호출되어야 합니다.

가장 간단한 ASP.NET Core 앱은 모든 요청을 처리하는 단일 요청 델리게이트를 설정합니다.

이 경우에는 실제 요청 파이프라인이 포함되지 않습니다.

대신, 모든 HTTP 요청에 대한 응답으로 단일 익명 함수가 호출됩니다.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello world!");
});

app.Run(); // 이 app.Run은 위의 app.Run이 파이프라인을 종료하므로 실행되지 않습니다.

Use 메서드를 사용하면 여러 요청 델리게이트를 체인으로 연결할 수 있습니다.

이때 next 매개변수는 파이프라인의 다음 델리게이트를 나타냅니다.

next 매개변수를 호출하지 않음으로써 파이프라인을 단락(short-circuit)시킬 수 있습니다.

다음 예시에서 보여주듯이, 일반적으로 next 델리게이트를 호출하기 전과 후에 모두 작업을 수행할 수 있습니다.

var builder = WebApplication.CreateBuilder(args); // 웹 애플리케이션 빌더를 생성합니다.
var app = builder.Build(); // 빌더를 사용하여 웹 애플리케이션 인스턴스를 생성합니다.

// 첫 번째 미들웨어: app.Use()를 사용하여 파이프라인에 추가합니다.
app.Use(async (context, next) =>
{
    // 응답에 쓸 수 있는 작업을 수행합니다. (예: 헤더 추가, 응답의 시작 부분 작성)
    // 이 부분의 코드는 다음 미들웨어가 실행되기 전에 실행됩니다.

    await next.Invoke(); // 다음 미들웨어(이 경우 app.Run)를 호출하여 제어를 넘깁니다.

    // 응답에 쓰지 않는 로깅 또는 다른 작업을 수행합니다.
    // 이 부분의 코드는 다음 미들웨어가 실행된 후(응답이 생성된 후) 실행됩니다.
});

// 두 번째 미들웨어: app.Run()을 사용하여 파이프라인에 추가합니다.
// app.Run()은 파이프라인을 종료하는 미들웨어입니다.
app.Run(async context =>
{
    // 이 미들웨어는 "Hello from 2nd delegate."를 응답에 작성하고 파이프라인을 종료합니다.
    await context.Response.WriteAsync("Hello from 2nd delegate.");
});

// 이 app.Run()은 위의 app.Run()이 이미 파이프라인을 종료했기 때문에 실행되지 않습니다.
app.Run();

요청 파이프라인 단락(Short-circuiting)

ASP.NET Core의 미들웨어 파이프라인에서, 특정 델리게이트(미들웨어)가 요청을 다음 델리게이트로 전달하지 않을 때 이를 요청 파이프라인을 단락(short-circuiting)시킨다고 합니다.

파이프라인 단락은 불필요한 작업을 피할 수 있기 때문에 종종 유용합니다.

예를 들어, 정적 파일 미들웨어(Static File Middleware)는 요청된 파일이 정적 파일(이미지, CSS, JavaScript 등)일 경우 해당 요청을 처리하고

파이프라인의 나머지 부분을 단락시킴으로써 종료 미들웨어(terminal middleware) 역할을 할 수 있습니다.

이렇게 되면 정적 파일을 제공한 후에는 인증이나 라우팅과 같은 다른 미들웨어들이 실행될 필요가 없으므로 효율성이 높아집니다.

단락과 next.Invoke() 이후 코드 실행

파이프라인의 추가적인 처리를 종료시키는 미들웨어보다 앞서 파이프라인에 추가된 미들웨어는 여전히 next.Invoke() 구문 이후의 코드를 처리합니다.

즉, 비록 파이프라인이 단락되어 최종 응답이 더 이상 아래로 전달되지 않더라도, next.Invoke()를 호출했던 이전 미들웨어들은 응답이 완료된 후 자신의 후처리 로직을 실행할 수 있습니다.

경고: 응답 전송 후 작업 주의

응답이 클라이언트에게 이미 전송되었거나 전송되기 시작한 후에는 next.Invoke()를 호출하거나 응답에 쓰려고 시도하지 마세요.

HttpResponse가 시작된 후에는 응답에 변경을 가하려고 하면 예외가 발생합니다.

예를 들어, 응답이 시작된 후 헤더나 상태 코드를 설정하려고 하면 예외가 발생합니다.

next.Invoke() 호출 후 응답 본문에 쓰는 것은 다음과 같은 문제를 야기할 수 있습니다:

• 프로토콜 위반: 명시된 Content-Length보다 더 많은 내용을 작성하는 것과 같은 프로토콜 위반을 초래할 수 있습니다.
• 본문 형식 손상: CSS 파일에 HTML 푸터(footer)를 작성하는 것처럼 본문 형식을 손상시킬 수 있습니다.

HasStarted 속성은 헤더가 전송되었는지 또는 본문이 작성되었는지 여부를 나타내는 유용한 힌트가 될 수 있습니다.

app.Use vs. app.Run

이 두 메서드는 파이프라인에 미들웨어를 추가하는 데 기본적이지만, 핵심적인 차이점이 있습니다:

app.Use(async (context, next) => { ... })

• 요청 수정 불가:
  마지막 단계이므로 요청을 다음으로 전달하기 전에 수정할 수 없습니다.
• 비종료(Non-Terminal) 미들웨어:
  이 유형의 미들웨어는 일반적으로 어떤 작업을 수행한 다음, next 델리게이트를 호출하여 파이프라인의 다음 미들웨어로 제어를 전달합니다.
• 요청/응답 수정 가능:
  요청을 다음으로 전달하기 전에 요청이나 응답을 변경할 수 있습니다.
• 예시:
  인증, 로깅, 커스텀 헤더 추가 등.

app.Run(async (context) => { ... })

• 종료(Terminal) 미들웨어:
  이 미들웨어는 next를 호출하지 않습니다.
  파이프라인을 종료하고 자체적으로 응답을 생성합니다.
• 최종 응답에 주로 사용:
  더 이상 처리가 필요 없는 요청(예: 간단한 메시지 반환)을 처리하는 데 일반적으로 사용됩니다.

// 여러 app.Run 호출의 결과

app.Run(async (HttpContext context) => {
    await context.Response.WriteAsync("Hello");
});

app.Run(async (HttpContext context) => {
    await context.Response.WriteAsync("Hello again");
});

app.Run(); // 이 app.Run은 위의 app.Run들이 이미 파이프라인을 종료했기 때문에 절대 실행되지 않습니다.

이 코드에서는 오직 첫 번째 app.Run 미들웨어만 실행됩니다.

“Hello”를 응답에 작성하여 파이프라인을 종료하고, 그 뒤의 app.Run (이것은 “Hello again”을 작성할 것임)은 실행될 기회를 얻지 못합니다.

// app.Use와 app.Run으로 미들웨어 체인 연결하기

// 미들웨어 1
app.Use(async (context, next) => {
    await context.Response.WriteAsync("Hello "); // 1. "Hello " 작성
    await next(context); // 2. 다음 미들웨어 호출
});

// 미들웨어 2
app.Use(async (context, next) => {
    await context.Response.WriteAsync("Hello again "); // 3. "Hello again " 작성
    await next(context); // 4. 다음 미들웨어 호출 (이 경우 app.Run)
});

// 미들웨어 3 (종료 미들웨어)
app.Run(async (HttpContext context) => {
    await context.Response.WriteAsync("Hello again"); // 5. "Hello again" 작성 후 파이프라인 종료
});

이 코드는 미들웨어를 올바르게 연결하는 방법을 보여줍니다.

1. 첫 번째 app.Use는 응답에 “Hello “를 작성하고 next를 호출하여 다음 미들웨어로 제어를 전달합니다.
2. 두 번째 app.Use는 “Hello again “을 작성하고 역시 next를 호출합니다.
3. 마지막 app.Run (종료 미들웨어)는 “Hello again”을 작성하고 파이프라인을 종료합니다.

ASP.NET Core의 커스텀 미들웨어

ASP.NET Core는 다양한 내장 미들웨어 구성 요소를 제공하지만, 때로는 애플리케이션 고유의 특정 요구 사항을 해결하기 위해 자신만의 커스텀 미들웨어를 만들어야 할 수도 있습니다.

커스텀 미들웨어를 통해 다음을 수행할 수 있습니다:

• 로직 캡슐화:
  관련 작업(예: 로깅, 보안 검사, 사용자 정의 헤더)을 재사용 가능한 구성 요소로 묶습니다.
• 동작 사용자 정의:
  애플리케이션의 요구 사항에 정확히 맞게 요청/응답 파이프라인을 조정합니다.
• 코드 구성 개선:
  미들웨어 코드를 깔끔하고 유지 관리하기 쉽게 만듭니다.

커스텀 미들웨어 클래스의 구조

IMiddleware 구현: 이 인터페이스는 단 하나의 메서드 InvokeAsync(HttpContext context, RequestDelegate next)를 요구합니다.

이 메서드는 미들웨어 로직의 핵심입니다

InvokeAsync 또는 Invoke 메서드

• context:
  HttpContext는 요청 및 응답 객체에 대한 접근을 제공합니다.
• next:
  RequestDelegate는 파이프라인의 다음 미들웨어를 호출할 수 있도록 합니다.

// MyCustomMiddleware.cs
namespace MiddlewareExample.CustomMiddleware
{
    public class MyCustomMiddleware : IMiddleware // IMiddleware 인터페이스 구현
    {
        public async Task InvokeAsync(HttpContext context, RequestDelegate next)
        {
            await context.Response.WriteAsync("My Custom Middleware - Starts\n"); // 1. 응답 시작 부분에 출력
            await next(context); // 2. 다음 미들웨어 호출
            await context.Response.WriteAsync("My Custom Middleware - Ends\n"); // 3. 다음 미들웨어 완료 후 응답 끝 부분에 출력
        }
    }

    // 쉽게 등록하기 위한 확장 메서드
    public static class CustomMiddlewareExtension
    {
        public static IApplicationBuilder UseMyCustomMiddleware(this IApplicationBuilder app)
        {
            return app.UseMiddleware<MyCustomMiddleware>();
        }
    }
}

// Program.cs (또는 Startup.cs)
using MiddlewareExample.CustomMiddleware;

// ... (다른 설정 코드) ...

builder.Services.AddTransient<MyCustomMiddleware>(); // 트랜지언트 서비스로 등록

app.Use(async (HttpContext context, RequestDelegate next) => {
    await context.Response.WriteAsync("From Middleware 1\n"); // 첫 번째 미들웨어: 시작 부분
    await next(context);
});

app.UseMyCustomMiddleware(); // 확장 메서드를 사용하여 커스텀 미들웨어 추가

app.Run(async (HttpContext context) => {
    await context.Response.WriteAsync("From Middleware 3\n"); // 세 번째 미들웨어: 파이프라인 종료
});

• 등록:
  ASP.NET Core가 필요할 때 MyCustomMiddleware 인스턴스를 생성할 수 있도록 이를 트랜지언트 서비스로 등록합니다.
• 파이프라인 통합:
  app.UseMyCustomMiddleware() 확장 메서드는 커스텀 미들웨어를 파이프라인에 추가합니다.
• 실행 순서:
  미들웨어 구성 요소는 파이프라인에 추가된 순서대로 실행됩니다. 이 경우 순서는 미들웨어 1, MyCustomMiddleware, 그리고 미들웨어 3이 됩니다.

커스텀 컨벤셔널 미들웨어 (Custom Conventional Middleware)

ASP.NET Core 미들웨어에는 두 가지 유형이 있습니다: 컨벤셔널(Conventional)과 팩토리 기반(Factory-based)

예시에서 보여진 컨벤셔널 미들웨어는 HTTP 요청 및 응답 처리를 위한 커스텀 로직을 캡슐화하는 간단하면서도 강력한 방법입니다.

주요 특징

• 클래스 기반:
  컨벤셔널 미들웨어는 클래스로 구현됩니다.
• 생성자 주입:
  의존성(있는 경우)을 생성자를 통해 받습니다.
• Invoke 메서드:
  이 메서드는 각 요청을 처리하는 로직을 포함하는 미들웨어의 핵심입니다.
• RequestDelegate:
  Invoke 메서드는 RequestDelegate 매개변수(_next로 명명)를 받습니다. 이 델리게이트는 파이프라인의 다음 미들웨어를 나타냅니다.
• 유연성:
  Invoke 메서드 내에서 요청 및 응답 객체를 완벽하게 제어할 수 있습니다.

// NameConcatenationMiddleware.cs
public class NameConcatenationMiddleware
{
    private readonly RequestDelegate _next;

    public NameConcatenationMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        if (context.Request.Query.ContainsKey("firstname") &&
            context.Request.Query.ContainsKey("lastname"))
        {
            string fullName = $"{context.Request.Query["firstname"]} {context.Request.Query["lastname"]}";
            await context.Response.WriteAsync(fullName);
            return; // 명시적으로 반환하여 다음 미들웨어 호출 방지
        }
        
        await _next(context);
    }
}

// MiddlewareExtensions.cs
public static class MiddlewareExtensions
{
    public static IApplicationBuilder UseNameConcatenation(this IApplicationBuilder builder)
    {
        return builder.UseMiddleware<NameConcatenationMiddleware>();
    }
}

미들웨어 파이프라인의 이상적인 순서

미들웨어의 순서는 애플리케이션의 동작과 효율성, 보안에 큰 영향을 미칩니다.

다음은 일반적으로 권장되는 이상적인 순서입니다

예외/오류 처리(Exception/Error Handling):

• 목적: 파이프라인의 어느 곳에서든 발생하는 예외를 Catch하고 처리합니다.
• 예시: UseExceptionHandler (프로덕션용), UseDeveloperExceptionPage (개발 환경용).
• 이유: 예외를 초기에 Catch하여 파이프라인 아래로 전파되어 더 큰 문제를 일으키는 것을 방지합니다.

HTTPS 리디렉션(HTTPS Redirection):

• 목적: 보안을 위해 HTTP 요청을 HTTPS로 리디렉션합니다.
• 예시: UseHttpsRedirection.
• 이유: 보안을 최우선으로 하여 모든 통신이 암호화되도록 합니다.

정적 파일(Static Files):

• 목적: 이미지, CSS, JavaScript 파일과 같은 정적 파일을 클라이언트에게 직접 제공합니다.
• 예시: UseStaticFiles.
• 이유: 정적 파일 요청은 빠르게 처리되어야 하며, 불필요하게 파이프라인의 다른 무거운 구성 요소를 거치지 않도록 일찍 처리합니다.

라우팅(Routing):

• 목적: URL을 기반으로 들어오는 요청을 특정 엔드포인트에 매칭합니다.
• 예시: UseRouting, UseEndpoints.
• 이유: 라우팅은 애플리케이션의 핵심 로직이 요청을 어떻게 처리할지 결정하는 기반이 됩니다.

CORS (Cross-Origin Resource Sharing):

• 목적: 다른 도메인으로부터의 안전한 교차 출처(cross-origin) 요청을 가능하게 합니다.
• 예시: UseCors.
• 이유: 인증/인가 전에 위치하여, 사전 요청(preflight request)이 불필요하게 인증/인가 미들웨어를 거치지 않도록 합니다.

인증(Authentication):

• 목적: 사용자 신원을 확인하고 사용자 주체(principal)를 설정합니다.
• 예시: UseAuthentication.
• 이유: 사용자가 누구인지 확인한 후에 리소스에 대한 접근 권한을 부여할 수 있습니다.

인가(Authorization):

• 목적: 사용자가 특정 리소스에 접근하거나 특정 작업을 수행할 수 있는지 여부를 결정합니다.
• 예시: UseAuthorization.
• 이유: 인증된 사용자에게만 권한 부여 여부를 검사합니다.

커스텀 미들웨어(Custom Middleware):

• 목적: 로깅, 기능 플래그 등 애플리케이션별 미들웨어 구성 요소를 처리합니다.
• 이유: 애플리케이션별 로직을 적절한 단계에서 파이프라인 내에 배치합니다.

MVC/Razor Pages/Minimal APIs:

• 목적: 실제 애플리케이션의 최종 엔드포인트 처리 로직을 실행합니다.
• 예시: MapControllers(), MapRazorPages(), MapGet() 등.

Program.cs 파일에 미들웨어 구성 요소가 추가되는 순서는 요청 시 미들웨어 구성 요소가 호출되는 순서를 정의하며, 응답 시에는 역순으로 호출됩니다.

이러한 순서는 보안, 성능 및 기능에 매우 중요합니다.

Program.cs의 다음 강조 표시된 코드는 보안 관련 미들웨어 구성 요소를 일반적으로 권장되는 순서로 추가하는 예시입니다:

using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using WebMiddleware.Data;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
    ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseMigrationsEndPoint();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
// app.UseCookiePolicy();

app.UseRouting();
// app.UseRateLimiter();
// app.UseRequestLocalization();
// app.UseCors();

app.UseAuthentication();
app.UseAuthorization();
// app.UseSession();
// app.UseResponseCompression();
// app.UseResponseCaching();

app.MapRazorPages();
app.MapDefaultControllerRoute();

app.Run();

UseWhen()

UseWhen()은 ASP.NET Core의 IApplicationBuilder 인터페이스에 있는 강력한 확장 메서드입니다.

이는 조건(predicate)에 따라 미들웨어를 요청 파이프라인에 조건부로 추가할 수 있도록 합니다.

즉, 특정 조건이 충족될 때만 특정 미들웨어 구성 요소가 실행되는 동적인 파이프라인을 만들 수 있습니다.

app.UseWhen(
    context => /* 여기에 조건 */, // HttpContext를 받아 true/false 반환
    app => /* 이 분기에서 실행될 미들웨어 구성 */ // 조건이 true일 때 실행될 미들웨어 파이프라인
);

• context:
  현재 요청을 나타내는 HttpContext 객체입니다.
• Predicate (조건):
  HttpContext를 받아들이고 미들웨어 분기가 실행되어야 할 경우 true를, 그렇지 않을 경우 false를 반환하는 함수입니다.
• Middleware Configuration (미들웨어 구성):
  조건이 true일 때 실행되어야 할 미들웨어 구성 요소를 구성하는 액션입니다.
  여기서 app.Use(), app.Run(), 또는 다른 미들웨어 등록 메서드를 사용합니다.

UseWhen() 작동 방식

• 조건 평가:
  요청이 들어오면 UseWhen() 메서드는 먼저 HttpContext에 대해 조건 함수를 평가합니다.
• 분기(조건이 true일 경우):
  조건이 true를 반환하면, 구성 액션에 지정된 미들웨어 분기가 실행됩니다.
  요청은 이 분기를 통해 흐르며, 수정되거나 응답을 생성할 수 있습니다.
• 메인 파이프라인 재진입:
  분기가 실행된 후(또는 조건이 false여서 건너뛰어진 경우), 요청 흐름은 메인 파이프라인으로 다시 진입하여 UseWhen() 호출 뒤에 등록된 다음 미들웨어 구성 요소로 계속 진행됩니다.

app.UseWhen(
    context => context.Request.Query.ContainsKey("username"), // 조건: 쿼리 문자열에 "username"이 있는지 확인
    app => {
        app.Use(async (context, next) =>
        {
            await context.Response.WriteAsync("Hello from Middleware branch\n"); // 분기 미들웨어: "Hello from Middleware branch" 작성
            await next(); // 다음 미들웨어 호출
        });
    });

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from middleware at main chain"); // 메인 파이프라인 미들웨어
});

• 조건:
  context.Request.Query.ContainsKey("username") 조건은 쿼리 문자열에 “username”이라는 매개변수가 포함되어 있는지 확인합니다.
• 분기 미들웨어:
  “username” 매개변수가 존재하면 분기 미들웨어가 실행됩니다.
  이 미들웨어는 응답에 “Hello from Middleware branch”를 작성하고 next를 호출하여 나머지 파이프라인이 계속되도록 합니다.
• 메인 파이프라인:
  마지막 app.Run 미들웨어는 메인 파이프라인의 일부입니다.
  이는 응답에 “Hello from middleware at main chain”을 작성합니다.

UseWhen() 사용 시점

• 조건부 기능:
  요청에 따라 특정 기능을 활성화하거나 비활성화합니다 (예: 특정 사용자에게만 로깅, 쿼리 매개변수에 따른 캐싱 규칙 적용).
• 동적 파이프라인:
  다양한 요청에 맞춰 조정되는 파이프라인을 만듭니다 (예: 특정 경로에 대해 다른 인증 미들웨어).
• A/B 테스트:
  실험을 위해 사용자 하위 집합을 대체 미들웨어 분기를 통해 라우팅합니다.
• 디버깅 및 진단:
  개발 환경에서만 진단 미들웨어를 적용합니다.

The post ASP.NET Core의 미들웨어(Middleware) appeared first on 어제와 내일의 나 그 사이의 이야기.

1. 패키지 설치 확인

프로젝트 파일 (.csproj)에 다음이 반드시 있어야 합니다:

<ItemGroup>
  <PackageReference Include="MimeKit" Version="[버전]" />
  <PackageReference Include="MailKit" Version="[버전]" />
</ItemGroup>

예시
<ItemGroup>
  <PackageReference Include="MimeKit" Version="4.13.0" />
  <PackageReference Include="MailKit" Version="4.13.0" />
</ItemGroup>

• 위 항목이 없다면 .csproj 파일에 직접 추가하거나 아래 명령어로 설치

2. NuGet 패키지 수동 설치 (Visual Studio 없이)

dotnet add package MimeKit --version [버전]
dotnet add package MailKit --version [버전]


예시 
dotnet add package MimeKit --version 4.13.0
dotnet add package MailKit --version 4.13.0

3. 패키지 복원

아래 명령어로 패키지를 복원합니다:

dotnet restore

4. MailKit 간단한 사용 예시

using MimeKit;
using MailKit.Net.Smtp;
using MailKit.Security;

namespace "namespace"
{
    public class EmailService : IEmailService
    {
        private readonly ILogger<EmailService> _logger;

        public EmailService(ILogger<EmailService> logger)
        {
            _logger = logger;
        }

        public async Task SendEmailAsync(string to, string subject, string body, string mimeType = "plain")
        {
            var email = new MimeMessage();
            email.From.Add(MailboxAddress.Parse("noreply@lycos7560.com"));
            email.To.Add(MailboxAddress.Parse(to));
            email.Subject = subject;

            email.Body = new TextPart(mimeType)
            {
                Text = body
            };

            using var smtp = new SmtpClient();
            try
            {
                await smtp.ConnectAsync("localhost", 포트, SecureSocketOptions.None); 
                await smtp.SendAsync(email);
                await smtp.DisconnectAsync(true);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "메일 전송 실패");
                throw;
            }
        }
    }

}

namespace "namespace"
{
    public interface IEmailService
    {
        public Task SendEmailAsync(string to, string subject, string body, string mimeType = "plain");
    }
}

The post MimeKit과 MailKit 패키지 빌드 오류 appeared first on 어제와 내일의 나 그 사이의 이야기.

UseStaticFiles

https://learn.microsoft.com/ko-kr/aspnet/core/fundamentals/static-files?view=aspnetcore-8.0

UseStaticFiles는 ASP.NET Core 애플리케이션에서 정적 파일(Static Files)을 제공하기 위해 사용되는 미들웨어입니다.

정적 파일이란 웹 서버가 클라이언트에 그대로 전달하는 파일들로, 웹 페이지를 구성하는 데 필요한 이미지, CSS 파일, JavaScript 파일, 폰트 등을 의미합니다.

1⃣ UseStaticFiles 미들웨어의 개념

ASP.NET Core는 기본적으로 보안을 위해 웹 루트(wwwroot 폴더) 외부의 파일에 대한 직접적인 웹 접근을 허용하지 않습니다.

UseStaticFiles 미들웨어는 이러한 제한을 해제하고, 웹 서버가 특정 디렉토리(기본값은 wwwroot)에 있는 정적 파일 요청을 처리할 수 있도록 파이프라인에 기능을 추가합니다.

이 미들웨어가 없으면, 브라우저가 /css/site.css나 /images/logo.png 같은 경로로 정적 파일을 요청했을 때, 서버는 해당 파일을 찾지 못하고 404 Not Found 오류를 반환하게 됩니다.

UseStaticFiles를 추가함으로써, ASP.NET Core 애플리케이션은 이러한 요청을 가로채어 지정된 위치에서 파일을 찾아 클라이언트에게 응답할 수 있게 됩니다.

2⃣ UseStaticFiles의 주요 역할

• 정적 파일 서빙 활성화:
  웹 루트(wwwroot)에 있는 HTML, CSS, JavaScript, 이미지 등 정적 파일을 웹 브라우저가 요청할 수 있도록 허용합니다.
• 파일 경로 매핑:
  들어오는 URL 요청을 서버의 실제 파일 시스템 경로에 매핑합니다.
• 캐싱 헤더 추가:
  효율적인 캐싱을 위해 Cache-Control 같은 HTTP 응답 헤더를 자동으로 추가하여 브라우저가 정적 파일을 효율적으로 캐싱하고, 다음 요청 시 서버에 다시 요청하는 대신 로컬 캐시를 사용하도록 돕습니다.
• MIME 타입 추론:
  파일 확장자를 기반으로 올바른 MIME 타입(Content-Type 헤더)을 응답에 포함하여 브라우저가 파일을 올바르게 해석하도록 합니다.
• 디렉터리 브라우징 방지:
  기본적으로 보안을 위해 디렉터리 목록을 보여주지 않습니다. (이를 허용하려면 추가 설정 필요)

3⃣ UseStaticFiles 사용 방법

UseStaticFiles 미들웨어는 보통 Program.cs 파일의 Configure 메서드에서 다른 미들웨어들과 함께 구성됩니다.

기본 사용법 (wwwroot 폴더)

가장 기본적인 사용법은 웹 루트(wwwroot) 폴더에 있는 정적 파일을 제공하는 것입니다.

이 경우, UseStaticFiles() 메서드를 인자 없이 호출하면 됩니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages(); // 또는 AddControllersWithViews 등

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();

// UseStaticFiles 미들웨어를 추가합니다.
// 이는 wwwroot 폴더의 정적 파일을 제공합니다.
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages(); // 또는 app.MapControllerRoute 등

app.Run();

• 위 코드에서 UseStaticFiles()를 호출하면, ASP.NET Core 프로젝트 템플릿에 기본으로 생성되는 wwwroot 폴더의 내용이 웹에 노출됩니다.
• 예를 들어, wwwroot/css/site.css 파일이 있다면, 브라우저에서 http://localhost:포트번호/css/site.css로 접근할 수 있게 됩니다.

다른 폴더의 정적 파일 제공

wwwroot 외의 다른 폴더에 있는 정적 파일을 제공하고 싶을 때는 StaticFileOptions를 구성하여 경로를 지정할 수 있습니다.

// Program.cs

var builder = WebApplication.CreateBuilder(args);

// ... 서비스 설정 ...

var app = builder.Build();

// ... 기타 미들웨어 설정 ...

// wwwroot 외의 'MyStaticFiles' 폴더에 있는 정적 파일을 제공합니다.
// URL 경로는 `/MyFiles`로 시작합니다.
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "MyStaticFiles")),
    RequestPath = "/MyFiles" // URL 프리픽스
});

// 기존 wwwroot 폴더도 계속 사용하려면 이 줄도 유지합니다.
app.UseStaticFiles();

app.UseRouting();

// ... 나머지 미들웨어 및 엔드포인트 설정 ...

app.Run();

• FileProvider: PhysicalFileProvider를 사용하여 서버의 실제 파일 시스템 경로를 지정합니다.
  ContentRootPath는 애플리케이션의 기본 디렉토리를 나타냅니다.
• RequestPath: 이 StaticFileOptions 인스턴스에 의해 제공되는 파일에 접근하기 위한 URL 프리픽스를 정의합니다.
  위 예시에서는 MyStaticFiles 폴더에 있는 image.png 파일을 http://localhost:포트번호/MyFiles/image.png로 접근할 수 있습니다.
• UseStaticFiles()를 여러 번 호출하여 여러 정적 파일 소스를 구성할 수 있습니다.

디렉터리 브라우징 활성화 (권장하지 않음)

보안상의 이유로 기본적으로 비활성화되어 있지만, 개발 목적으로 디렉터리 목록을 웹에 노출해야 하는 경우 UseDirectoryBrowser 미들웨어를 함께 사용할 수 있습니다.

// Program.cs

var builder = WebApplication.CreateBuilder(args);

// 서비스에 디렉터리 브라우징 추가
builder.Services.AddDirectoryBrowser();

var app = builder.Build();

// ... 기타 미들웨어 설정 ...

// 'MyDirectory' 폴더를 웹에 노출하고, 해당 폴더의 내용을 `/MyFolder` URL로 브라우징할 수 있도록 합니다.
app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(app.Environment.ContentRootPath, "MyDirectory")),
    RequestPath = "/MyFolder"
});

// 'MyDirectory' 폴더의 정적 파일도 제공합니다.
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(app.Environment.ContentRootPath, "MyDirectory")),
    RequestPath = "/MyFolder"
});

// ... 나머지 미들웨어 및 엔드포인트 설정 ...

app.Run();

• 경고: UseDirectoryBrowser는 보안 취약점이 될 수 있으므로, 운영 환경에서는 절대 사용해서는 안 됩니다.
  오직 개발/디버깅 목적으로만 제한적으로 사용해야 합니다.

4⃣ UseStaticFiles 미들웨어의 위치

미들웨어 파이프라인에서 UseStaticFiles의 위치는 중요합니다.

• 일반적으로 UseStaticFiles는 UseRouting 미들웨어 앞에 위치하는 것이 좋습니다.
  이렇게 하면 라우팅 시스템이 복잡한 컨트롤러/엔드포인트 매칭 로직을 시작하기 전에, 정적 파일 요청을 먼저 빠르게 처리하고 응답할 수 있어 성능에 유리합니다.
• 만약 UseStaticFiles가 UseRouting 뒤에 오면, 정적 파일 요청도 라우팅 시스템의 대상이 되어 불필요한 처리 오버헤드가 발생할 수 있습니다.
• 하지만, 특정 미들웨어(예: 인증/인가 미들웨어)를 통해 정적 파일 접근을 제어하고 싶다면, 해당 미들웨어 뒤에 UseStaticFiles를 배치할 수도 있습니다.
  이 경우 정적 파일 요청도 인증/인가 절차를 거치게 됩니다.

UseStaticFiles 미들웨어는 ASP.NET Core 웹 애플리케이션에서 정적인 웹 리소스를 효율적이고 안전하게 제공하는 데 필수적인 구성 요소입니다.

The post ASP.NET Core – UseStaticFiles appeared first on 어제와 내일의 나 그 사이의 이야기.

개요

Microsoft.Extensions.Hosting 네임스페이스는 .NET 애플리케이션의 호스팅 모델(Hosting Model)을 제공하는 핵심 구성 요소입니다.

Host 클래스는 이 모델의 시작점 역할을 하며, 애플리케이션의 생명 주기(lifecycle), 구성(configuration), 의존성 주입(dependency injection, DI), 로깅(logging) 등 다양한 인프라 서비스를 중앙 집중식으로 관리합니다.

이 호스팅 모델은 ASP.NET Core 애플리케이션에서 시작되었지만, 현재는 콘솔 애플리케이션, 백그라운드 서비스, Windows 서비스, WPF 애플리케이션 등 다양한 종류의 .NET 애플리케이션에서 표준적인 방식으로 사용되고 있습니다.

1. Host 클래스의 목적과 역할

Host 클래스는 특정 애플리케이션 유형에 구애받지 않고, 공통적인 인프라 기능을 쉽게 통합하고 관리할 수 있도록 설계되었습니다.

• 생명 주기 관리: 애플리케이션의 시작(StartAsync) 및 종료(StopAsync)를 관리하고, 이 과정에서 필요한 서비스들이 올바른 순서로 초기화되고 정리될 수 있도록 합니다.
• 의존성 주입 (DI): 애플리케이션 전반에 걸쳐 강력한 DI 컨테이너를 제공하여, 서비스 간의 느슨한 결합을 촉진하고 테스트 용이성을 향상시킵니다.
• 구성 (Configuration): appsettings.json, 환경 변수, 명령줄 인수 등 다양한 소스에서 설정을 로드하고 관리하는 일관된 방법을 제공합니다.
• 로깅 (Logging): 다양한 로깅 프로바이더(콘솔, 파일, 데이터베이스 등)를 쉽게 통합하고, 로깅 레벨을 유연하게 제어할 수 있도록 합니다.
• 백그라운드 서비스 (IHostedService): 장시간 실행되는 백그라운드 작업을 호스트의 생명 주기에 통합하여 관리할 수 있도록 합니다. 이는 API를 제공하지 않고 단순히 작업을 수행하는 서비스에 특히 유용합니다.

2. Host 클래스 핵심 인터페이스 및 메서드

Host 클래스 자체보다는, 이와 관련된 IHost 및 IHostBuilder 인터페이스를 이해하는 것이 중요합니다.

(1) IHostBuilder 인터페이스

IHostBuilder는 호스트를 구성(Configure)하는 데 사용되는 인터페이스입니다.

Host.CreateDefaultBuilder() 메서드가 반환하는 객체가 바로 IHostBuilder 타입입니다.

이 빌더를 통해 다음을 정의할 수 있습니다:

• ConfigureAppConfiguration:
  설정 소스(파일, 환경 변수 등)를 추가하거나 커스터마이징합니다.

.ConfigureAppConfiguration((context, config) =>
{
    config.AddJsonFile("custom.json", optional: true)
          .AddEnvironmentVariables()
          .AddCommandLine(args);
})

• ConfigureLogging:
  로깅 프로바이더(콘솔, 디버그, 파일 등)를 추가하고 로깅 필터링 규칙을 정의합니다.

.ConfigureLogging((context, logging) =>
{
    logging.AddConsole()
           .AddDebug()
           .SetMinimumLevel(LogLevel.Information);
})

• ConfigureServices:
  의존성 주입 컨테이너에 애플리케이션의 서비스들을 등록합니다.
  AddSingleton, AddScoped, AddTransient 등의 메서드를 사용하여 서비스의 생명 주기를 지정할 수 있습니다.

.ConfigureServices((context, services) =>
{
    services.AddSingleton<ISingletonService, SingletonService>();
    services.AddScoped<IScopedService, ScopedService>();
    services.AddTransient<ITransientService, TransientService>();
    services.AddHostedService<MyBackgroundService>();
})

• UseConsoleLifetime:
  콘솔 애플리케이션의 경우, Ctrl+C와 같은 콘솔 시그널을 감지하여 호스트를 정상적으로 종료하도록 설정합니다.
  (이는 Host.CreateDefaultBuilder()에 의해 기본적으로 포함됩니다.)
• Build():
  IHostBuilder에 정의된 모든 구성을 기반으로 최종 IHost 인스턴스를 생성합니다.

(2) IHost 인터페이스

IHost는 빌드된 호스트 인스턴스를 나타내며, 실제로 애플리케이션을 실행하고 관리하는 데 사용됩니다.

주요 메서드는 다음과 같습니다

• Services:
  등록된 모든 서비스 인스턴스에 접근할 수 있는 IServiceProvider를 제공합니다.
  이를 통해 런타임에 필요한 서비스를 resolve(가져오기)할 수 있습니다.
• StartAsync(CancellationToken cancellationToken):
  호스트를 비동기적으로 시작합니다. 이 메서드가 호출되면 등록된 모든 IHostedService 인스턴스의 StartAsync 메서드가 호출됩니다.
• StopAsync(CancellationToken cancellationToken):
  호스트를 비동기적으로 종료합니다. 등록된 모든 IHostedService 인스턴스의 StopAsync 메서드가 호출되어 리소스를 정리할 기회를 줍니다.
• RunAsync(CancellationToken cancellationToken = default):
  StartAsync를 호출하고, 호스트가 종료될 때까지 대기한 후 StopAsync를 호출합니다.
  대부분의 콘솔 애플리케이션에서 메인 실행 루프로 사용됩니다.

(3) IHostedService 인터페이스

IHostedService는 호스트의 생명 주기에 통합되어 백그라운드 작업을 수행하는 서비스들을 정의하는 인터페이스입니다.

StartAsync와 StopAsync 두 가지 메서드를 구현해야 합니다.

• StartAsync(CancellationToken cancellationToken):
  호스트가 시작될 때 호출됩니다. 장시간 실행되는 작업을 시작하는 데 사용됩니다.
• StopAsync(CancellationToken cancellationToken):
  호스트가 종료될 때 호출됩니다. StartAsync에서 시작된 작업을 정상적으로 중지하고 리소스를 정리하는 데 사용됩니다.

3. Host.CreateDefaultBuilder() 메서드의 이점

이 메서드는 많은 “관습(conventions)”을 제공하여 애플리케이션 초기 설정을 간소화하는 장점이 있습니다.

• 일관성:
  모든 .NET 애플리케이션 유형(웹, 콘솔, 백그라운드 서비스)에서 동일한 방식으로 인프라를 설정할 수 있게 하여 코드의 일관성을 유지합니다.
• 생산성:
  설정, 로깅, DI 등 반복적인 초기화 코드를 작성할 필요 없이 바로 비즈니스 로직에 집중할 수 있도록 합니다.
• 확장성:
  기본 설정을 사용하면서도 ConfigureAppConfiguration, ConfigureServices 등의 메서드를 통해 언제든지 필요에 따라 커스터마이징하고 확장할 수 있습니다.
• 테스트 용이성:
  DI 컨테이너를 중심으로 설계되어, 단위 테스트 및 통합 테스트에서 의존성을 쉽게 Mocking하거나 대체할 수 있습니다.
  참고: Mocking – 테스트 코드 작성 시 가짜 객체(Mock)를 만들어 실제 객체 대신 사용하는 기법

예시 코드: 콘솔 애플리케이션에서 Host 사용하기

콘솔 애플리케이션에서 Host 클래스를 사용하여 백그라운드 서비스(카운터)를 실행하고, 설정 및 로깅을 사용하는 예제

• Microsoft.Extensions.Hosting NuGet 패키지를 설치

dotnet add package Microsoft.Extensions.Hosting

• appsettings.json 파일을 추가하고 내용을 작성합니다.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AppConfig": {
    "IntervalSeconds": 2
  }
}

• Services/MyBackgroundService.cs (커스텀 IHostedService 구현):

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Configuration; // IConfiguration 주입을 위해 추가
using System;
using System.Threading;
using System.Threading.Tasks;

namespace MyConsoleApp.Services
{
    // IHostedService를 구현하여 호스트의 생명 주기에 통합될 백그라운드 서비스를 정의합니다.
    public class MyBackgroundService : IHostedService, IDisposable
    {
        private readonly ILogger<MyBackgroundService> _logger;
        private readonly IConfiguration _configuration;
        private Timer? _timer;
        private int _executionCount = 0;
        private int _intervalSeconds;

        public MyBackgroundService(ILogger<MyBackgroundService> logger, IConfiguration configuration)
        {
            _logger = logger;
            _configuration = configuration;

            // appsettings.json에서 설정 값 읽기
            _intervalSeconds = _configuration.GetValue<int>("AppConfig:IntervalSeconds", 5); // 기본값 5초
        }

        // 호스트가 시작될 때 호출됩니다.
        public Task StartAsync(CancellationToken cancellationToken)
        {
            _logger.LogInformation("MyBackgroundService가 시작되었습니다.");

            // 타이머를 설정하여 지정된 간격마다 DoWork 메서드를 호출합니다.
            _timer = new Timer(DoWork, null, TimeSpan.Zero, TimeSpan.FromSeconds(_intervalSeconds));

            return Task.CompletedTask; // 비동기 작업 시작을 알리고 즉시 반환
        }

        // 타이머에 의해 주기적으로 호출되는 실제 작업 메서드
        private void DoWork(object? state)
        {
            var count = Interlocked.Increment(ref _executionCount);
            _logger.LogInformation(
                "MyBackgroundService가 {count}번째 작업을 수행 중입니다. 현재 시간: {time}",
                count, DateTimeOffset.Now);
        }

        // 호스트가 종료될 때 호출됩니다.
        public Task StopAsync(CancellationToken cancellationToken)
        {
            _logger.LogInformation("MyBackgroundService가 중지되고 있습니다.");

            // 타이머를 중지하고 리소스를 해제합니다.
            // Change(Timeout.Infinite, 0)은 타이머를 비활성화하는 표준 방법입니다.
            _timer?.Change(Timeout.Infinite, 0);

            _logger.LogInformation("MyBackgroundService가 중지되었습니다.");
            return Task.CompletedTask; // 작업 완료를 알립니다.
        }

        // 리소스 해제를 위한 Dispose 메서드 (IHostedService는 IDisposable을 구현하는 경우가 많음)
        public void Dispose()
        {
            _timer?.Dispose();
        }
    }
}

• Program.cs 구현:

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using MyConsoleApp.Services; // MyBackgroundService를 사용하기 위해 추가
using System;
using System.Threading.Tasks;

namespace MyConsoleApp
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("콘솔 애플리케이션 호스트가 시작됩니다. 종료하려면 Ctrl+C를 누르세요.");

            // 1. IHostBuilder 인스턴스 생성: Host.CreateDefaultBuilder()는 기본적인 구성(config, logging, DI)을 설정합니다.
            var builder = Host.CreateDefaultBuilder(args)
                // 2. 서비스 컨테이너 구성: 의존성 주입을 위한 서비스들을 등록합니다.
                .ConfigureServices((hostContext, services) =>
                {
                    // MyBackgroundService를 IHostedService로 등록합니다.
                    // 호스트가 시작될 때 StartAsync가 호출되고, 종료될 때 StopAsync가 호출됩니다.
                    services.AddHostedService<MyBackgroundService>();

                    // 여기에 다른 서비스들도 등록할 수 있습니다. 예:
                    // services.AddSingleton<IMyService, MyService>();
                    // services.AddScoped<IOtherService, OtherService>();
                })
                // 3. 로깅 구성 (선택 사항: CreateDefaultBuilder가 기본 설정 제공하지만, 커스터마이징 가능)
                .ConfigureLogging(logging =>
                {
                    logging.ClearProviders(); // 기본 로깅 프로바이더를 지우고 새로 추가하거나
                    logging.AddConsole();    // 콘솔 로거를 추가합니다.
                    // logging.AddDebug();    // 디버그 로거 추가
                });
                // 4. 기타 구성 (선택 사항: 파일 경로, 환경 등)
                // .UseContentRoot(Directory.GetCurrentDirectory())
                // .UseEnvironment("Development")
                // .ConfigureAppConfiguration((hostingContext, config) => {
                //    config.AddJsonFile("custom.json", optional: true);
                // });

            // 5. IHost 인스턴스 빌드: 구성된 빌더를 바탕으로 실제 호스트를 생성합니다.
            var host = builder.Build();

            // 6. 호스트 실행: 등록된 모든 IHostedService를 시작하고 애플리케이션 종료를 대기합니다.
            // Ctrl+C 시그널을 감지하여 정상적으로 종료됩니다.
            await host.RunAsync();

            Console.WriteLine("콘솔 애플리케이션 호스트가 종료되었습니다.");
        }
    }
}

The post Microsoft.Extensions.Hosting, 호스팅 모델(Hosting Model) appeared first on 어제와 내일의 나 그 사이의 이야기.

ASP.NET Identity는 .NET 애플리케이션에서 사용자 인증과 권한 관리를 담당하는 시스템입니다.

이 시스템은 7개의 핵심 테이블로 구성되어 있으며, 각각은 특별한 역할을 수행합니다.

전체 구조 개요

 사용자 (AspNetUsers)
     다대다 관계
 역할 (AspNetRoles)
    
 권한/정보 (Claims)
 로그인 정보 (Logins, Tokens)

1. AspNetUsers – 사용자 기본 정보

역할: 회원가입한 사용자들의 기본 정보를 저장하는 메인 테이블

주요 필드 설명

보안 관련 필드들

SecurityStamp: 보안이 변경될 때마다 갱신되는 “도장”

• 비밀번호 변경, 이메일 변경 시 자동 갱신
• 이전 로그인 세션들을 무효화하는 역할

ConcurrencyStamp: 동시 수정 방지 “버전 번호”

• 여러 사용자가 같은 계정을 동시에 수정하는 것을 방지

실제 사용 예시

// 사용자 계정 잠금 확인
if (user.LockoutEnd.HasValue && user.LockoutEnd > DateTime.UtcNow)
{
    // 계정이 잠겨있음
    return "계정이 일시적으로 잠겨있습니다.";
}

// 로그인 실패 횟수 증가
user.AccessFailedCount++;
if (user.AccessFailedCount >= 5)
{
    user.LockoutEnd = DateTime.UtcNow.AddMinutes(30);
}

2. AspNetRoles – 역할 정의

역할: 사용자들을 그룹으로 분류하는 역할(Role) 정보 저장

주요 필드

일반적인 역할 예시

// 기본 역할들
var roles = new[]
{
    new IdentityRole { Name = "SuperAdmin", NormalizedName = "SUPERADMIN" },
    new IdentityRole { Name = "Admin", NormalizedName = "ADMIN" },
    new IdentityRole { Name = "Manager", NormalizedName = "MANAGER" },
    new IdentityRole { Name = "Employee", NormalizedName = "EMPLOYEE" },
    new IdentityRole { Name = "Customer", NormalizedName = "CUSTOMER" }
};

3. AspNetUserRoles – 사용자-역할 연결

역할: 어떤 사용자가 어떤 역할을 가지는지 매핑하는 중간 테이블

구조

관계 예시

사용자 "김철수" (UserId: user123)
├── Admin 역할 (RoleId: role-admin)
└── Manager 역할 (RoleId: role-manager)

사용자 "이영희" (UserId: user456)
└── Employee 역할 (RoleId: role-employee)

실제 사용법

// 사용자에게 역할 할당
await userManager.AddToRoleAsync(user, "Admin");

// 사용자의 모든 역할 조회
var userRoles = await userManager.GetRolesAsync(user);
// 결과: ["Admin", "Manager"]

// 특정 역할 확인
bool isAdmin = await userManager.IsInRoleAsync(user, "Admin");

4. Claims 시스템 – 세부 권한 관리

클레임(Claim)이란? 사용자나 역할에 대한 “주장” 또는 “속성”을 나타내는 이름-값 쌍입니다.

클레임 vs 역할 비교

AspNetRoleClaims – 역할별 클레임

역할: 특정 역할에 속한 모든 사용자가 공통으로 가지는 권한/속성

실제 예시:

// "Admin" 역할에 클레임 추가
var claims = new[]
{
    new Claim("Permission", "CanManageUsers"),
    new Claim("Permission", "CanDeletePosts"),
    new Claim("Permission", "CanViewReports"),
    new Claim("Department", "Management")
};

foreach (var claim in claims)
{
    await roleManager.AddClaimAsync(adminRole, claim);
}

AspNetUserClaims – 개인별 클레임

역할: 특정 사용자에게만 부여되는 개별적인 권한/속성

실제 예시:

// 특정 사용자에게만 베타 기능 접근 권한 부여
var betaClaim = new Claim("Feature", "BetaAccess");
await userManager.AddClaimAsync(user, betaClaim);

// VIP 고객 표시
var vipClaim = new Claim("CustomerLevel", "VIP");
await userManager.AddClaimAsync(user, vipClaim);

5. AspNetUserLogins – 외부 로그인 연동

역할: 구글, 페이스북 등 외부 서비스를 통한 로그인 정보 저장

구조

연동 과정 예시

1. 사용자가 "구글로 로그인" 클릭
2. 구글에서 인증 완료 후 사용자 정보 반환 (ProviderKey: google-12345)
3. AspNetUserLogins 테이블에서 해당 ProviderKey 검색
4. 기존 계정이 있으면 로그인, 없으면 새 계정 생성

실제 구현

// 외부 로그인 정보 추가
var loginInfo = new UserLoginInfo("Google", "google-12345", "Google");
await userManager.AddLoginAsync(user, loginInfo);

// 사용자의 모든 외부 로그인 조회
var logins = await userManager.GetLoginsAsync(user);
// 결과: [{ Provider: "Google", Key: "google-12345" }, ...]

6. AspNetUserTokens – 인증 토큰 관리

역할: 사용자별 각종 보안 토큰 저장 (리프레시 토큰, 인증 코드 등)

구조

토큰 유형별 예시

1. 리프레시 토큰

// 리프레시 토큰 저장
await userManager.SetAuthenticationTokenAsync(
    user, "MyApp", "RefreshToken", "abc123def456ghi789");

2. 이메일 인증 토큰

// 이메일 인증 토큰 생성 및 저장
var emailToken = await userManager.GenerateEmailConfirmationTokenAsync(user);
// 자동으로 AspNetUserTokens에 저장됨

3. 비밀번호 재설정 토큰

// 비밀번호 재설정 토큰 생성
var resetToken = await userManager.GeneratePasswordResetTokenAsync(user);

권한 검사 실제 활용법

1. 컨트롤러에서 역할 기반 권한 검사

[Authorize(Roles = "Admin,Manager")]
public class AdminController : Controller
{
    public IActionResult Dashboard()
    {
        return View();
    }
}

2. 클레임 기반 권한 검사

[Authorize(Policy = "CanManageUsers")]
public class UserManagementController : Controller
{
    public async Task<IActionResult> DeleteUser(string userId)
    {
        // 사용자 삭제 로직
        return Ok();
    }
}

// Startup.cs에서 정책 정의
services.AddAuthorization(options =>
{
    options.AddPolicy("CanManageUsers", policy =>
        policy.RequireClaim("Permission", "CanManageUsers"));
});

3. 코드에서 동적 권한 검사

public async Task<IActionResult> SomeAction()
{
    // 현재 사용자가 특정 클레임을 가지고 있는지 확인
    if (User.HasClaim("Permission", "CanDeletePosts"))
    {
        // 게시물 삭제 가능
    }
    
    // 역할 확인
    if (User.IsInRole("Admin"))
    {
        // 관리자 전용 기능
    }
    
    return View();
}

실무 시나리오 예시

회사 내부 시스템 권한 설계

1. 역할 구조

SuperAdmin (최고 관리자)
├── Admin (일반 관리자)
├── HRManager (인사 관리자)
├── ProjectManager (프로젝트 관리자)
├── Developer (개발자)
├── Designer (디자이너)
└── Intern (인턴)

2. 클레임 설계

// 부서별 클레임
ClaimType: "Department"
Values: "Engineering", "Design", "HR", "Marketing"

// 권한별 클레임
ClaimType: "Permission"
Values: "ViewSalary", "EditProject", "DeleteUser", "ViewReports"

// 레벨별 클레임
ClaimType: "Level"
Values: "Senior", "Junior", "Lead"

3. 실제 적용

// 사용자 "김개발"의 권한 설정
var developer = await userManager.FindByNameAsync("kim_developer");

// 역할 할당
await userManager.AddToRoleAsync(developer, "Developer");

// 개인 클레임 할당
await userManager.AddClaimAsync(developer, new Claim("Department", "Engineering"));
await userManager.AddClaimAsync(developer, new Claim("Level", "Senior"));
await userManager.AddClaimAsync(developer, new Claim("Permission", "ViewReports"));

4. 권한 검사

// 급여 정보는 HR 부서와 본인만 볼 수 있음
[Authorize]
public async Task<IActionResult> ViewSalary(string userId)
{
    var currentUser = await userManager.GetUserAsync(User);
    
    // 본인 정보이거나 HR 부서인 경우만 허용
    if (currentUser.Id == userId || 
        User.HasClaim("Department", "HR"))
    {
        return View();
    }
    
    return Forbid();
}

테이블 간 관계 요약

AspNetUsers (사용자)
    ├── AspNetUserRoles → AspNetRoles (역할)
    ├── AspNetUserClaims (개인 클레임)
    ├── AspNetUserLogins (외부 로그인)
    └── AspNetUserTokens (인증 토큰)

AspNetRoles (역할)
    └── AspNetRoleClaims (역할별 클레임)

핵심 포인트

1. 역할(Role)은 사용자를 그룹으로 분류하는 개념
2. 클레임(Claim)은 세부적인 권한과 속성을 정의하는 개념
3. 역할 클레임은 해당 역할의 모든 사용자에게 적용
4. 사용자 클레임은 특정 사용자에게만 적용
5. 외부 로그인으로 여러 인증 방식 통합 가능
6. 토큰으로 다양한 인증 시나리오 지원

이러한 구조를 통해 복잡한 권한 관리와 인증 시스템을 유연하고 안전하게 구현할 수 있습니다.

The post ASP.NET Identity 데이터베이스 appeared first on 어제와 내일의 나 그 사이의 이야기.

ASP.NET Core 파일 처리: FileResult 및 인터페이스

ASP.NET Core 애플리케이션에서 파일은 핵심적인 요소입니다.

클라이언트로부터 파일을 업로드 받거나(Upload), 서버에 있는 파일을 클라이언트에게 제공(Download/Serve)하는 등 다양한 시나리오에서 파일을 효율적이고 안전하게 다루는 것이 중요합니다.

파일을 클라이언트에게 전송하는 주요 FileResult 유형(FileContentResult, VirtualFileResult, PhysicalFileResult)의 차이점과

파일 업로드, 파일 시스템 접근, 환경 정보 제공 등 파일 관련하여 알아야 할 핵심 인터페이스와 개념들을 정리합니다.

1⃣ File Download 및 Serving을 위한 FileResult 유형

ASP.NET Core MVC/API에서 컨트롤러 액션 메서드가 파일을 HTTP 응답으로 스트리밍할 때 사용하는 IActionResult의 파생 클래스들입니다.

파일 데이터를 가져오는 방식과 경로를 해석하는 방식에 따라 구분됩니다.

FileContentResult

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.mvc.filecontentresult?view=aspnetcore-8.0

파일의 내용이 이미 byte[] 배열 형태로 메모리에 로드되어 있을 때 사용됩니다.

웹 서버는 이 바이트 배열을 그대로 클라이언트에게 스트리밍합니다.

• 정의:
  Microsoft.AspNetCore.Mvc.FileContentResult
• 데이터 원본:
  byte[] (메모리)
• 메모리 사용:
  높음. 파일의 모든 내용이 메모리에 로드되므로, 큰 파일을 처리할 경우 메모리 부족 문제가 발생할 수 있습니다.
• 성능:
  작은 파일이나 동적으로 생성된 파일에 적합합니다. 대용량 파일에는 비효율적입니다.

주요 사용처:

• 동적으로 생성된 파일:
  이미지 생성 라이브러리(예: System.Drawing.Common, ImageSharp)로 런타임에 생성된 이미지.
• 데이터베이스에 저장된 파일:
  파일 데이터가 BLOB(Binary Large Object) 형태로 데이터베이스에 저장되어 있으며, 이를 byte[]로 읽어와야 하는 경우.
• 작은 파일:
  메모리 오버헤드가 무시할 만한 수준의 작은 파일.

생성자 매개변수:

• byte[] fileContents: 전송할 파일의 바이트 배열 데이터.
• string contentType: 파일의 MIME 타입 (예: “image/png”, “application/pdf”, “text/plain”).
• string? fileDownloadName (선택 사항): 브라우저가 파일을 다운로드할 때 제안할 파일 이름.
  이 매개변수를 지정하면 Content-Disposition 헤더가 attachment로 설정되어 브라우저가 파일을 인라인으로 표시하는 대신 다운로드하도록 유도합니다.

예시:

using Microsoft.AspNetCore.Mvc;
using System.Text;

public class DynamicFileController : Controller
{
    // GET: /DynamicFile/GenerateText
    public IActionResult GenerateText()
    {
        var content = "이것은 동적으로 생성된 텍스트 파일입니다. " +
                      "현재 시간: " + DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
        byte[] fileBytes = Encoding.UTF8.GetBytes(content);

        return File(fileBytes, "text/plain", "generated_text.txt");
    }

    // GET: /DynamicFile/GetImageFromDatabase
    public IActionResult GetImageFromDatabase()
    {
        // 실제 시나리오에서는 DB에서 byte[]를 읽어옵니다.
        // 여기서는 예시를 위해 더미 바이트 배열을 사용합니다.
        byte[] imageBytes = new byte[] { /* ... PNG 이미지 바이트 데이터 ... */ };

        return File(imageBytes, "image/png", "db_image.png");
    }
}

VirtualFileResult

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.mvc.virtualfileresult?view=aspnetcore-8.0

웹 애플리케이션의 가상 경로(Virtual Path)를 사용하여 파일을 제공할 때 사용됩니다.

ASP.NET Core는 이 가상 경로를 실제 파일 시스템 경로로 변환하여 파일을 찾아 클라이언트에 스트리밍합니다.

• 정의:
  Microsoft.AspNetCore.Mvc.VirtualFileResult
• 데이터 원본:
  웹 루트(wwwroot)를 기준으로 한 가상 경로
• 메모리 사용:
  낮음. 파일의 내용이 메모리에 한 번에 로드되지 않고, 스트림 방식으로 전송되므로 대용량 파일에도 적합합니다.
• 성능:
  효율적입니다.

주요 사용처:

• wwwroot 내의 정적 파일: 애플리케이션의 wwwroot 폴더 내에 있는 CSS, JavaScript, 이미지 등 정적 파일을 컨트롤러 액션 메서드에서 직접 제공해야 할 때 (예: 특정 인증/권한이 필요한 정적 파일).
• StaticFileOptions로 구성된 가상 경로: UseStaticFiles 미들웨어 구성 시 RequestPath를 지정하여 만든 가상 경로에 있는 파일.

생성자 매개변수:

• string virtualPath: 웹 루트를 기준으로 한 가상 경로 (예: ~/images/logo.png, /css/site.css).
• string contentType: 파일의 MIME 타입.
• string? fileDownloadName (선택 사항): 다운로드 시 파일 이름.

예시:

using Microsoft.AspNetCore.Mvc;

public class StaticAssetController : Controller
{
    // GET: /StaticAsset/GetAppStyle
    public IActionResult GetAppStyle()
    {
        // wwwroot/css/app.css 파일을 제공합니다.
        return File("~/css/app.css", "text/css");
    }

    // GET: /StaticAsset/DownloadSampleDocument
    public IActionResult DownloadSampleDocument()
    {
        // wwwroot/downloads/sample.pdf 파일을 다운로드합니다.
        return File("/downloads/sample.pdf", "application/pdf", "SampleDocument.pdf");
    }
}

PhysicalFileResult

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.mvc.physicalfileresult?view=aspnetcore-8.0

서버의 실제 파일 시스템 경로(Physical Path)를 사용하여 파일을 제공할 때 사용됩니다.

웹 애플리케이션의 루트 디렉토리를 벗어나 서버의 임의의 경로에 있는 파일을 제공해야 할 때 가장 유용합니다.

• 정의:
  Microsoft.AspNetCore.Mvc.PhysicalFileResult
• 데이터 원본:
  서버의 실제 파일 시스템 경로 (절대 경로 또는 콘텐츠 루트 기준 상대 경로)
• 메모리 사용:
  낮음. VirtualFileResult와 마찬가지로 스트림 방식으로 전송되어 메모리 효율적입니다.
• 성능:
  효율적입니다.

주요 사용처:

• 웹 루트 외부 파일: 사용자가 업로드한 파일, 백업 파일, 또는 보안상의 이유로 wwwroot에 직접 노출되지 않는 폴더에 저장된 파일.
• 서버의 특정 위치에 있는 파일: 애플리케이션과 독립적으로 관리되는 파일 저장소의 파일.

생성자 매개변수:

• string physicalPath: 파일의 절대 경로 (예: “C:\Uploads\document.pdf”) 또는 애플리케이션의 콘텐츠 루트에 대한 상대 경로.
• string contentType: 파일의 MIME 타입.
• string? fileDownloadName (선택 사항): 다운로드 시 파일 이름.

주의사항: 사용자가 physicalPath를 직접 제어할 수 있는 경우 보안 취약점이 될 수 있습니다. 경로 유효성 검사 및 인가 처리가 필수적입니다.

예시:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Hosting; // IWebHostEnvironment를 사용하기 위해 필요

public class UploadedFileController : Controller
{
    private readonly IWebHostEnvironment _env;

    public UploadedFileController(IWebHostEnvironment env)
    {
        _env = env;
    }

    // GET: /UploadedFile/Download/{fileName}
    public IActionResult Download(string fileName)
    {
        // 업로드된 파일이 ContentRootPath/UserUploads 폴더에 저장되어 있다고 가정합니다.
        var filePath = Path.Combine(_env.ContentRootPath, "UserUploads", fileName);

        if (!System.IO.File.Exists(filePath))
        {
            return NotFound();
        }

        // 파일 확장자를 기반으로 MIME 타입 결정 (실제로는 더 견고한 로직 필요)
        string contentType;
        var ext = Path.GetExtension(fileName).ToLowerInvariant();
        if (ext == ".pdf") contentType = "application/pdf";
        else if (ext == ".jpg" || ext == ".jpeg") contentType = "image/jpeg";
        else contentType = "application/octet-stream"; // 기본값: 알 수 없는 파일

        return PhysicalFile(filePath, contentType, fileName);
    }
}

FileStreamResult (스트림 기반 파일 Serving)

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.mvc.filestreamresult?view=aspnetcore-8.0

FileStreamResult는 Stream 객체로부터 직접 파일을 제공할 때 사용됩니다.

이는 PhysicalFileResult나 VirtualFileResult와 마찬가지로 메모리 효율적이며,

파일이 이미 스트림 형태로 열려 있거나 외부 소스에서 스트림으로 직접 데이터를 읽어올 때 유용합니다.

• 정의:
  Microsoft.AspNetCore.Mvc.FileStreamResult
• 데이터 원본:
  System.IO.Stream
• 메모리 사용:
  낮음. 파일 내용을 한 번에 메모리에 로드하지 않고 스트림에서 직접 읽어 전송합니다.
• 성능:
  효율적입니다.

주요 사용처:

• 네트워크 스트림에서 직접 읽어온 데이터.
• 압축 파일 내부의 특정 파일을 스트림으로 추출하여 제공할 때.
• 데이터베이스에서 BLOB 데이터를 Stream으로 직접 가져올 때.
• 외부 API에서 스트림 형태로 응답을 받을 때.

생성자 매개변수:

• Stream fileStream: 전송할 파일의 내용을 담고 있는 스트림.
• string contentType: 파일의 MIME 타입.
• string? fileDownloadName (선택 사항): 다운로드 시 파일 이름.

예시:

using Microsoft.AspNetCore.Mvc;
using System.IO;

public class StreamFileController : Controller
{
    // GET: /StreamFile/GetLogFile
    public IActionResult GetLogFile()
    {
        var logFilePath = Path.Combine(AppContext.BaseDirectory, "Logs", "application.log");
        if (!System.IO.File.Exists(logFilePath))
        {
            return NotFound();
        }
        // FileStream을 직접 열어 FileStreamResult로 반환
        var stream = new FileStream(logFilePath, FileMode.Open, FileAccess.Read);
        return File(stream, "text/plain", "application.log");
    }
}

2⃣ 파일 처리 관련 기타 핵심 인터페이스 및 개념

FileResult 유형 외에도 ASP.NET Core에서 파일을 효율적이고 안전하게 다루기 위해 알아야 할 중요한 인터페이스와 개념들이 있습니다.

IFormFile 및 IFormFileCollection (파일 업로드)

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.http.iformfile?view=aspnetcore-8.0

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.http.iformfilecollection?view=aspnetcore-8.0

클라이언트(브라우저)에서 서버로 파일을 전송할 때 사용하는 인터페이스입니다.

• IFormFile: 단일 업로드 파일을 나타냅니다.
  • 정의: Microsoft.AspNetCore.Http.IFormFile
  • 주요 속성: FileName, ContentType, Length.
  • 주요 메서드: CopyToAsync(Stream), OpenReadStream().
• IFormFileCollection: 여러 개의 업로드 파일을 나타내는 IFormFile 객체의 컬렉션입니다.
  • 정의: Microsoft.AspNetCore.Http.IFormFileCollection
  • 사용 예시: <input type="file" multiple> 폼 요소로 여러 파일을 받을 때 컨트롤러 액션의 매개변수로 사용됩니다.

IWebHostEnvironment 및 IHostEnvironment (환경 정보 및 경로)

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.hosting.iwebhostenvironment?view=aspnetcore-8.0

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.components.routing.ihostenvironmentnavigationmanager?view=aspnetcore-8.0

애플리케이션의 호스팅 환경에 대한 정보를 제공하여, 파일 경로를 구성하고 접근할 때 매우 유용합니다. 이들은 DI 컨테이너에 등록되어 있어 생성자를 통해 쉽게 주입받을 수 있습니다.

• IWebHostEnvironment: 웹 호스팅 환경에 특화된 정보를 제공합니다.
  • 정의: Microsoft.AspNetCore.Hosting.IWebHostEnvironment
  • 주요 속성:
    • WebRootPath: 웹 루트(wwwroot) 폴더의 물리적 경로. 정적 파일이 위치하는 곳입니다.
    • WebRootFileProvider: WebRootPath에 대한 IFileProvider 인스턴스.
  • 주요 사용처: 정적 파일 저장 경로, 웹에 노출될 리소스 경로 구성.
• IHostEnvironment: 일반적인 호스팅 환경 정보를 제공합니다. IWebHostEnvironment는 IHostEnvironment를 상속합니다.
  • 정의: Microsoft.Extensions.Hosting.IHostEnvironment
  • 주요 속성:
    • ContentRootPath: 애플리케이션의 콘텐츠 루트 폴더(프로젝트 파일이 있는 기본 디렉토리)의 물리적 경로.
    • ContentRootFileProvider: ContentRootPath에 대한 IFileProvider 인스턴스.
    • EnvironmentName: 현재 실행 중인 환경의 이름 (예: “Development”, “Production”, “Staging”).
  • 주요 사용처: 로그 파일, 설정 파일 등 애플리케이션이 사용하는 비-웹 관련 파일 경로 구성.

IFileProvider (추상화된 파일 시스템 접근)

파일 시스템 접근을 추상화하는 핵심 인터페이스입니다.

물리적인 디스크, 메모리, 압축 파일 등 다양한 소스에서 파일을 일관된 방식으로 다룰 수 있게 해줍니다.

• 정의: Microsoft.Extensions.FileProviders.IFileProvider
• 주요 역할: 파일 존재 여부 확인, 디렉토리 내용 열거, 파일 내용 스트림 생성 등 파일 시스템 작업을 수행합니다. UseStaticFiles 미들웨어, Razor Pages 등에서 내부적으로 사용됩니다.
• 주요 메서드:
  • GetFileInfo(string subpath): 지정된 하위 경로의 파일 또는 디렉토리에 대한 IFileInfo 객체를 반환합니다.
  • GetDirectoryContents(string subpath): 지정된 하위 경로의 디렉토리 콘텐츠(IDirectoryContents)를 반환합니다.
  • Watch(string filter): 지정된 필터와 일치하는 파일 또는 디렉토리의 변경 사항을 감시합니다 (예: 파일 변경 시 캐시 무효화).
• 주요 구현체:
  • PhysicalFileProvider: 실제 파일 시스템 경로에서 파일을 제공합니다.
  • CompositeFileProvider: 여러 IFileProvider를 결합하여 여러 위치에서 파일을 찾을 수 있게 합니다.

IFileInfo 및 IDirectoryContents (파일/디렉토리 메타데이터)

https://learn.microsoft.com/ko-kr/dotnet/api/microsoft.aspnetcore.mvc.razor.runtimecompilation.fileproviderrazorprojectitem.fileinfo?view=aspnetcore-8.0#microsoft-aspnetcore-mvc-razor-runtimecompilation-fileproviderrazorprojectitem-fileinfo

IFileProvider와 함께 사용되어 파일 시스템 항목의 상세 정보를 제공합니다.

• IFileInfo: 단일 파일 또는 디렉토리에 대한 메타데이터 (이름, 크기, 수정 시간, 존재 여부 등)를 제공합니다. IFileProvider.GetFileInfo()가 반환합니다.
• IDirectoryContents: 디렉토리 내의 파일 및 서브디렉토리 목록을 나타냅니다. IFileProvider.GetDirectoryContents()가 반환하며, IEnumerable<IFileInfo>를 구현합니다.

3⃣ 고급 파일 처리 기능

파일 업로드 보안 강화

파일 시그니처 검증

파일 확장자만으로는 안전하지 않으며, 파일 시그니처(매직 바이트) 검증이 필요합니다.

public static class FileSignatureValidator
{
    private static readonly Dictionary<string, byte[][]> FileSignatures = new()
    {
        { ".jpg", new[] { new byte[] { 0xFF, 0xD8, 0xFF } } },
        { ".jpeg", new[] { new byte[] { 0xFF, 0xD8, 0xFF } } },
        { ".png", new[] { new byte[] { 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A } } },
        { ".pdf", new[] { new byte[] { 0x25, 0x50, 0x44, 0x46 } } },
        { ".gif", new[] { new byte[] { 0x47, 0x49, 0x46, 0x38 } } }
    };

    public static bool IsValidFileSignature(IFormFile file, string[] allowedExtensions)
    {
        if (file.Length == 0) return false;

        var ext = Path.GetExtension(file.FileName).ToLowerInvariant();
        if (!allowedExtensions.Contains(ext) || !FileSignatures.ContainsKey(ext))
            return false;

        using var reader = new BinaryReader(file.OpenReadStream());
        var signatures = FileSignatures[ext];
        var headerBytes = reader.ReadBytes(signatures.Max(s => s.Length));

        return signatures.Any(signature => 
            headerBytes.Take(signature.Length).SequenceEqual(signature));
    }
}

커스텀 파일 검증 어트리뷰트

public class AllowedExtensionsAttribute : ValidationAttribute
{
    private readonly string[] _extensions;

    public AllowedExtensionsAttribute(params string[] extensions)
    {
        _extensions = extensions;
    }

    protected override ValidationResult IsValid(object value, ValidationContext validationContext)
    {
        if (value is IFormFile file)
        {
            if (!FileSignatureValidator.IsValidFileSignature(file, _extensions))
            {
                return new ValidationResult("허용되지 않는 파일 형식입니다.");
            }
        }
        return ValidationResult.Success;
    }
}

public class MaxFileSizeAttribute : ValidationAttribute
{
    private readonly int _maxFileSize;

    public MaxFileSizeAttribute(int maxFileSize)
    {
        _maxFileSize = maxFileSize;
    }

    protected override ValidationResult IsValid(object value, ValidationContext validationContext)
    {
        if (value is IFormFile file && file.Length > _maxFileSize)
        {
            return new ValidationResult($"파일 크기는 {_maxFileSize / (1024 * 1024)}MB를 초과할 수 없습니다.");
        }
        return ValidationResult.Success;
    }
}

// 사용 예시
public class FileUploadModel
{
    [AllowedExtensions(".jpg", ".jpeg", ".png", ".pdf")]
    [MaxFileSize(5 * 1024 * 1024)] // 5MB
    public IFormFile UploadedFile { get; set; }
}

대용량 파일 처리 최적화

스트리밍 업로드

[HttpPost]
[DisableFormValueModelBinding]
public async Task<IActionResult> UploadLargeFile()
{
    if (!IsMultipartContentType(Request.ContentType))
        return BadRequest("지원하지 않는 미디어 타입입니다.");

    var boundary = GetBoundary(Request.ContentType);
    var reader = new MultipartReader(boundary, HttpContext.Request.Body);
    var section = await reader.ReadNextSectionAsync();

    while (section != null)
    {
        if (ContentDispositionHeaderValue.TryParse(section.ContentDisposition, 
            out var contentDisposition))
        {
            if (HasFileContentDisposition(contentDisposition))
            {
                var fileName = contentDisposition.FileName.Value;
                var filePath = Path.Combine("uploads", fileName);
                
                using var targetStream = new FileStream(filePath, FileMode.Create);
                await section.Body.CopyToAsync(targetStream);
            }
        }
        section = await reader.ReadNextSectionAsync();
    }

    return Ok("파일 업로드 완료");
}

private static bool IsMultipartContentType(string contentType)
{
    return !string.IsNullOrEmpty(contentType) 
           && contentType.IndexOf("multipart/", StringComparison.OrdinalIgnoreCase) >= 0;
}

private static string GetBoundary(string contentType)
{
    var elements = contentType.Split(' ');
    var element = elements.Where(entry => entry.StartsWith("boundary=")).First();
    var boundary = element.Substring("boundary=".Length);
    return HeaderUtilities.RemoveQuotes(boundary).Value;
}

private static bool HasFileContentDisposition(ContentDispositionHeaderValue contentDisposition)
{
    return contentDisposition != null
           && contentDisposition.DispositionType.Equals("form-data")
           && (!StringSegment.IsNullOrEmpty(contentDisposition.FileName)
               || !StringSegment.IsNullOrEmpty(contentDisposition.FileNameStar));
}

Range Request 지원 (부분 콘텐츠 전송)

public IActionResult DownloadWithRangeSupport(string fileName)
{
    var filePath = Path.Combine("uploads", fileName);
    if (!System.IO.File.Exists(filePath))
        return NotFound();

    var fileInfo = new FileInfo(filePath);
    var rangeHeader = Request.Headers["Range"].ToString();

    if (!string.IsNullOrEmpty(rangeHeader))
    {
        // Range 요청 처리
        var range = ParseRangeHeader(rangeHeader, fileInfo.Length);
        if (range.HasValue)
        {
            var (start, end) = range.Value;
            var contentLength = end - start + 1;

            Response.StatusCode = 206; // Partial Content
            Response.Headers.Add("Content-Range", $"bytes {start}-{end}/{fileInfo.Length}");
            Response.Headers.Add("Content-Length", contentLength.ToString());

            var stream = new FileStream(filePath, FileMode.Open, FileAccess.Read);
            stream.Seek(start, SeekOrigin.Begin);
            
            return File(stream, "application/octet-stream", fileName, enableRangeProcessing: true);
        }
    }

    return PhysicalFile(filePath, "application/octet-stream", fileName);
}

private (long start, long end)? ParseRangeHeader(string rangeHeader, long fileLength)
{
    if (!rangeHeader.StartsWith("bytes="))
        return null;

    var range = rangeHeader.Substring(6);
    var parts = range.Split('-');
    
    if (parts.Length != 2)
        return null;

    long start = 0, end = fileLength - 1;

    if (!string.IsNullOrEmpty(parts[0]))
        start = long.Parse(parts[0]);

    if (!string.IsNullOrEmpty(parts[1]))
        end = long.Parse(parts[1]);

    if (start > end || start >= fileLength)
        return null;

    return (start, Math.Min(end, fileLength - 1));
}

임시 파일 관리 및 정리

임시 파일 자동 정리 서비스

public class TempFileCleanupService : BackgroundService
{
    private readonly ILogger<TempFileCleanupService> _logger;
    private readonly string _tempDirectory;

    public TempFileCleanupService(ILogger<TempFileCleanupService> logger, IWebHostEnvironment env)
    {
        _logger = logger;
        _tempDirectory = Path.Combine(env.ContentRootPath, "temp");
        
        // 임시 디렉토리가 존재하지 않으면 생성
        if (!Directory.Exists(_tempDirectory))
        {
            Directory.CreateDirectory(_tempDirectory);
        }
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                CleanupOldTempFiles();
                await Task.Delay(TimeSpan.FromHours(1), stoppingToken);
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "임시 파일 삭제 실패: {FilePath}", file);
            }
        }
    }
}

// Program.cs에서 서비스 등록
builder.Services.AddHostedService<TempFileCleanupService>();

파일 압축 및 최적화

이미지 자동 리사이징

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Processing;
using SixLabors.ImageSharp.Formats.Jpeg;

public class ImageProcessingResult : FileStreamResult
{
    public ImageProcessingResult(Stream imageStream, string contentType, int maxWidth = 800, int maxHeight = 600)
        : base(ProcessImage(imageStream, maxWidth, maxHeight), contentType)
    {
    }

    private static Stream ProcessImage(Stream originalStream, int maxWidth, int maxHeight)
    {
        using var image = Image.Load(originalStream);
        
        if (image.Width > maxWidth || image.Height > maxHeight)
        {
            image.Mutate(x => x.Resize(new ResizeOptions
            {
                Size = new Size(maxWidth, maxHeight),
                Mode = ResizeMode.Max
            }));
        }

        var outputStream = new MemoryStream();
        image.SaveAsJpeg(outputStream, new JpegEncoder { Quality = 85 });
        outputStream.Position = 0;
        
        return outputStream;
    }
}

// 사용 예시
public IActionResult GetOptimizedImage(string fileName)
{
    var filePath = Path.Combine("images", fileName);
    if (!System.IO.File.Exists(filePath))
        return NotFound();
        
    var stream = new FileStream(filePath, FileMode.Open, FileAccess.Read);
    
    return new ImageProcessingResult(stream, "image/jpeg");
}

파일 메타데이터 및 추적

파일 메타데이터 모델

public class FileMetadata
{
    public string Id { get; set; } = Guid.NewGuid().ToString();
    public string OriginalName { get; set; }
    public string StoredName { get; set; }
    public string ContentType { get; set; }
    public long Size { get; set; }
    public string Hash { get; set; } // SHA256 해시
    public DateTime UploadedAt { get; set; } = DateTime.UtcNow;
    public string UploadedBy { get; set; }
    public int DownloadCount { get; set; }
    public DateTime? LastAccessedAt { get; set; }
}

public class SecureFileService
{
    private readonly ILogger<SecureFileService> _logger;
    private readonly string _uploadDirectory;
    private readonly Dictionary<string, FileMetadata> _fileMetadata = new();

    public SecureFileService(ILogger<SecureFileService> logger, IWebHostEnvironment env)
    {
        _logger = logger;
        _uploadDirectory = Path.Combine(env.ContentRootPath, "SecureUploads");
        
        if (!Directory.Exists(_uploadDirectory))
        {
            Directory.CreateDirectory(_uploadDirectory);
        }
    }

    public async Task<FileMetadata> SaveFileAsync(IFormFile file, string userId)
    {
        // 파일 시그니처 검증
        var allowedExtensions = new[] { ".jpg", ".jpeg", ".png", ".pdf", ".docx", ".xlsx" };
        if (!FileSignatureValidator.IsValidFileSignature(file, allowedExtensions))
        {
            throw new InvalidOperationException("허용되지 않는 파일 형식입니다.");
        }

        var metadata = new FileMetadata
        {
            OriginalName = file.FileName,
            StoredName = $"{Guid.NewGuid()}{Path.GetExtension(file.FileName)}",
            ContentType = file.ContentType,
            Size = file.Length,
            UploadedBy = userId
        };

        var filePath = Path.Combine(_uploadDirectory, metadata.StoredName);
        
        // 파일 저장
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await file.CopyToAsync(stream);
        }

        // 파일 해시 계산
        metadata.Hash = await ComputeFileHashAsync(filePath);
        
        // 메타데이터 저장
        _fileMetadata[metadata.Id] = metadata;
        
        _logger.LogInformation("파일 저장 완료: {FileName} ({FileId})", 
            metadata.OriginalName, metadata.Id);
        
        return metadata;
    }

    public async Task<(Stream stream, FileMetadata metadata)> GetFileAsync(string fileId)
    {
        if (!_fileMetadata.TryGetValue(fileId, out var metadata))
        {
            throw new FileNotFoundException("파일을 찾을 수 없습니다.");
        }

        var filePath = Path.Combine(_uploadDirectory, metadata.StoredName);
        if (!System.IO.File.Exists(filePath))
        {
            throw new FileNotFoundException("물리적 파일이 존재하지 않습니다.");
        }

        // 다운로드 통계 업데이트
        metadata.DownloadCount++;
        metadata.LastAccessedAt = DateTime.UtcNow;

        var stream = new FileStream(filePath, FileMode.Open, FileAccess.Read);
        return (stream, metadata);
    }

    private async Task<string> ComputeFileHashAsync(string filePath)
    {
        using var sha256 = SHA256.Create();
        using var stream = new FileStream(filePath, FileMode.Open, FileAccess.Read);
        var hash = await sha256.ComputeHashAsync(stream);
        return Convert.ToBase64String(hash);
    }

    public bool DeleteFile(string fileId, string userId)
    {
        if (!_fileMetadata.TryGetValue(fileId, out var metadata))
        {
            return false;
        }

        // 권한 확인
        if (metadata.UploadedBy != userId)
        {
            throw new UnauthorizedAccessException("파일 삭제 권한이 없습니다.");
        }

        var filePath = Path.Combine(_uploadDirectory, metadata.StoredName);
        
        try
        {
            if (System.IO.File.Exists(filePath))
            {
                System.IO.File.Delete(filePath);
            }
            
            _fileMetadata.Remove(fileId);
            
            _logger.LogInformation("파일 삭제 완료: {FileName} ({FileId})", 
                metadata.OriginalName, fileId);
            
            return true;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "파일 삭제 실패: {FileName} ({FileId})", 
                metadata.OriginalName, fileId);
            return false;
        }
    }
}

에러 처리 및 로깅

포괄적인 파일 에러 처리

public class FileController : Controller
{
    private readonly ILogger<FileController> _logger;
    private readonly SecureFileService _fileService;

    public FileController(ILogger<FileController> logger, SecureFileService fileService)
    {
        _logger = logger;
        _fileService = fileService;
    }

    [HttpPost]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        try
        {
            if (file == null || file.Length == 0)
                return BadRequest(new { error = "파일이 선택되지 않았습니다." });

            if (file.Length > 10 * 1024 * 1024) // 10MB
                return BadRequest(new { error = "파일 크기가 10MB를 초과합니다." });

            // 파일명 검증 (경로 조작 공격 방지)
            var fileName = Path.GetFileName(file.FileName);
            if (string.IsNullOrEmpty(fileName) || fileName.Contains(".."))
                return BadRequest(new { error = "유효하지 않은 파일명입니다." });

            var result = await _fileService.SaveFileAsync(file, User.Identity.Name);
            
            _logger.LogInformation("파일 업로드 성공: {FileName}, 사용자: {User}, 파일ID: {FileId}", 
                file.FileName, User.Identity.Name, result.Id);

            return Ok(new { 
                fileId = result.Id, 
                fileName = result.OriginalName,
                size = result.Size,
                message = "파일 업로드 완료" 
            });
        }
        catch (InvalidOperationException ex)
        {
            _logger.LogWarning("파일 업로드 유효성 검사 실패: {FileName}, 오류: {Error}", 
                file?.FileName, ex.Message);
            return BadRequest(new { error = ex.Message });
        }
        catch (IOException ex)
        {
            _logger.LogError(ex, "파일 I/O 오류: {FileName}", file?.FileName);
            return StatusCode(500, new { error = "파일 저장 중 오류가 발생했습니다." });
        }
        catch (UnauthorizedAccessException ex)
        {
            _logger.LogError(ex, "파일 접근 권한 오류: {FileName}", file?.FileName);
            return StatusCode(500, new { error = "파일 접근 권한이 없습니다." });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "예상치 못한 오류: {FileName}", file?.FileName);
            return StatusCode(500, new { error = "파일 처리 중 오류가 발생했습니다." });
        }
    }

    [HttpGet("{fileId}")]
    public async Task<IActionResult> Download(string fileId)
    {
        try
        {
            var (stream, metadata) = await _fileService.GetFileAsync(fileId);
            
            _logger.LogInformation("파일 다운로드: {FileName} ({FileId}), 사용자: {User}", 
                metadata.OriginalName, fileId, User.Identity.Name);

            return File(stream, metadata.ContentType, metadata.OriginalName);
        }
        catch (FileNotFoundException ex)
        {
            _logger.LogWarning("파일 다운로드 실패 - 파일 없음: {FileId}, 사용자: {User}", 
                fileId, User.Identity.Name);
            return NotFound(new { error = "파일을 찾을 수 없습니다." });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "파일 다운로드 오류: {FileId}", fileId);
            return StatusCode(500, new { error = "파일 다운로드 중 오류가 발생했습니다." });
        }
    }

    [HttpDelete("{fileId}")]
    public IActionResult Delete(string fileId)
    {
        try
        {
            var success = _fileService.DeleteFile(fileId, User.Identity.Name);
            
            if (!success)
                return NotFound(new { error = "파일을 찾을 수 없습니다." });

            return Ok(new { message = "파일이 삭제되었습니다." });
        }
        catch (UnauthorizedAccessException ex)
        {
            _logger.LogWarning("파일 삭제 권한 없음: {FileId}, 사용자: {User}", 
                fileId, User.Identity.Name);
            return Forbid("파일 삭제 권한이 없습니다.");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "파일 삭제 오류: {FileId}", fileId);
            return StatusCode(500, new { error = "파일 삭제 중 오류가 발생했습니다." });
        }
    }
}

4⃣ 파일 처리 시 보안 및 성능 고려사항

보안 고려사항

1. 경로 유효성 검사:
   PhysicalFileResult나 파일 업로드 시 사용자가 제공한 파일 이름/경로에 대해 경로 조작(Path Traversal) 공격을 방지하기 위해 철저한 유효성 검사를 수행해야 합니다.
   Path.GetFullPath(), Path.GetFileName() 등을 사용하여 안전한 경로를 구성하고, 허용된 디렉토리 내에만 파일을 저장하도록 제한해야 합니다.
2. MIME 타입:
   올바른 Content-Type을 지정하여 브라우저가 파일을 올바르게 해석하고, 잠재적인 스크립트 실행 공격을 방지합니다.
   FileExtensionContentTypeProvider와 같은 클래스를 사용하여 MIME 타입을 자동으로 추론하는 것이 좋습니다.
3. 파일 시그니처 검증:
   파일 확장자만으로는 안전하지 않으므로, 파일의 매직 바이트(시그니처)를 검증하여 실제 파일 형식을 확인해야 합니다.
4. 파일 크기 제한:
   서비스 거부 공격을 방지하기 위해 업로드 파일 크기를 제한해야 합니다.
5. 바이러스 스캔:
   중요한 시스템에서는 업로드된 파일에 대한 바이러스 검사를 수행해야 합니다.

성능 고려사항

1. 대용량 파일:
   큰 파일은 byte[]로 메모리에 로드하는 FileContentResult 대신, 스트림 기반의 VirtualFileResult, PhysicalFileResult, FileStreamResult를 사용하여 메모리 사용량을 최소화해야 합니다.
2. 캐싱:
   UseStaticFiles 미들웨어의 StaticFileOptions.OnPrepareResponse를 사용하여 Cache-Control 헤더를 설정하거나, ResponseCaching 미들웨어를 사용하여 캐싱 전략을 최적화할 수 있습니다.
3. 응답 압축:
   UseResponseCompression 미들웨어를 사용하여 정적 파일 및 동적 응답을 gzip, brotli 등으로 압축하여 네트워크 대역폭 사용을 줄이고 로딩 속도를 향상시킬 수 있습니다.
4. 스트리밍 처리:
   대용량 파일 업로드/다운로드 시 전체 파일을 메모리에 로드하지 않고 스트림으로 처리하여 메모리 효율성을 높입니다.
5. 비동기 처리:
   파일 I/O 작업은 항상 비동기 메서드(CopyToAsync, ReadAsync 등)를 사용하여 스레드 풀을 효율적으로 활용합니다.

5⃣ 프로덕션 환경 설정

Program.cs 설정 예시

var builder = WebApplication.CreateBuilder(args);

// 서비스 등록
builder.Services.AddControllers();
builder.Services.AddScoped<SecureFileService>();
builder.Services.AddHostedService<TempFileCleanupService>();

// 파일 업로드 설정
builder.Services.Configure<FormOptions>(options =>
{
    options.MultipartBodyLengthLimit = 100 * 1024 * 1024; // 100MB
    options.ValueLengthLimit = int.MaxValue;
    options.ValueCountLimit = int.MaxValue;
    options.KeyLengthLimit = int.MaxValue;
});

// 응답 압축 설정
builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
});

var app = builder.Build();

// 미들웨어 파이프라인
app.UseResponseCompression();
app.UseStaticFiles(new StaticFileOptions
{
    OnPrepareResponse = ctx =>
    {
        // 정적 파일 캐싱 설정
        ctx.Context.Response.Headers.Append("Cache-Control", "public,max-age=31536000");
    }
});

app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

로깅 설정 (appsettings.json)

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "FileController": "Information",
      "SecureFileService": "Information",
      "TempFileCleanupService": "Information"
    }
  }
}

6⃣ 결론

ASP.NET Core의 이러한 다양한 파일 처리 도구와 개념을 이해하고 적절히 활용하는 것은 견고하고 효율적인 웹 애플리케이션을 구축하는 데 필수적입니다.

특히 보안, 성능, 사용자 경험을 모두 고려한 파일 처리 시스템을 구축하기 위해서는:

1. 적절한 FileResult 선택: 파일의 특성과 사용 목적에 따라 최적의 FileResult 유형을 선택
2. 강력한 보안 검증: 파일 시그니처 검증, 경로 조작 방지, 크기 제한 등 다층적 보안 적용
3. 성능 최적화: 스트리밍 처리, 캐싱, 압축 등을 통한 성능 향상
4. 포괄적인 에러 처리: 예상 가능한 모든 오류 상황에 대한 적절한 처리와 로깅
5. 사용자 경험 고려: Range Request 지원, 진행률 표시, 적절한 피드백 제공

이러한 원칙들을 따라 구현하면 안전하고 효율적이며 사용자 친화적인 파일 처리 시스템을 구축할 수 있습니다.

The post ASP.NET Core 파일 처리: FileResult 및 인터페이스 appeared first on 어제와 내일의 나 그 사이의 이야기.

Swagger(스웨거)란 무엇인가?

Swagger는 현재 OpenAPI Specification (OAS)라는 이름으로 표준화된 RESTful API 명세 및 문서화 도구입니다.

2015년 SmartBear Software에서 OpenAPI Initiative에 기증한 후, 현재는 Linux Foundation 산하에서 관리되고 있습니다.

핵심 개념

• API 명세의 표준화: REST API의 엔드포인트, 파라미터, 응답 구조를 JSON/YAML 형식으로 정의
• Code-First 접근: 소스코드로부터 API 문서를 자동 생성하여 문서와 구현 간 불일치 방지
• Interactive Documentation: 브라우저에서 직접 API를 테스트할 수 있는 UI 제공

Swagger가 필요한 이유

1. 개발 생산성 향상

• 자동 문서화: 수동으로 API 문서를 작성하고 유지보수하는 비용 절약
• 실시간 동기화: 코드 변경 시 문서가 자동으로 업데이트
• 타입 안전성: .NET의 강타입 시스템을 활용한 정확한 스키마 생성

2. 팀 협업 효율성

• 프론트엔드-백엔드 협업: 명확한 API 계약 정의를 통한 병렬 개발 지원
• API 계약 테스트: 구현 전 API 설계 검증 가능
• 버전 관리: API 변경사항 추적 및 하위 호환성 관리

3. 운영 및 테스트

• 통합 테스트: CI/CD 파이프라인에서 자동화된 API 테스트
• 모니터링: API 사용 패턴 분석 및 성능 모니터링 기반 제공

Swashbuckle.AspNetCore 아키텍처

Swashbuckle.AspNetCore는 .NET에서 Swagger/OpenAPI를 구현하는 가장 널리 사용되는 라이브러리입니다.

.NET 6+ 프로젝트에서 Swagger 구성

1. 패키지 설치

# Package Manager Console
Install-Package Swashbuckle.AspNetCore

# .NET CLI
dotnet add package Swashbuckle.AspNetCore

2. 기본 구성 (Program.cs)

var builder = WebApplication.CreateBuilder(args);

// 컨트롤러 서비스 등록
builder.Services.AddControllers();

// Swagger 서비스 등록
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "My API",
        Description = "ASP.NET Core Web API for demonstration",
        Contact = new OpenApiContact
        {
            Name = "Developer Name",
            Email = "developer@example.com"
        }
    });
});

var app = builder.Build();

// 개발 환경에서만 Swagger 활성화
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        options.RoutePrefix = string.Empty; // 루트 경로에서 Swagger UI 제공
    });
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

SwaggerGen의 동작 원리

SwaggerGen은 다음과 같은 과정을 통해 OpenAPI 문서를 생성합니다:

1. 어셈블리 스캔: 등록된 컨트롤러와 액션 메서드 탐색
2. 메타데이터 추출: 라우트, HTTP 메서드, 파라미터, 반환 타입 분석
3. 스키마 생성: .NET 타입을 JSON Schema로 변환
4. 문서 조합: OpenAPI 3.0 사양에 맞는 JSON 문서 생성

생성되는 OpenAPI 문서 예시

{
  "openapi": "3.0.1",
  "info": {
    "title": "My API",
    "version": "v1"
  },
  "paths": {
    "/api/products": {
      "get": {
        "tags": ["Products"],
        "summary": "제품 목록 조회",
        "responses": {
          "200": {
            "description": "성공",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Product"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "format": "int32" },
          "name": { "type": "string", "nullable": true }
        }
      }
    }
  }
}

Swagger UI 고급 활용

Swagger UI는 생성된 OpenAPI 문서를 기반으로 다음 기능을 제공합니다:

주요 기능

• HTTP 메서드별 분류: GET, POST, PUT, DELETE 등 시각적 구분
• 스키마 검증: 요청/응답 데이터 구조 실시간 검증
• Try it Out: 브라우저에서 직접 API 호출 및 결과 확인
• 모델 정의: 복잡한 객체 구조의 시각적 표현
• 인증 통합: 다양한 인증 방식 지원 (Bearer, API Key 등)

커스터마이징 옵션

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    options.DocumentTitle = "My API Documentation";
    options.DefaultModelsExpandDepth(2);
    options.DefaultModelRendering(ModelRendering.Model);
    options.DisplayRequestDuration();
    options.EnableDeepLinking();
    options.EnableFilter();
    options.ShowExtensions();
});

실무 필수 확장 기능

1. XML 주석 통합

프로젝트 파일 설정:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Program.cs 구성:

builder.Services.AddSwaggerGen(options =>
{
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
    
    // 상속된 XML 주석 포함
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "MyModels.xml"));
});

컨트롤러 예시:

/// <summary>
/// 제품 관리 API
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    /// <summary>
    /// 제품 목록을 조회합니다.
    /// </summary>
    /// <param name="pageSize">페이지당 항목 수 (기본값: 10)</param>
    /// <returns>제품 목록</returns>
    /// <response code="200">성공적으로 조회됨</response>
    /// <response code="400">잘못된 요청 파라미터</response>
    [HttpGet]
    [ProducesResponseType(typeof(IEnumerable<Product>), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<IEnumerable<Product>>> GetProducts(
        [FromQuery] int pageSize = 10)
    {
        // 구현 로직
    }
}

2. JWT Bearer 인증 통합

builder.Services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\""
    });

    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty<string>()
        }
    });
});

3. API 버전 관리

패키지 설치:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

구성:

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Version"),
        new MediaTypeApiVersionReader("ver"));
});

builder.Services.AddVersionedApiExplorer(setup =>
{
    setup.GroupNameFormat = "'v'VVV";
    setup.SubstituteApiVersionInUrl = true;
});

builder.Services.AddSwaggerGen();
builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();

4. 사용자 정의 스키마 필터

public class EnumSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type.IsEnum)
        {
            schema.Enum.Clear();
            Enum.GetNames(context.Type)
                .ToList()
                .ForEach(name => schema.Enum.Add(new OpenApiString(name)));
        }
    }
}

// 등록
builder.Services.AddSwaggerGen(options =>
{
    options.SchemaFilter<EnumSchemaFilter>();
});

성능 최적화 및 모범 사례

1. 프로덕션 환경 고려사항

// 조건부 Swagger 활성화
if (app.Environment.IsDevelopment() || app.Environment.IsStaging())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

// 또는 구성 기반 활성화
if (builder.Configuration.GetValue<bool>("EnableSwagger"))
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

2. 대용량 API 문서 최적화

builder.Services.AddSwaggerGen(options =>
{
    // 불필요한 스키마 제외
    options.SchemaFilter<ExcludeInternalTypesFilter>();
    
    // 문서 압축
    options.EnableAnnotations();
    
    // 메모리 사용량 최적화
    options.UseAllOfToExtendReferenceSchemas();
    options.UseOneOfForPolymorphism();
});

3. 보안 강화

app.UseSwagger(options =>
{
    // JSON 문서 접근 제한
    options.PreSerializeFilters.Add((swagger, httpReq) =>
    {
        if (!httpReq.Headers.ContainsKey("X-API-Key"))
        {
            throw new UnauthorizedAccessException();
        }
    });
});

트러블슈팅 가이드

일반적인 문제와 해결책

모니터링 및 분석

Application Insights 통합

builder.Services.AddApplicationInsightsTelemetry();

// Swagger 사용량 추적
app.UseSwagger(options =>
{
    options.PreSerializeFilters.Add((swagger, httpReq) =>
    {
        var telemetryClient = httpReq.HttpContext.RequestServices
            .GetRequiredService<TelemetryClient>();
        telemetryClient.TrackEvent("SwaggerAccessed");
    });
});

요약 및 베스트 프랙티스

핵심 도구 정리

개발팀을 위한 권장사항

1. 개발 초기부터 Swagger 도입하여 API 설계 단계에서 문서화
2. XML 주석을 활용한 상세한 API 설명 작성
3. DTO 패턴 적용으로 명확한 API 계약 정의
4. 버전 관리 전략 수립으로 하위 호환성 보장
5. 보안 설정 통합으로 실제 운영 환경과 일치하는 테스트 환경 구축
6. CI/CD 파이프라인에 OpenAPI 스펙 검증 단계 포함

이러한 접근을 통해 Swagger/OpenAPI는 단순한 문서화 도구를 넘어서 API 개발 생명주기 전반을 지원하는 핵심 인프라가 될 수 있습니다.

The post Swagger/OpenAPI for .NET appeared first on 어제와 내일의 나 그 사이의 이야기.