تعریف، امضا و قرارداد خروجی

در الگوی TryParse، ورودی بررسی و نتیجه از طریق پارامتر out برگردانده می‌شود. در موفقیت یک Guid ساخته می‌شود و در شکست result برابر Guid.Empty خواهد بود، هرچند بهتر است تصمیم فقط بر اساس مقدار بازگشتی متد گرفته شود. این قرارداد برای مرزهای غیرقابل‌اعتماد، مانند فرم و فایل، خوانا است و مسیر شکست را به بخش عادی منطق برنامه تبدیل می‌کند.

امضاهای مهم

Guid.TryParse(string? input, out Guid result);
    Guid.TryParse(ReadOnlySpan<char> input, out Guid result);

تحلیل فنی و طراحی صحیح

استفاده حرفه‌ای از Guid.TryParse() با تشخیص مرز اعتماد آغاز می‌شود. متنی که کاربر، فایل CSV، پارامتر URL یا سامانه بیرونی تولید کرده است می‌تواند خالی، ناسازگار یا مخرب باشد. TryParse یک سد نحوی فراهم می‌کند، اما طول ورودی، قواعد دامنه، مجوز دسترسی و ارتباط مقدار با سایر فیلدها همچنان باید کنترل شود.

در حوزه شناسه درخواست، کلید عمومی، Correlation ID و پیوند امن رکوردها باید میان «قابل تبدیل بودن» و «قابل پذیرش بودن» فرق گذاشت. ممکن است متن به‌درستی تبدیل شود اما مقدار خارج از بازه سیاست سازمان، شناسه ناشناخته یا تاریخ غیرمجاز باشد. این جداسازی پیام خطای دقیق‌تر، آزمون واحد ساده‌تر و تغییر قواعد کسب‌وکار بدون دستکاری Parser را ممکن می‌کند.

در API بهتر است خطای تبدیل به پاسخ ساخت‌یافته شامل نام فیلد و کد خطا تبدیل شود. در Import نیز ردیف‌های خراب را همراه شماره خط و دلیل رد در گزارش جدا نگه دارید. حذف خاموش خطاها ممکن است جمع گزارش یا تصمیم مدیریتی را تحریف کند؛ بنابراین شاخص کیفیت داده بخشی از خروجی فرایند است.

Culture باید از قرارداد واقعی داده بیاید. فایل ماشینی معمولاً با InvariantCulture و قالب ثابت امن‌تر است، درحالی‌که فرم محلی باید فرهنگ انتخاب‌شده کاربر را به کار گیرد. اتکا به CurrentCulture سرور می‌تواند پس از جابه‌جایی محیط، به‌روزرسانی کانتینر یا اجرای تست روی رایانه دیگر نتیجه را تغییر دهد.

از نظر امنیت، Guid.TryParse() تنها تبدیل را انجام می‌دهد و جای اعتبارسنجی مجوز، محدودیت طول، Allowlist یا کنترل وجود رکورد را نمی‌گیرد. برای شناسه درخواست، کلید عمومی، Correlation ID و پیوند امن رکوردها ورودی بسیار طولانی را پیش از پردازش محدود کنید، اطلاعات حساس را در لاگ ننویسید و پیام داخلی استثنا را مستقیماً به کاربر نشان ندهید.

از نظر نگهداری، بهتر است فراخوانی‌های تکراری در Parser یا Value Object دامنه‌ای متمرکز شوند. آن جزء می‌تواند Culture، بازه مجاز، پیام‌های فارسی و انگلیسی و سیاست null را یکسان کند. پراکندگی تبدیل در کنترلر، فرم و Repository معمولاً به رفتارهای متفاوت و رفع اشکال دشوار منجر می‌شود.

مثال‌های عملی گام‌به‌گام

ده مثال زیر از تبدیل پایه آغاز می‌شوند و به سناریوهای مجموعه‌داده، null، مرز، خطای Culture و کارایی می‌رسند. هر مثال برای Guid.TryParse() طراحی شده و نتیجه نمونه را بدون نیاز به اجرای اولیه نشان می‌دهد.

مثال شماره 1: تبدیل قالب D

رشته استاندارد خط‌تیره‌دار به Guid تبدیل می‌شود. مقدار بازگشتی متد قبل از استفاده از شناسه بررسی می‌گردد.

