Read this article in your language IT | EN | DE | ES

Покращення повідомлень про помилки хоста .NET і можливості підтримки

Ви коли-небудь намагалися запустити програму .NET і бачили повідомлення про помилку про те, що вам не вистачає середовища виконання, як-от нижче? Ви коли-небудь засмучувалися повідомленням про те, що вам не вистачає SDK, але ви не знаєте, чому? У рамках .NET 7 Preview 6 ми оновили кілька повідомлень про помилки та команд як dotnet --info, щоб надати більше корисної інформації.

Як команда .NET, нас часто просять про допомогу. Можливість підтримки важлива для нас, оскільки вона допомагає заощадити час і швидко допомагає розробникам, операторам і кінцевим користувачам вирішити проблему. Ми прагнемо, щоб помилки були достатньо інформативними, щоб багато користувачів могли самостійно діагностувати свої проблеми, навіть нетехнічні користувачі. Ми також хочемо, щоб незалежні постачальники програмного забезпечення (ISV) могли легко підтримувати своїх користувачів. Значною частиною цього є те, що повідомлення про помилки стають більш інформативними, але не ускладнюються. Давайте подивимося, що ми зробили для покращення .NET 7.

Ця публікація була написана командою .NET Host. Я розміщую цю публікацію на хостингу, а також є членом команди хостингу. Сподіваюся, я хороший хост.

Контекст

.NET — це розміщена платформа середовища виконання. Це означає, що кожна програма .NET запускається власним хостом, якому потрібно знайти та завантажити сумісне середовище виконання .NET для виконання коду програми. Іноді середовище виконання не може бути знайдено, і хост повинен надати повідомлення про помилку з деталями помилки та інструкціями, що робити.

Значна частина цієї публікації стосується лише програм, що залежать від фреймворку . Це стандартний варіант створення та публікації. Залежні від фреймворку програми (на відміну від автономних програм) не включають середовище виконання, але їх потрібно завантажувати (зазвичай) із глобального місця встановлення. Ось що веде до всієї цієї теми. Залежні від фреймворку програми мають багато переваг, тому ця модель популярна.

Деякі повідомлення про помилки містять посилання на різні сторінки завантаження на веб-сайті .NET . Ці посилання цілодобово отримують великий трафік. Це говорить про те, що це важливий досвід, у який ми повинні інвестувати більше. І ми це робимо. У нас є подібний досвід для .NET Framework, який існує протягом тривалого часу.

Відсутній час виконання

Ситуація, коли не вдається знайти потрібне середовище виконання .NET, є важливим сценарієм як для кінцевих користувачів, так і для розробників. У помилках ми намагалися знайти баланс між простотою для кінцевих користувачів і деталями для розробників. Щоб дати змогу кінцевим користувачам краще вирішувати власні проблеми, ми зосередилися на тому, щоб повідомлення про помилки були зрозумілими та відповідними. Ми оновили форматування для покращення читабельності, видалили непотрібну інформацію та додали посилання для завантаження та документації. Щоб дозволити розробникам краще підтримувати своїх кінцевих користувачів, ми додали більше інформації до повідомлень про помилки, наприклад про архітектуру та місце розташування .NET.

Ми оновили наші повідомлення про помилки, щоб мати загальну структуру:

Неможливість знайти потрібне середовище виконання .NET може означати, що .NET взагалі не інстальовано, версія фреймворка (наприклад, ASP.NET Core або Windows Desktop) не інстальована, необхідна архітектура не інстальована або вона не відповідає очікуваному місцезнаходженню. Ми розглянемо досвід кожного з них.

Ми також перенесли ці оновлення до .NET 6.0.7. Досвід із відсутнім середовищем виконання є важливим, і ми вважаємо, що було б корисно як для кінцевих користувачів, так і для розробників, щоб ці покращення були в нашому останньому випуску LTS .

Інсталяція .NET не знайдена

Кінцеві користувачі, які вперше запускають програму .NET, можуть не мати встановленої версії .NET. У цьому випадку ми хочемо сказати користувачеві, що йому потрібно інсталювати .NET, і направити його на відповідну сторінку завантаження.

Якщо .NET взагалі не інстальовано, запущена програма .NET 7 покаже:

У наведеному вище повідомленні зазначено, що потрібна інсталяція .NET і є окремий розділ для виділення важливої ​​інформації, як-от архітектура та версія хосту додатка. Він також містить посилання на документацію з більш детальною інформацією та надає посилання для завантаження, за яким користувач може перейти, щоб вирішити проблему. Хоча ми очікуємо, що більшість користувачів можуть вирішити свою проблему за допомогою посилання для завантаження, додаткова інформація дозволить отримати кращу підтримку, якщо користувачеві потрібна додаткова допомога.

