이메일 형식 변환기
ASP.NET 코어에서 간단한 이메일 변환 웹 API를 만드는 방법

ASP.NET 코어에서 간단한 이메일 변환 웹 API를 만드는 방법

전자 메일 변환을위한 마이크로 서비스 또는 웹 API를 만드는 것은 다른 응용 프로그램이 전체 Aspose.Email 라이브러리를 통합하지 않고 전환 기능을 활용할 수 있습니다.이 접근 방식은 여러 클라이언트, 애플리케이션 또는 시스템을 봉사 할 수있는 중앙화 된, 스케일 가능한 솔루션을 제공합니다. ASP.NET 코어와 아스포스.email LowCode Converter를 사용하면 HTTP 업로드를 통해 이메일 파일을 수락하고 다운로드를 위해 변형 된 파일이 반환됩니다.

왜 이메일 변환 API를 구축합니까?

전용 이메일 변환 API는 여러 가지 장점을 제공합니다 :

  • 중앙 처리 : 단일 서비스는 모든 변환 논리를 처리합니다.
  • Cross-Platform Access : 모든 응용 프로그램은 HTTP를 통해 API를 사용할 수 있습니다.
  • Scalability : 독립적으로 배치하고 수요에 따라 스케일
  • Technology Independence : 고객은 .NET 또는 Aspose.Email 의존성이 필요하지 않습니다.
  • Microservice Architecture : 현대 배포된 응용 패턴에 적합합니다.
  • 리소스 관리 : 처리 자원에 대한 중앙 통제

원칙

이메일 변환 API를 구축하기 전에, 당신이 가지고 있는지 확인하십시오 :

  • ASP.NET Core 6.0 또는 그 이상의 개발 환경
  • Visual Studio 2022 또는 Visual Studio 코드 C# 확장 기능
  • Aspose.Email NuGet 패키지
  • RESTful API 디자인에 대한 기본 지식
  • 웹 APIs에서 파일 업로드/다운로드에 대한 이해

1단계: API 프로젝트 설정

새로운 ASP.NET Core Web API 프로젝트 만들기 :

dotnet new webapi -n EmailConverterApi
cd EmailConverterApi
dotnet add package Aspose.Email
dotnet add package Swashbuckle.AspNetCore

프로젝트 파일을 설정합니다 (EmailConverterApi.csproj):

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspose.Email" Version="24.3.0" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>

</Project>

2단계: 이메일 컨버터 컨트롤러 만들기

이메일 변환 작업을 관리하는 포괄적 인 컨트롤러를 만드십시오 :

using Aspose.Email.LowCode;
using Microsoft.AspNetCore.Mvc;
using System.ComponentModel.DataAnnotations;