using System;

    internal static class Program
    {
        private static void Main()
        {
            string input = "6f9619ff-8b86-d011-b42d-00c04fc964ff";
            bool ok = Guid.TryParse(input, out Guid id);
            Console.WriteLine($"ok={ok}; id={id:D}");
        }
    }

قالب D برای API و لاگ خوانا است. قالب ذخیره‌سازی را در قرارداد سرویس ثابت نگه دارید.

مثال شماره 2: پذیرش چند قالب Guid

Guid.TryParse چند قالب شناخته‌شده را می‌پذیرد. این انعطاف برای ورودی عمومی مفید است، اما ممکن است قرارداد سخت API را بیش از حد باز کند.

using System;

    internal static class Program
    {
        private static void Main()
        {
            string[] values = { "6f9619ff-8b86-d011-b42d-00c04fc964ff", "{7c9e6679-7425-40de-944b-e07fc1f90ae7}", "7c9e6679742540de944be07fc1f90ae7" };
            foreach (string text in values)
            {
                Console.WriteLine(Guid.TryParse(text, out Guid id) ? id.ToString("D") : "نامعتبر");
            }
        }
    }

اگر فقط یک قالب مجاز است از Guid.TryParseExact استفاده کنید تا خطای تولیدکننده داده زود آشکار شود.

مثال شماره 3: ورود دسته‌ای شناسه درخواست

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

using System;
    using Linq;

    internal static class Program
    {
        private static void Main()
        {
            string[] raw = { "6f9619ff-8b86-d011-b42d-00c04fc964ff", "bad-id", "7c9e6679-7425-40de-944b-e07fc1f90ae7" };
            var ids = raw.Select(text => Guid.TryParse(text, out Guid id) ? id : (Guid?)null).ToArray();
            Console.WriteLine($"valid={ids.Count(id => id.HasValue)}");
        }
    }

شناسه و شماره ردیف نامعتبر را برای پیگیری ثبت کنید. از ثبت توکن یا داده محرمانه در کنار شناسه خودداری کنید.

مثال شماره 4: فیلتر شناسه‌های قابل استفاده

پس از تبدیل نحوی، Guid.Empty حذف می‌شود تا شناسه تهی وارد جست‌وجوی پایگاه داده نشود.

using System;
    using Linq;

    internal static class Program
    {
        private static void Main()
        {
            string[] raw = { "6f9619ff-8b86-d011-b42d-00c04fc964ff", "00000000-0000-0000-0000-000000000000", "bad" };
            var accepted = raw.Where(text => Guid.TryParse(text, out Guid id) && id != Guid.Empty);
            Console.WriteLine(accepted.Count());
        }
    }

Guid.Empty از نظر نحوی معتبر است، اما اغلب از نظر کسب‌وکار مجاز نیست. این قانون باید صریح باشد.

مثال شماره 5: جست‌وجوی امن در Dictionary

تبدیل موفق شناسه پیش‌شرط جست‌وجو است. سپس وجود واقعی کلید با TryGetValue بررسی می‌شود.

using System;
    using Collections.Generic;

    internal static class Program
    {
        private static void Main()
        {
            var records = new Dictionary<Guid, string>
            {
                [Guid.Parse("6f9619ff-8b86-d011-b42d-00c04fc964ff")] = "سفارش فعال"
            };
            string input = "6f9619ff-8b86-d011-b42d-00c04fc964ff";
            if (Guid.TryParse(input, out Guid id) && records.TryGetValue(id, out string? title))
            {
                Console.WriteLine(title);
            }
        }
    }

تبدیل معتبر به معنی وجود رکورد نیست. دو مرحله اعتبار نحوی و lookup باید جدا بمانند.

مثال شماره 6: رفتار با null

شناسه اختیاری null بدون استثنا رد می‌شود. مقدار result در شکست Guid.Empty است، ولی وضعیت false معیار معتبر تصمیم است.

using System;

    internal static class Program
    {
        private static void Main()
        {
            string? input = null;
            bool ok = Guid.TryParse(input, out Guid id);
            Console.WriteLine($"ok={ok}; empty={id == Guid.Empty}");
        }
    }

اگر null معنای «ایجاد رکورد جدید» دارد، آن تصمیم را در لایه کاربردی تعریف کنید و با شناسه خراب یکی نگیرید.

مثال شماره 7: مرز معنایی Guid.Empty

رشته صفر کامل از نظر ساختار یک Guid معتبر است. سپس قانون دامنه آن را رد می‌کند.

