تحلیل تغییرات بین نسخه‌های صفحه‌گسترده یک کار روتین برای جریان‌های کاری مالی، گزارش‌گیری و اعتبارسنجی داده‌ها است. GroupDocs.Comparison Cloud SDK for .NET یک API قدرتمند ارائه می‌دهد که مقایسه فایل‌های Excel را در .NET بدون بازرسی دستی آسان می‌کند. در این راهنما خواهید دید که چگونه کتابخانه را تنظیم کنید، کتاب‌های کاری را بارگذاری کنید، نقطه انتهایی REST را از C# فراخوانی کنید، اطلاعات دقیق تغییرات را بازیابی کنید و گزینه‌های مقایسه را برای نتایج دقیق تنظیم دقیق کنید.

قبل از شروع: پیش‌نیازها و نصب

قبل از شروع، مطمئن شوید که موارد زیر را دارید:

  • .NET 6.0 یا نسخه‌های بعدی نصب شده باشد.
  • یک IDE مانند Visual Studio 2022.
  • یک حساب GroupDocs Cloud با ClientId و ClientSecret.
  • دسترسی به ذخیره‌سازی GroupDocs Cloud که فایل‌های Excel در آن بارگذاری می‌شوند.

SDK را از طریق NuGet نصب کنید:

dotnet add package GroupDocs.Comparison-Cloud

آخرین بسته را از صفحه انتشار دانلود کنید. پس از نصب، اعتبارنامه‌های خود را همان‌طور که در ادامه نشان داده شده است، در کد اضافه کنید. اکنون آماده‌اید تا جریان کار مقایسه را آغاز کنید.

راهنمای گام‌به‌گام برای مقایسه فایل‌های Excel در .NET

مراحل زیر نشان می‌دهند که چگونه می‌توان فایل‌های Excel را در .NET با استفاده از SDK مقایسه کرد.

مرحله 1: بارگذاری اسناد منبع و هدف

یک شیء پیکربندی با اعتبارهای خود ایجاد کنید و CompareApi را نمونه‌سازی کنید.

var config = new Configuration
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET"
};

var compareApi = new CompareApi(config);

گام ۲: آماده‌سازی کتاب‌های کار Excel

اشیاء FileInfo را تعریف کنید که به فایل‌های منبع و هدف XLSX ذخیره‌شده در فضای ذخیره‌سازی GroupDocs Cloud اشاره می‌کنند.

var sourceFile = new FileInfo { FilePath = "input/source.xlsx" };
var targetFile = new FileInfo { FilePath = "input/target.xlsx" };

مرحله 3: تنظیم گزینه‌ها و تنظیمات مقایسه

پیکربندی شیء CompareOptions، شامل تنظیمات تغییرات دقیق.

var compareOptions = new CompareOptions
{
    SourceFile = sourceFile,
    TargetFiles = new List<FileInfo> { targetFile },
    OutputPath = "output/diff_result.xlsx",
    Settings = new Settings
    {
        ShowDeletedContent = true,
        ShowInsertedContent = true,
        ShowStyleChanges = true,
        GenerateSummaryPage = true
    }
};

برای دریافت فهرست کامل تنظیمات، به مرجع API مراجعه کنید.

مرحله ۴: اجرای مقایسه و پردازش نتایج

متد Compare را فراخوانی کنید و اطلاعات پایهٔ نتیجه را بخوانید.

var compareResult = compareApi.Compare(compareOptions);
Console.WriteLine($"Comparison completed. Result file: {compareResult.Path}");
Console.WriteLine($"Number of changes detected: {compareResult.Changes?.Count ?? 0}");

مرحله 5: دریافت اطلاعات دقیق تغییر

اگر به گزارشی جزئی نیاز دارید، درخواست GetChanges را استفاده کنید.

var changesRequest = new GetChangesRequest
{
    SourceFile = sourceFile,
    TargetFile = targetFile,
    OutputPath = "output/detailed_changes.json"
};
var detailedChanges = compareApi.GetChanges(changesRequest);
Console.WriteLine($"Detailed changes saved to: {detailedChanges.Path}");

با این مراحل، شما فرآیند مقایسه فایل‌های Excel را در .NET به‌صورت کامل خودکار کرده‌اید.

مقایسه فایل‌های Excel به‌صورت برنامه‌نویسی - مثال کامل کد

کد زیر جریان کاری کامل از پیکربندی تا پردازش نتایج را نشان می‌دهد.

using System;
using System.Collections.Generic;
using GroupDocs.Comparison.Cloud.Sdk.Api;
using GroupDocs.Comparison.Cloud.Sdk.Client;
using GroupDocs.Comparison.Cloud.Sdk.Model;

namespace CompareExcelDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Set up API credentials (replace with your actual credentials)
            var config = new Configuration
            {
                ClientId = "YOUR_CLIENT_ID",
                ClientSecret = "YOUR_CLIENT_SECRET"
            };

// Initialize Compare API
            var compareApi = new CompareApi(config);

// Prepare source and target Excel files (must be uploaded to GroupDocs Cloud storage beforehand)
            var sourceFile = new FileInfo { FilePath = "input/source.xlsx" };
            var targetFile = new FileInfo { FilePath = "input/target.xlsx" };

// Define comparison options
            var compareOptions = new CompareOptions
            {
                SourceFile = sourceFile,
                TargetFiles = new List<FileInfo> { targetFile },
                OutputPath = "output/diff_result.xlsx",
                // Optional: specify that we want detailed changes for worksheets
                Settings = new Settings
                {
                    ShowDeletedContent = true,
                    ShowInsertedContent = true,
                    ShowStyleChanges = true,
                    GenerateSummaryPage = true
                }
            };