namespace EmailConverterApi.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    [Produces("application/json")]
    public class EmailConverterController : ControllerBase
    {
        private readonly ILogger<EmailConverterController> _logger;
        private readonly IConfiguration _configuration;
        private readonly long _maxFileSize;
        private readonly string[] _allowedExtensions = { ".eml", ".msg" };
        private readonly string[] _supportedOutputFormats = { "html", "eml", "msg", "mhtml", "mht" };

        public EmailConverterController(ILogger<EmailConverterController> logger, IConfiguration configuration)
        {
            _logger = logger;
            _configuration = configuration;
            _maxFileSize = _configuration.GetValue<long>("MaxFileSize", 10 * 1024 * 1024); // 10MB default
        }

        /// <summary>
        /// Converts an email file to the specified format
        /// </summary>
        /// <param name="emailFile">The email file to convert (EML or MSG)</param>
        /// <param name="format">Output format (html, eml, msg, mhtml, mht)</param>
        /// <param name="filename">Optional custom filename for the output</param>
        /// <returns>The converted file for download</returns>
        [HttpPost("convert")]
        [ProducesResponseType(typeof(FileResult), 200)]
        [ProducesResponseType(typeof(ApiErrorResponse), 400)]
        [ProducesResponseType(typeof(ApiErrorResponse), 500)]
        public async Task<IActionResult> ConvertEmail(
            [Required] IFormFile emailFile,
            [FromQuery, Required] string format = "html",
            [FromQuery] string? filename = null)
        {
            var requestId = Guid.NewGuid().ToString("N")[..8];
            _logger.LogInformation("Starting conversion request {RequestId} for file: {FileName}, format: {Format}", 
                requestId, emailFile?.FileName, format);

            try
            {
                // Validate request
                var validationResult = ValidateRequest(emailFile, format);
                if (validationResult != null)
                {
                    _logger.LogWarning("Validation failed for request {RequestId}: {Error}", requestId, validationResult.Message);
                    return validationResult;
                }

                // Create in-memory output handler
                var outputHandler = new MemoryOutputHandler();
                
                // Perform conversion
                using var inputStream = emailFile!.OpenReadStream();
                await ConvertEmailInternal(inputStream, emailFile.FileName, outputHandler, format);

                // Get converted content
                var convertedContent = outputHandler.GetContent();
                var outputFileName = filename ?? GenerateOutputFileName(emailFile.FileName, format);
                var contentType = GetContentType(format);

                _logger.LogInformation("Successfully converted {RequestId}: {InputFile} -> {OutputFile} ({Size} bytes)", 
                    requestId, emailFile.FileName, outputFileName, convertedContent.Length);

                // Return file for download
                return File(convertedContent, contentType, outputFileName);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Conversion failed for request {RequestId}: {Error}", requestId, ex.Message);
                return StatusCode(500, new ApiErrorResponse 
                { 
                    Message = "Internal server error during conversion", 
                    RequestId = requestId 
                });
            }
        }

        /// <summary>
        /// Gets information about supported formats and API capabilities
        /// </summary>
        [HttpGet("info")]
        [ProducesResponseType(typeof(ApiInfoResponse), 200)]
        public IActionResult GetApiInfo()
        {
            return Ok(new ApiInfoResponse
            {
                SupportedInputFormats = _allowedExtensions,
                SupportedOutputFormats = _supportedOutputFormats,
                MaxFileSizeMB = _maxFileSize / (1024 * 1024),
                Version = "1.0.0",
                Description = "Email format conversion API powered by Aspose.Email"
            });
        }

        /// <summary>
        /// Health check endpoint
        /// </summary>
        [HttpGet("health")]
        [ProducesResponseType(typeof(HealthResponse), 200)]
        public IActionResult HealthCheck()
        {
            return Ok(new HealthResponse 
            { 
                Status = "Healthy", 
                Timestamp = DateTime.UtcNow,
                Version = "1.0.0"
            });
        }

        private IActionResult? ValidateRequest(IFormFile? emailFile, string format)
        {
            if (emailFile == null || emailFile.Length == 0)
            {
                return BadRequest(new ApiErrorResponse { Message = "No file provided or file is empty" });
            }

            if (emailFile.Length > _maxFileSize)
            {
                return BadRequest(new ApiErrorResponse 
                { 
                    Message = $"File size exceeds maximum allowed size of {_maxFileSize / (1024 * 1024)}MB" 
                });
            }

            var extension = Path.GetExtension(emailFile.FileName)?.ToLowerInvariant();
            if (string.IsNullOrEmpty(extension) || !_allowedExtensions.Contains(extension))
            {
                return BadRequest(new ApiErrorResponse 
                { 
                    Message = $"Unsupported file format. Allowed formats: {string.Join(", ", _allowedExtensions)}" 
                });
            }

            if (string.IsNullOrEmpty(format) || !_supportedOutputFormats.Contains(format.ToLowerInvariant()))
            {
                return BadRequest(new ApiErrorResponse 
                { 
                    Message = $"Unsupported output format. Supported formats: {string.Join(", ", _supportedOutputFormats)}" 
                });
            }

            return null;
        }

        private static async Task ConvertEmailInternal(Stream inputStream, string fileName, IOutputHandler outputHandler, string format)
        {
            switch (format.ToLowerInvariant())
            {
                case "html":
                    await Converter.ConvertToHtml(inputStream, fileName, outputHandler);
                    break;
                case "eml":
                    await Converter.ConvertToEml(inputStream, fileName, outputHandler);
                    break;
                case "msg":
                    await Converter.ConvertToMsg(inputStream, fileName, outputHandler);
                    break;
                case "mhtml":
                    await Converter.ConvertToMhtml(inputStream, fileName, outputHandler);
                    break;
                case "mht":
                    await Converter.ConvertToMht(inputStream, fileName, outputHandler);
                    break;
                default:
                    throw new ArgumentException($"Unsupported conversion format: {format}");
            }
        }

        private static string GenerateOutputFileName(string inputFileName, string format)
        {
            var nameWithoutExtension = Path.GetFileNameWithoutExtension(inputFileName);
            return $"{nameWithoutExtension}.{format.ToLowerInvariant()}";
        }

        private static string GetContentType(string format) => format.ToLowerInvariant() switch
        {
            "html" => "text/html",
            "eml" => "message/rfc822",
            "msg" => "application/vnd.ms-outlook",
            "mhtml" => "message/rfc822",
            "mht" => "message/rfc822",
            _ => "application/octet-stream"
        };
    }
}