Для додатків графічного інтерфейсу користувача Windows ми внесли подібні зміни до показаної помилки, включивши посилання на документацію та більш чітке викладення відповідної інформації:

Ці зміни покращують попередню поведінку:

Потрібний фреймворк не знайдено

Ще один поширений сценарій для кінцевого користувача — це запуск програми, для якої потрібен фреймворк, який не інстальовано, або необхідна версія цього фреймворку не інстальована. У цьому випадку ми хочемо повідомити користувачеві, що йому потрібно встановити певний фреймворк для .NET, і направити його на відповідну сторінку завантаження.

Запуск програми покаже:

У повідомленні є окремий розділ для важливої ​​інформації, як-от ім’я (Microsoft.AspNetCore.App), версія (7.0.0-preview.4.22251.1) та архітектура (x64) відсутнього фреймворку та розташування, де він знаходиться очікується встановлення. Подібно до помилки, коли .NET взагалі не інстальовано, тут є посилання на документацію та посилання для завантаження, щоб користувач міг вирішити проблему. Знову ж таки, ми прагнемо, щоб більшість користувачів могли вирішити проблему за допомогою посилання для завантаження, але намагаємось включити більш детальну інформацію щодо можливості підтримки.

Для програм графічного інтерфейсу Windows ми знову внесли подібні зміни до показаної помилки:

Так само, як у випадку, коли .NET взагалі не інстальовано, додається посилання на документацію та чітко викладена відповідна інформація.

Ці зміни покращують попередню поведінку:

Архітектура

Ви також можете зіткнутися з проблемами під час роботи програми, якщо не встановлено середовище виконання .NET відповідної архітектури. Наприклад, ми часто спостерігаємо це під час запуску програми x64 на машині macOS або Windows Arm64, де встановлено середовище виконання Arm64 .NET, але не x64, або запуск програми x86 на машині Windows x64, де встановлено середовище виконання x64 .NET встановлено, але не x86.

Це проявляється як відсутність інсталяції .NET або відсутність необхідного фреймворку залежно від того, чи є інсталяція відповідної архітектури. Щоб допомогти розв'язувати проблеми, пов’язані з різними архітектурами, повідомлення тепер показує архітектуру, наприклад:

Загалом ми переконалися, що всі повідомлення про помилки про відсутність середовища виконання вказують на відповідну архітектуру, щоб усім було зрозуміліше – кінцевому користувачеві, розробнику чи розробнику, який підтримує кінцевого користувача – яка архітектура потрібна.

Ми внесли кардинальні зміни в те, як .NET використовує PATH для операційних систем, які підтримують емульовані архітектури (у .NET Core 3.1, .NET 6 і .NET 7). Встановлення .NET оновлюватиме лише змінну середовища PATH для рідної архітектури операційної системи. Наприклад, встановлення x86 (32-розрядної версії) не оновлюватиме файл PATH, якщо встановлено на 64-розрядній машині. Попередня поведінка (стоовно оновлення PATH інсталяцій .NET із емульованою та рідною архітектурою) спричинила значну плутанину клієнтів і поломку продукту. Проблема полягає в тому, що поведінка старої схеми не завжди була передбачуваною. Нова схема на 100% передбачувана та надійна. Ми внесли ті самі зміни в .NET для x64 в операційних системах Arm64 .

Розташування .NET

Власний хост для програми .NET шукає середовище виконання .NET на основі змінних середовища, файлів конфігурації (в Unix) або ключів реєстру (в Windows) і добре відомих розташувань за замовчуванням. Можливо, у вас справді встановлено потрібне середовище виконання .NET, але не в місці, визначеному програмою. Щоб полегшити визначення, коли ви можете опинитися в такій ситуації, ми додали до повідомлень про помилки розташування .NET, яке використовує хост. Наприклад, повідомлення про відсутню необхідну структуру показує щось на зразок:

Це дає вам змогу точно знати, де необхідно встановити необхідний фреймворк для успішного запуску програми. Це також дозволяє перевірити, чи знайдене розташування .NET відповідає вашим очікуванням. Якщо ви хочете використати інше розташування, ви можете використати змінні середовища або реєстрацію, описану в пошуку розташування встановлення , щоб змінити розташування .NET.