try
            {
                // Call the Compare API
                var compareResult = compareApi.Compare(compareOptions);

// Output basic result information
                Console.WriteLine($"Comparison completed. Result file: {compareResult.Path}");
                Console.WriteLine($"Number of changes detected: {compareResult.Changes?.Count ?? 0}");

// Iterate through change details
                if (compareResult.Changes != null)
                {
                    foreach (var change in compareResult.Changes)
                    {
                        Console.WriteLine("--------------------------------------------------");
                        Console.WriteLine($"Change Type   : {change.ChangeType}");
                        Console.WriteLine($"Worksheet     : {change.Worksheet}");
                        Console.WriteLine($"Cell Address  : {change.CellAddress}");
                        Console.WriteLine($"Old Value     : {change.OldValue}");
                        Console.WriteLine($"New Value     : {change.NewValue}");
                        Console.WriteLine($"Is New Row    : {change.IsNewRow}");
                        Console.WriteLine($"Is New Column : {change.IsNewColumn}");
                    }
                }

// Retrieve detailed changes via GetChanges (optional)
                var changesRequest = new GetChangesRequest
                {
                    SourceFile = sourceFile,
                    TargetFile = targetFile,
                    OutputPath = "output/detailed_changes.json"
                };
                var detailedChanges = compareApi.GetChanges(changesRequest);
                Console.WriteLine($"Detailed changes saved to: {detailedChanges.Path}");
            }
            catch (ApiException apiEx)
            {
                Console.WriteLine($"API error: {apiEx.ErrorCode} - {apiEx.Message}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Unexpected error: {ex.Message}");
            }
        }
    }
}

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید مسیرهای فایل و مقادیر پیکربندی را به‌گونه‌ای به‌روزرسانی کنید که با محیط واقعی شما مطابقت داشته باشد، اطمینان حاصل کنید تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند، و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.

انجام مقایسه Excel از طریق REST با cURL

می‌توانید همان نتیجه را بدون نوشتن کد C# با فراخوانی مستقیم REST API به دست آورید.

1. احراز هویت و دریافت توکن دسترسی

curl -X POST "https://api.groupdocs.cloud/v1.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

2. بارگذاری کتاب کار منبع

curl -X PUT "https://api.groupdocs.cloud/v1.0/storage/file?path=input/source.xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -T "./source.xlsx"

3. بارگذاری کتاب کار هدف

curl -X PUT "https://api.groupdocs.cloud/v1.0/storage/file?path=input/target.xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -T "./target.xlsx"

4. اجرای مقایسه

curl -X POST "https://api.groupdocs.cloud/v1.0/comparison/compare" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "source_file": {"file_path":"input/source.xlsx"},
           "target_files": [{"file_path":"input/target.xlsx"}],
           "output_path":"output/diff_result.xlsx",
           "settings": {
               "show_deleted_content": true,
               "show_inserted_content": true,
               "show_style_changes": true,
               "generate_summary_page": true
           }
         }'

5. دانلود دفتر کار Diff حاصل

curl -X GET "https://api.groupdocs.cloud/v1.0/storage/file?path=output/diff_result.xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o diff_result.xlsx

برای دریافت فهرست کامل پارامترها، به مستندات رسمی API مراجعه کنید.

نتیجه‌گیری

با استفاده از GroupDocs.Comparison Cloud SDK for .NET می‌توانید به راحتی فایل‌های Excel را در .NET مقایسه کنید و یک کتاب‌کار diff دقیق دریافت کنید که هر تغییر را برجسته می‌کند. معماری مبتنی بر REST این SDK به شما امکان می‌دهد مقایسه صفحات گسترده را به هر سرویس C#، وب API یا کار پس‌زمینه با کمترین تلاش یکپارچه کنید. به یاد داشته باشید برای استفاده در تولید یک لایسنس مناسب تهیه کنید؛ یک لایسنس موقت از صفحه لایسنس در دسترس است و جزئیات کامل لایسنس‌گذاری در سایت محصول آمده است. امروز شروع به خودکارسازی جریان‌های کاری diff Excel خود کنید و خطاهای بازرسی دستی را از بین ببرید.

سوالات متداول

  • چگونه می‌توانم فایل‌های Excel را در .NET بدون نوشتن کد زیاد مقایسه کنم؟
    SDK کارهای سنگین را انتزاع می‌کند. فقط کافی است اعتبارنامه‌ها را پیکربندی کنید، به دو فایل XLSX اشاره کنید، و compareApi.Compare را فراخوانی کنید. کتابخانه یک فایل diff و فهرستی از اشیاء تغییر را برمی‌گرداند.

  • نتیجه diff به چه فرمتی ذخیره می‌شود؟
    به‌طور پیش‌فرض نتیجه به‌صورت یک کتاب‌کار XLSX ذخیره می‌شود، در حالی که طرح اصلی حفظ می‌شود و نشانگرهای بصری برای حذف‌ها، افزودن‌ها و تغییرات سبک اعمال می‌شود.

  • آیا امکان مقایسه کتاب‌های کار Excel محافظت‌شده وجود دارد؟
    بله. پسورد را در ویژگی Password شیء FileInfo ارائه دهید. API قبل از انجام مقایسه، کتاب کار را باز می‌کند.

  • آیا برای توسعه و تست به مجوز نیاز دارم؟
    یک مجوز موقت می‌تواند از صفحه مجوز دریافت شود. برای استقرارهای تولیدی باید یک مجوز کامل خریداری کنید همان‌طور که در صفحه محصول توضیح داده شده است.

بیشتر بخوانید