단계 3: In-Memory Output Handler 만들기

메모리에 변환 된 콘텐츠를 캡처하는 사용자 지정 출력 거래자를 만드십시오 :

using Aspose.Email.LowCode;
using System.Text;

namespace EmailConverterApi.Services
{
    /// <summary>
    /// Output handler that captures converted content in memory for API responses
    /// </summary>
    public class MemoryOutputHandler : IOutputHandler
    {
        private byte[]? _content;
        private string? _fileName;

        public async Task AddOutputStream(string name, Func<Stream, Task> writeAction)
        {
            _fileName = name;
            using var memoryStream = new MemoryStream();
            await writeAction(memoryStream);
            _content = memoryStream.ToArray();
        }

        public void AddOutputStream(string name, Action<Stream> writeAction)
        {
            _fileName = name;
            using var memoryStream = new MemoryStream();
            writeAction(memoryStream);
            _content = memoryStream.ToArray();
        }

        public byte[] GetContent()
        {
            return _content ?? throw new InvalidOperationException("No content has been written to this handler");
        }

        public string GetContentAsString()
        {
            var content = GetContent();
            return Encoding.UTF8.GetString(content);
        }

        public string GetFileName()
        {
            return _fileName ?? throw new InvalidOperationException("No file name available");
        }

        public bool HasContent => _content != null && _content.Length > 0;
    }
}

단계 4 : 응답 모델 만들기

API에 대한 구조화 된 응답 모델을 정의하십시오 :

namespace EmailConverterApi.Models
{
    /// <summary>
    /// Standard error response model
    /// </summary>
    public class ApiErrorResponse
    {
        public string Message { get; set; } = string.Empty;
        public string? RequestId { get; set; }
        public DateTime Timestamp { get; set; } = DateTime.UtcNow;
        public string? Details { get; set; }
    }

    /// <summary>
    /// API information response model
    /// </summary>
    public class ApiInfoResponse
    {
        public string[] SupportedInputFormats { get; set; } = Array.Empty<string>();
        public string[] SupportedOutputFormats { get; set; } = Array.Empty<string>();
        public long MaxFileSizeMB { get; set; }
        public string Version { get; set; } = string.Empty;
        public string Description { get; set; } = string.Empty;
    }

    /// <summary>
    /// Health check response model
    /// </summary>
    public class HealthResponse
    {
        public string Status { get; set; } = string.Empty;
        public DateTime Timestamp { get; set; }
        public string Version { get; set; } = string.Empty;
        public Dictionary<string, object>? AdditionalInfo { get; set; }
    }

    /// <summary>
    /// Conversion request model for batch operations
    /// </summary>
    public class BatchConversionRequest
    {
        public string OutputFormat { get; set; } = "html";
        public bool ZipOutput { get; set; } = true;
        public string? CustomPrefix { get; set; }
    }

    /// <summary>
    /// Batch conversion result
    /// </summary>
    public class BatchConversionResult
    {
        public int TotalFiles { get; set; }
        public int SuccessfulConversions { get; set; }
        public int FailedConversions { get; set; }
        public List<ConversionError> Errors { get; set; } = new();
        public string? OutputFileName { get; set; }
    }

    /// <summary>
    /// Individual conversion error details
    /// </summary>
    public class ConversionError
    {
        public string FileName { get; set; } = string.Empty;
        public string ErrorMessage { get; set; } = string.Empty;
    }
}

5단계: 배치 변환 지원 추가

컨트롤러를 확장하여 배치 변환을 지원합니다.