using System;

    internal static class Program
    {
        private static void Main()
        {
            string input = "00000000-0000-0000-0000-000000000000";
            bool syntaxOk = Guid.TryParse(input, out Guid id);
            bool domainOk = syntaxOk && id != Guid.Empty;
            Console.WriteLine($"syntax={syntaxOk}; domain={domainOk}");
        }
    }

این نمونه تفاوت validation نحوی و تجاری را روشن می‌کند؛ پیام این دو خطا نیز باید متفاوت باشد.

مثال شماره 8: گزارش Correlation IDها

شناسه‌های معتبر شمارش می‌شوند و تکراری‌ها با Distinct حذف می‌گردند تا گزارش رخداد دقیق‌تر باشد.

using System;
    using Linq;

    internal static class Program
    {
        private static void Main()
        {
            string[] raw = { "6f9619ff-8b86-d011-b42d-00c04fc964ff", "6f9619ff-8b86-d011-b42d-00c04fc964ff", "7c9e6679-7425-40de-944b-e07fc1f90ae7", "bad" };
            Guid[] unique = raw
                .Select(text => Guid.TryParse(text, out Guid id) ? id : Guid.Empty)
                .Where(id => id != Guid.Empty)
                .Distinct()
                .ToArray();
            Console.WriteLine(unique.Length);
        }
    }

تکراری بودن ممکن است نشانه retry طبیعی یا خطای جریان باشد. گزارش باید زمینه عملیات را نیز در نظر بگیرد.

مثال شماره 9: قرارداد سخت با TryParseExact

Guid.TryParse قالب B را می‌پذیرد، ولی API فقط D می‌خواهد. TryParseExact قرارداد را دقیق می‌کند.

using System;

    internal static class Program
    {
        private static void Main()
        {
            string input = "{6f9619ff-8b86-d011-b42d-00c04fc964ff}";
            bool flexible = Guid.TryParse(input, out _);
            bool strict = Guid.TryParseExact(input, "D", out _);
            Console.WriteLine($"flexible={flexible}; strict={strict}");
        }
    }

انعطاف بیش از حد می‌تواند ناسازگاری تولیدکننده را پنهان کند. مرزهای عمومی را مستند و سخت‌گیرانه طراحی کنید.

مثال شماره 10: تبدیل Span در مسیر پرتکرار

بخشی از خط ورودی بدون ساخت رشته جدید به Guid.TryParse داده می‌شود.

using System;

    internal static class Program
    {
        private static void Main()
        {
            ReadOnlySpan<char> token = "7c9e6679-7425-40de-944b-e07fc1f90ae7".AsSpan();
            bool ok = Guid.TryParse(token, out Guid id);
            Console.WriteLine(ok ? id.ToString("D") : "نامعتبر");
        }
    }

در پردازش لاگ حجیم سودمند است؛ در فرم عادی، سادگی کد اولویت دارد.

خطاهای رایج و راه اصلاح

• استفاده از result بدون بررسی مقدار بازگشتی؛ اصلاح: منطق مصرف مقدار را داخل شاخه موفقیت قرار دهید.
• یکی گرفتن مقدار پیش‌فرض با شکست؛ اصلاح: وضعیت تبدیل را همراه مقدار نگه دارید یا Result صریح بسازید.
• اتکا به فرهنگ سرور؛ اصلاح: Culture و Style را از قرارداد داده تعیین کنید.
• پذیرش هر مقدار قابل تبدیل؛ اصلاح: پس از تبدیل، بازه، Allowlist و قواعد ارتباطی دامنه را بررسی کنید.
• حذف خاموش رکورد خراب در Import؛ اصلاح: شمارش و گزارش خطا را در خروجی فرایند قرار دهید.
• نادیده گرفتن نکته اختصاصی نوع؛ اصلاح: موفقیت نحوی به معنی مجاز بودن شناسه نیست؛ Guid.Empty و شناسه ناشناخته باید جداگانه کنترل شوند.

پیام خطا باید قابل اقدام باشد. به‌جای «ورودی نامعتبر است» می‌توان قالب مورد انتظار، محدوده مجاز و یک نمونه صحیح را ارائه کرد. بااین‌حال جزئیات داخلی، Stack Trace یا داده حساس نباید در پاسخ عمومی ظاهر شود.

کارایی، تخصیص حافظه و Best Practice