У .NET 7 ми також вимкнули багаторівневий пошук лише для Windows (див. сповіщення про критичні зміни ). Це означає, що хост програми .NET більше не шукає фреймворки в кількох місцях. Наприклад, якщо необхідний фреймворк встановлено у глобально зареєстрованому розташуванні, але змінна середовища DOTNET_ROOT налаштована на встановлення без цього фреймворку, інсталяція, що відповідає значенню DOTNET_ROOT, вважатиметься розташуванням .NET, і ви отримаєте повідомлення про помилку повідомлення про те, що необхідну структуру не знайдено в цьому місці.

Відсутній SDK

Для розробників .NET запуск команд .NET SDK є початковою точкою для будь-якої розробки. За замовчуванням використовується останній встановлений SDK, але конкретну версію можна налаштувати за допомогою файлу global.json . У .NET 7, якщо ви спробуєте запустити команду SDK, але не маєте встановленої версії, указаної у файлі global.json, ви побачите помилку, подібну до:

У цьому випадку хост не може визначити, чи ви намагаєтесь запустити програму чи команду SDK, тому він пропонує обидві можливості, перш ніж включити подробиці про невдачу знайти сумісний SDK та інструкції щодо вирішення проблеми. Він також містить посилання на додаткові відомості про те, як вибирається версія SDK.

Ми вважаємо, що формулювання та макет полегшують перегляд відповідних деталей, порівняно з попередньою поведінкою:

Це оновлення для роботи з відсутнім SDK також було перенесено до .NET 6.0.7. Ми сподіваємося, що новий досвід полегшить розблокування під час розробки.

Рідний хост також надає API для роздільної здатності SDK, який використовується для вирішення MSBuild SDK . У .NET 7 ми оновили цей API, щоб надати більше інформації, наприклад запитану версію SDK. Ми плануємо використати цю інформацію для надання кращого повідомлення про помилку , якщо не вдасться вирішити SDK у таких сценаріях.

dotnet --info

Команда dotnet --info виводить інформацію про інсталяцію .NET і середовище, в якому вона запущена. Це корисно для самодіагностики проблем і для надання інформації під час запиту підтримки.

У .NET 7 ми оновили результат, щоб він виглядав так:

Відповідно до оновлених повідомлень про помилки ми очистили макет, видалили непотрібний текст і додали посилання на документацію. Ми також включили архітектуру хоста та будь-який файл global.json, який використовувався для вирішення SDK.

Як згадувалося раніше, ми спостерігали плутанину через різні архітектури або розташування .NET . Щоб допомогти з розумінням таких проблем, ми оновили dotnet --info, щоб перерахувати інсталяції інших архітектур, включаючи їх розташування та, якщо це можливо, спосіб їх реєстрації, а також будь-які змінні середовища DOTNET_ROOT, які впливають на те, як рідний хост виглядає для середовища виконання .NET.

Це був попередній результат:

Повідомлення про помилки SDK

Ми виявили деякі повідомлення про помилку SDK, які посилаються на global.json, але не вказують його розташування. Це може дуже засмучувати . Ми сподіваємося покращити цей досвід у пізнішому Прев’ю.

Значок dotnet

У відповідь на чудову пропозицію спільноти ми також додали піктограму до виконуваного файлу dotnet в Windows. Замість значка програми Windows за замовчуванням тепер ви побачите:

Веб-сайт

Веб -сайт .NET є метою для посилань для завантаження. Посилання містять невеликі фрагменти інформації, наприклад, яка потрібна архітектура та версія .NET. Наразі веб-сайт спрямовує користувача на сторінку для певної версії, як для .NET 7. Однак користувачеві потрібно вибирати між кількома завантаженнями.

Надалі ми плануємо оновити веб-сайт, щоб за цими посиланнями пропонувалося одне завантаження. Він має відповідати операційній системі, архітектурі та версії .NET запиту. Таким чином, усі користувачі (технічні чи нетехнічні) матимуть простий досвід «натисни та зайди», не потребуючи жодних спеціальних знань.

Висновки

Ми доклали значних зусиль, щоб покращити зручність використання та підтримку всіх цих «екранів» з помилками та інформацією. Ми повинні підтримувати наш продукт на регулярній основі, і ми вважаємо, що додаткова інформація буде дуже корисною для нас. Сподіваємося, що це стане в нагоді вам, незалежно від того, чи ви розробник, спеціаліст із операцій чи кінцевий користувач.

Зрештою, ви просто хочете інсталювати .NET, щоб можна було запускати програму або займатися розробкою. Ми сподіваємося, що ми зробили цей процес трохи швидшим і простішим.

Source