/// <summary>
/// Converts multiple email files and returns them as a ZIP archive
/// </summary>
/// <param name="emailFiles">Multiple email files to convert</param>
/// <param name="request">Batch conversion settings</param>
/// <returns>ZIP file containing all converted emails</returns>
[HttpPost("convert-batch")]
[ProducesResponseType(typeof(FileResult), 200)]
[ProducesResponseType(typeof(ApiErrorResponse), 400)]
[ProducesResponseType(typeof(ApiErrorResponse), 500)]
public async Task<IActionResult> ConvertEmailBatch(
    [Required] IFormFileCollection emailFiles,
    [FromForm] BatchConversionRequest request)
{
    var requestId = Guid.NewGuid().ToString("N")[..8];
    _logger.LogInformation("Starting batch conversion request {RequestId} for {FileCount} files, format: {Format}", 
        requestId, emailFiles.Count, request.OutputFormat);

    try
    {
        if (!emailFiles.Any())
        {
            return BadRequest(new ApiErrorResponse { Message = "No files provided for batch conversion" });
        }

        if (!_supportedOutputFormats.Contains(request.OutputFormat.ToLowerInvariant()))
        {
            return BadRequest(new ApiErrorResponse 
            { 
                Message = $"Unsupported output format: {request.OutputFormat}" 
            });
        }

        var results = new List<(string FileName, byte[] Content, bool Success, string? Error)>();

        // Process each file
        foreach (var file in emailFiles)
        {
            try
            {
                var validationResult = ValidateRequest(file, request.OutputFormat);
                if (validationResult != null)
                {
                    results.Add((file.FileName, Array.Empty<byte>(), false, "Validation failed"));
                    continue;
                }

                var outputHandler = new MemoryOutputHandler();
                using var inputStream = file.OpenReadStream();
                
                await ConvertEmailInternal(inputStream, file.FileName, outputHandler, request.OutputFormat);
                
                results.Add((file.FileName, outputHandler.GetContent(), true, null));
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to convert file {FileName} in batch {RequestId}", file.FileName, requestId);
                results.Add((file.FileName, Array.Empty<byte>(), false, ex.Message));
            }
        }

        // Create ZIP archive
        var zipContent = CreateZipArchive(results, request);
        var zipFileName = $"converted_emails_{DateTime.Now:yyyyMMdd_HHmmss}.zip";

        _logger.LogInformation("Batch conversion {RequestId} completed: {Success}/{Total} successful", 
            requestId, results.Count(r => r.Success), results.Count);

        return File(zipContent, "application/zip", zipFileName);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Batch conversion failed for request {RequestId}: {Error}", requestId, ex.Message);
        return StatusCode(500, new ApiErrorResponse 
        { 
            Message = "Internal server error during batch conversion", 
            RequestId = requestId 
        });
    }
}

private static byte[] CreateZipArchive(List<(string FileName, byte[] Content, bool Success, string? Error)> results, BatchConversionRequest request)
{
    using var zipStream = new MemoryStream();
    using (var archive = new System.IO.Compression.ZipArchive(zipStream, System.IO.Compression.ZipArchiveMode.Create, true))
    {
        // Add successful conversions
        foreach (var (fileName, content, success, _) in results.Where(r => r.Success))
        {
            var outputFileName = GenerateOutputFileName(fileName, request.OutputFormat);
            if (!string.IsNullOrEmpty(request.CustomPrefix))
            {
                outputFileName = $"{request.CustomPrefix}_{outputFileName}";
            }

            var entry = archive.CreateEntry(outputFileName);
            using var entryStream = entry.Open();
            entryStream.Write(content, 0, content.Length);
        }

        // Add error log if there were failures
        var failures = results.Where(r => !r.Success).ToList();
        if (failures.Any())
        {
            var errorLog = string.Join("\n", failures.Select(f => $"{f.FileName}: {f.Error}"));
            var errorEntry = archive.CreateEntry("conversion_errors.txt");
            using var errorStream = errorEntry.Open();
            using var writer = new StreamWriter(errorStream);
            writer.Write(errorLog);
        }
    }

    return zipStream.ToArray();
}

단계 6 : 응용 프로그램 설정

응용 프로그램을 적절한 구성으로 설정합니다. Program.cs:

using EmailConverterApi.Services;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Add services
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Email Converter API",
        Version = "v1",
        Description = "RESTful API for converting email files between different formats using Aspose.Email",
        Contact = new OpenApiContact
        {
            Name = "API Support",
            Email = "support@example.com"
        }
    });
    
    // Include XML comments if available
    var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    if (File.Exists(xmlPath))
    {
        c.IncludeXmlComments(xmlPath);
    }
});

// Configure file upload limits
builder.Services.Configure<IISServerOptions>(options =>
{
    options.MaxRequestBodySize = 50 * 1024 * 1024; // 50MB
});

// Add CORS if needed
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", policy =>
    {
        policy.AllowAnyOrigin()
              .AllowAnyHeader()
              .AllowAnyMethod();
    });
});

// Add logging
builder.Logging.AddConsole();
builder.Logging.AddDebug();

var app = builder.Build();

// Configure pipeline
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Email Converter API V1");
        c.RoutePrefix = string.Empty; // Swagger at root
    });
}

app.UseHttpsRedirection();
app.UseCors("AllowAll");
app.UseAuthorization();
app.MapControllers();

app.Run();

단계 7 : 설정 설정

Configuration에 추가 appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "EmailConverterApi": "Debug"
    }
  },
  "AllowedHosts": "*",
  "MaxFileSize": 52428800,
  "ConversionSettings": {
    "DefaultOutputFormat": "html",
    "EnableBatchConversion": true,
    "MaxBatchSize": 10,
    "TempDirectory": "temp"
  }
}