TryParse برای شکست قابل انتظار از الگوی Parse همراه try/catch مناسب‌تر است، زیرا استثنا برای کنترل جریان عادی طراحی نشده است. این حکم به معنی ممنوع بودن Parse نیست؛ اگر رشته یک ثابت داخلی معتبر است و خرابی آن باگ برنامه محسوب می‌شود، fail-fast با Parse می‌تواند انتخاب روشنی باشد.

overloadهای ReadOnlySpan در Parserهای پرتکرار امکان کار روی برشی از بافر را بدون ساخت substring می‌دهند. سود آن در فایل‌های بزرگ، پروتکل یا پردازش میلیون‌ها توکن بیشتر است. در فرم عادی، پیچیدگی اضافی ممکن است ارزش نداشته باشد؛ ابتدا CPU، Allocation و نرخ شکست را اندازه‌گیری کنید.

برای آزمون، حداقل حالت‌های معتبر، null، خالی، فاصله، Culture متفاوت، کمینه، بیشینه، خارج از محدوده و مقدار معتبر ولی غیرمجاز را پوشش دهید. تست‌ها باید Target Framework واقعی را اجرا کنند، زیرا برخی overloadها و رفتارهای گوشه‌ای میان نسخه‌های .NET تفاوت دارند.

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

پرسش 1: Guid.TryParse() دقیقاً چه مسئله‌ای را حل می‌کند؟

Guid.TryParse() متن را با قرارداد نوع مقصد بررسی می‌کند و بدون تبدیل شکست قابل انتظار به استثنا، وضعیت موفقیت را برمی‌گرداند. این ویژگی در ورودی کاربر، فایل، API و تنظیمات ارزشمند است. حوزه رایج این مقاله شناسه درخواست، کلید عمومی، Correlation ID و پیوند امن رکوردها است، اما اعتبار نحوی فقط نخستین مرحله است و قواعد دامنه باید جدا اعمال شوند.

پرسش 2: در صورت شکست Guid.TryParse() چه اتفاقی برای result می‌افتد؟

متد false برمی‌گرداند و result مقدار پیش‌فرض نوع را خواهد داشت یا نباید معتبر فرض شود. الگوی درست این است که result فقط در شاخه true مصرف شود. تکیه بر صفر، false، تاریخ کمینه یا Guid.Empty می‌تواند داده نامعتبر را با یک مقدار واقعی اشتباه بگیرد و خطای خاموش ایجاد کند.

پرسش 3: Culture چه اثری بر Guid.TryParse() دارد؟

اثر Culture به نوع بستگی دارد. اعداد اعشاری، جداکننده هزارگان و تاریخ به فرهنگ حساس‌اند، درحالی‌که Guid و bool قرارداد محدودتری دارند. در مرزهای ماشینی CultureInfo.InvariantCulture و قالب مستند، و در رابط کاربر فرهنگ انتخاب‌شده کاربر مناسب است. فرهنگ سرور نباید به‌طور تصادفی نتیجه را تعیین کند.

پرسش 4: چگونه Guid.TryParse() را در نرم‌افزار تجاری استفاده کنیم؟

یک لایه اعتبارسنجی بسازید که متن خام، نتیجه تبدیل، کد خطا و پیام قابل فهم را برگرداند. سپس قانون کسب‌وکار مربوط به شناسه درخواست، کلید عمومی، Correlation ID و پیوند امن رکوردها را اعمال کنید. این جداسازی هم تست‌پذیری را بالا می‌برد و هم امکان گزارش کیفیت داده، مشاوره فنی و توسعه سفارشی جریان Import را فراهم می‌کند.

پرسش 5: آیا جایگزینی بهتر از Guid.TryParse() وجود دارد؟

پاسخ به قرارداد ورودی وابسته است. برای قالب ثابت TryParseExact، برای داده‌ای که خرابی آن باگ است Parse، و برای تبدیل‌های سفارشی یک Value Object یا Parser دامنه‌ای مناسب‌تر است. هدف انتخاب کوتاه‌ترین کد نیست؛ باید خطا، Culture، سازگاری نسخه و پیام کاربر به‌روشنی مدیریت شود.

پرسش 6: برای پیاده‌سازی سازمانی Guid.TryParse() چه خدماتی لازم می‌شود؟

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

پرسش 7: خطای رایج هنگام کار با Guid.TryParse() چیست؟

رایج‌ترین خطا استفاده از result بدون بررسی مقدار بازگشتی است. خطاهای دیگر شامل اتکا به Culture جاری، نادیده گرفتن مرز نوع، یکی گرفتن اعتبار نحوی و معنایی و حذف خاموش رکورد نامعتبر است. نکته اختصاصی این موضوع نیز چنین است: موفقیت نحوی به معنی مجاز بودن شناسه نیست؛ Guid.Empty و شناسه ناشناخته باید جداگانه کنترل شوند.

پرسش 8: کارایی Guid.TryParse() در پردازش حجیم چگونه است؟

در شکست‌های قابل انتظار، TryParse معمولاً از کنترل جریان با exception مناسب‌تر است. overloadهای ReadOnlySpan می‌توانند تخصیص substring را کاهش دهند. بااین‌حال نتیجه به نسخه .NET، الگوی داده و مسیر اجرا وابسته است؛ پروفایلر و BenchmarkDotNet باید تصمیم را تأیید کنند و بهینه‌سازی زودهنگام نباید خوانایی را قربانی کند.

پرسش 9: بهترین روش طراحی با Guid.TryParse() چیست؟

قرارداد ورودی را مستند کنید، Culture و Style را در صورت نیاز صریح بدهید، result را فقط پس از true مصرف کنید، اعتبار دامنه را جدا بسنجید و خطا را با پیام قابل اقدام گزارش دهید. برای شناسه درخواست، کلید عمومی، Correlation ID و پیوند امن رکوردها آزمون‌های مرزی، null، مقدار نامعتبر، ورودی بسیار بزرگ و سناریوی واقعی کسب‌وکار را در مجموعه تست قرار دهید.

پرسش 10: Guid.TryParse() با کدام نسخه‌های C# و .NET سازگار است؟

overload پایه string در نسخه‌های قدیمی .NET نیز در دسترس است، اما overloadهای Span، UTF-8 و رابط‌های Generic Math در نسخه‌های جدیدتر افزوده شده‌اند. پروژه باید مستندات Target Framework خود را مبنا قرار دهد. اگر کتابخانه چندهدفه است، API سطح مشترک را انتخاب یا برای نسخه‌های جدید مسیر بهینه جدا تعریف کنید.

سؤالات مصاحبه C# و .NET

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

1. تفاوت قرارداد خطای Guid.TryParse() با Parse را توضیح دهید و برای هر کدام یک سناریو نام ببرید.
2. چرا بررسی مقدار بازگشتی قبل از result ضروری است و مقدار پیش‌فرض چه خطری دارد؟
3. اثر Culture، Style یا قالب ورودی بر Guid.TryParse() را با یک مثال تشریح کنید.
4. اعتبار نحوی و اعتبار کسب‌وکار در موضوع شناسه درخواست، کلید عمومی، Correlation ID و پیوند امن رکوردها چگونه از هم جدا می‌شوند؟
5. چه زمانی overload مبتنی بر ReadOnlySpan ارزشمند است و چگونه سود آن را اندازه می‌گیرید؟

چک‌لیست نهایی

• نوع مقصد و محدوده آن با دامنه واقعی داده سازگار است.
• Culture، Style یا قالب ثابت در مرز سیستم مشخص شده است.
• result فقط در مسیر موفقیت مصرف می‌شود.
• اعتبار نحوی از قواعد کسب‌وکار جداست.
• null، مقدار خالی، مرز و ورودی خراب تست شده‌اند.
• خطاها قابل پایش‌اند و داده حساس در لاگ قرار نمی‌گیرد.
• بهینه‌سازی Span تنها پس از اندازه‌گیری انجام شده است.

جمع‌بندی

Guid.TryParse() ابزار کوچکی برای ساخت مرز ورودی قابل اعتماد است. ارزش واقعی آن زمانی دیده می‌شود که قرارداد فرهنگ، محدوده، گزارش خطا و اعتبار دامنه پیرامونش درست طراحی شود. در شناسه درخواست، کلید عمومی، Correlation ID و پیوند امن رکوردها همین رویکرد از داده خاموش اشتباه، استثناهای پرتکرار و اختلاف رفتار محیط‌ها جلوگیری می‌کند.

برای مرور سایر نوع‌ها و انتخاب API مناسب، راهنمای جامع همه متدهای TryParse در C# و .NET را مطالعه کنید.