단계 8 : 오류 처리 중개를 추가

글로벌 오류 처리 middleware 만들기:

using System.Net;
using System.Text.Json;

namespace EmailConverterApi.Middleware
{
    public class GlobalErrorHandlingMiddleware
    {
        private readonly RequestDelegate _next;
        private readonly ILogger<GlobalErrorHandlingMiddleware> _logger;

        public GlobalErrorHandlingMiddleware(RequestDelegate next, ILogger<GlobalErrorHandlingMiddleware> logger)
        {
            _next = next;
            _logger = logger;
        }

        public async Task InvokeAsync(HttpContext context)
        {
            try
            {
                await _next(context);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "An unhandled exception occurred");
                await HandleExceptionAsync(context, ex);
            }
        }

        private static async Task HandleExceptionAsync(HttpContext context, Exception exception)
        {
            context.Response.ContentType = "application/json";
            
            var (statusCode, message) = exception switch
            {
                ArgumentException => (HttpStatusCode.BadRequest, exception.Message),
                FileNotFoundException => (HttpStatusCode.NotFound, "Requested file not found"),
                UnauthorizedAccessException => (HttpStatusCode.Unauthorized, "Access denied"),
                NotSupportedException => (HttpStatusCode.BadRequest, "Operation not supported"),
                _ => (HttpStatusCode.InternalServerError, "An error occurred while processing your request")
            };

            context.Response.StatusCode = (int)statusCode;

            var response = new
            {
                message = message,
                statusCode = (int)statusCode,
                timestamp = DateTime.UtcNow
            };

            await context.Response.WriteAsync(JsonSerializer.Serialize(response));
        }
    }
}

// Register middleware in Program.cs
app.UseMiddleware<GlobalErrorHandlingMiddleware>();

단계 9 : 고객 사용 예제

CURL 예제

단일 파일을 변환 :

curl -X POST "https://localhost:5001/api/emailconverter/convert?format=html" \
  -H "Content-Type: multipart/form-data" \
  -F "emailFile=@sample.eml" \
  -o converted.html

API 정보 제공:

curl -X GET "https://localhost:5001/api/emailconverter/info"

C# 고객 예제 

public class EmailConverterClient
{
    private readonly HttpClient _httpClient;
    
    public EmailConverterClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }
    
    public async Task<byte[]> ConvertEmailAsync(string filePath, string outputFormat = "html")
    {
        using var form = new MultipartFormDataContent();
        using var fileStream = File.OpenRead(filePath);
        using var fileContent = new StreamContent(fileStream);
        
        fileContent.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/octet-stream");
        form.Add(fileContent, "emailFile", Path.GetFileName(filePath));
        
        var response = await _httpClient.PostAsync($"/api/emailconverter/convert?format={outputFormat}", form);
        response.EnsureSuccessStatusCode();
        
        return await response.Content.ReadAsByteArrayAsync();
    }
}

JavaScript 클라이언트 예제 

async function convertEmail(file, format = 'html') {
    const formData = new FormData();
    formData.append('emailFile', file);
    
    const response = await fetch(`/api/emailconverter/convert?format=${format}`, {
        method: 'POST',
        body: formData
    });
    
    if (!response.ok) {
        throw new Error(`Conversion failed: ${response.statusText}`);
    }
    
    return await response.blob();
}

결론

ASP.NET Core 및 Aspose.Email LowCode Converter를 사용하여 이메일 변환 웹 API를 구축하면 강력하고 재사용 가능한 서비스를 제공합니다.

  • 중앙 처리 : 단일 서비스는 모든 이메일 변환을 처리합니다.
  • Cross-Platform Access : HTTP 기반 인터페이스는 모든 클라이언트 기술과 함께 작동합니다.
  • Scalability : 클라이언트 응용 프로그램에 관계없이 배치 및 규모
  • 포괄적 인 기능 : 여러 형식 지원, 배치 처리 및 오류 처리
  • Production Ready : 로그인, 구성, 인증 및 문서화 포함

이 API 아키텍처는 조직이 서비스로서 이메일 변환 능력을 제공하고, 여러 응용 프로그램을 지원하고 사용 사례를 유지하면서 처리 논리와 자원에 대한 중앙 통제를 유지할 수 있습니다.이 마이크로 서비스 접근 방식은 현대 애플리케이션 건축을 촉진하고 기존 시스템과 작업 흐름과의 쉽게 통합을 가능하게합니다.

 한국어