Microsoft.Testing.Platform Services

Testovací platforma nabízí cenné služby pro testovací architekturu i body rozšíření. Tyto služby zajišťují běžné potřeby, jako je přístup ke konfiguraci, analýza a načítání argumentů příkazového řádku, získání objektu pro vytváření protokolování a přístup k systému protokolování mimo jiné. IServiceProvider implementuje vzor lokátoru služby pro testovací platformu.

IServiceProvider je odvozena přímo z knihovny základních tříd.

namespace System
{
    public interface IServiceProvider
    {
        object? GetService(Type serviceType);
    }
}

Testovací platforma nabízí užitečné rozšiřující metody pro přístup k dobře známým objektům služby. Všechny tyto metody jsou umístěny ve statické třídě v rámci oboru názvů Microsoft.Testing.Platform.Services.

public static class ServiceProviderExtensions
{
    public static TService GetRequiredService<TService>(
        this IServiceProvider provider)

    public static TService? GetService<TService>(
        this IServiceProvider provider)

    public static IMessageBus GetMessageBus(
        this IServiceProvider serviceProvider)

    public static IConfiguration GetConfiguration(
        this IServiceProvider serviceProvider)

    public static ICommandLineOptions GetCommandLineOptions(
        this IServiceProvider serviceProvider)

    public static ILoggerFactory GetLoggerFactory(
        this IServiceProvider serviceProvider)

    public static IOutputDevice GetOutputDevice(
        this IServiceProvider serviceProvider)

    // ... and more
}

Většina registračních továren vystavených body rozšíření poskytuje přístup k IServiceProvider: Například při registrování testovacího frameworku se IServiceProvider předává jako parametr metodě továrny.

ITestApplicationBuilder RegisterTestFramework(
    Func<IServiceProvider, ITestFrameworkCapabilities> capabilitiesFactory,
    Func<ITestFrameworkCapabilities, IServiceProvider, ITestFramework> adapterFactory);

V předchozím kódu oba capabilitiesFactory a adapterFactory dodávají IServiceProvider jako parametr.

Služba `IConfiguration`

Rozhraní IConfiguration lze načíst pomocí IServiceProvider a poskytuje přístup k nastavení konfigurace pro testovací rámec a všechny body rozšíření. Ve výchozím nastavení se tyto konfigurace načítají z:

Proměnné prostředí
Soubor JSON s názvem [assemblyName].testingplatformconfig.json umístěný poblíž sestavení vstupního bodu.

Pořadí priority je zachováno, což znamená, že pokud se v proměnných prostředí najde konfigurace, soubor JSON se nezpracuje.

Rozhraní je jednoduchá dvojice řetězců klíč-hodnota:

public interface IConfiguration
{
    string? this[string key] { get; }
}

Konfigurační soubor JSON

Soubor JSON se řídí hierarchickou strukturou. Pro přístup k podřízeným vlastnostem musíte použít oddělovač :. Představte si například konfiguraci pro potenciální testovací architekturu, například:

{
  "CustomTestingFramework": {
    "DisableParallelism": true
  }
}

Fragment kódu by vypadal přibližně takto:

IServiceProvider serviceProvider = null; // Get the service provider...

var configuration = serviceProvider.GetConfiguration();

if (bool.TryParse(configuration["CustomTestingFramework:DisableParallelism"], out var value) && value is true)
{
    // ...
}

V případě pole, jako například:

{
  "CustomTestingFramework": {
    "Engine": [
      "ThreadPool",
      "CustomThread"
    ]
  }
}

Syntax pro přístup k prvnímu prvku ("ThreadPool") je:

IServiceProvider serviceProvider = null; // Get the service provider...

var configuration = serviceProvider.GetConfiguration();

var fistElement = configuration["CustomTestingFramework:Engine:0"];

Proměnné prostředí

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. __je dvojité podtržítko:

Podporováno všemi platformami. Například : oddělovač není podporován Bash, ale __ je.
Automaticky nahrazeno :

Proměnnou prostředí můžete například nastavit následujícím způsobem (Tento příklad platí pro Windows):

setx CustomTestingFramework__DisableParallelism=True

Při vytváření ITestApplicationBuilderse můžete rozhodnout, že nebudete používat zdroj konfigurace proměnné prostředí:

var options = new TestApplicationOptions();

options.Configuration.ConfigurationSources.RegisterEnvironmentVariablesConfigurationSource = false;

var builder = await TestApplication.CreateBuilderAsync(args, options);

Služba `ICommandLineOptions`

Služba ICommandLineOptions se využívá k načtení podrobností o možnostech příkazového řádku, které platforma parsovala. Dostupná rozhraní API zahrnují:

public interface ICommandLineOptions
{
    bool IsOptionSet(string optionName);

    bool TryGetOptionArgumentList(
        string optionName, 
        out string[]? arguments);
}

ICommandLineOptions lze získat prostřednictvím určitých rozhraní API, jako je ICommandLineOptionsProvider, nebo můžete načíst jeho instanci z IServiceProvider prostřednictvím rozšiřující metody serviceProvider.GetCommandLineOptions().

ICommandLineOptions.IsOptionSet(string optionName): Tato metoda umožňuje ověřit, zda byla zadána konkrétní možnost. Při zadávání optionNamevynecháte předponu --. Pokud například uživatel zadá --myOption, měli byste jednoduše použít myOption.

ICommandLineOptions.TryGetOptionArgumentList(string optionName, out string[]? arguments): Tato metoda vám umožňuje zkontrolovat, zda byla nastavena konkrétní volba, a pokud ano, získat odpovídající hodnotu nebo hodnoty (pokud je počet argumentů více než jeden). Podobně jako v předchozím případě by se optionName měla poskytnout bez předpony --.

Služba `ILoggerFactory`

Testovací platforma se dodává s integrovaným systémem protokolování, který generuje soubor protokolu. Možnosti protokolování můžete zobrazit spuštěním příkazu --help. Mezi možnosti, které si můžete vybrat, patří:

--diagnostic                             Enable the diagnostic logging. The default log level is 'Trace'. The file will be written in the output directory with the name log_[MMddHHssfff].diag
--diagnostic-synchronous-write Force the built-in file logger to write the log synchronously. Useful for scenario where you don't want to lose any log (i.e. in case of crash). Note that this is slowing down the test execution.
--diagnostic-output-directory            Output directory of the diagnostic logging, if not specified the file will be generated inside the default 'TestResults' directory.
--diagnostic-file-prefix           Prefix for the log file name that will replace '[log]_.'
--diagnostic-verbosity                   Define the level of the verbosity for the --diagnostic. The available values are 'Trace', 'Debug', 'Information', 'Warning', 'Error', and 'Critical'

Z hlediska kódování, pro záznam informací potřebujete získat ILoggerFactory z IServiceProvider. Rozhraní API ILoggerFactory je následující:

public interface ILoggerFactory
{
    ILogger CreateLogger(string categoryName);
}

public static class LoggerFactoryExtensions
{
    public static ILogger<TCategoryName> CreateLogger<TCategoryName>(this ILoggerFactory factory);
}

Továrna na zapisovače vám umožňuje vytvořit objekt ILogger pomocí rozhraní API CreateLogger. K dispozici je také pohodlné rozhraní API, které přijímá obecný argument, který se použije jako název kategorie.

public interface ILogger
{
    Task LogAsync<TState>(
        LogLevel logLevel, 
        TState state, 
        Exception? exception, 
        Func<TState, Exception?, string> formatter);

    void Log<TState>(
        LogLevel logLevel,
        TState state, 
        Exception? exception, 
        Func<TState, Exception?, string> formatter);

    bool IsEnabled(LogLevel logLevel);
}

public interface ILogger<out TCategoryName> : ILogger
{
}

public static class LoggingExtensions
{
    public static Task LogCriticalAsync(this ILogger logger, string message);
    public static Task LogDebugAsync(this ILogger logger, string message);
    public static Task LogErrorAsync(this ILogger logger, Exception ex);
    public static Task LogErrorAsync(this ILogger logger, string message, Exception ex);
    public static Task LogErrorAsync(this ILogger logger, string message);
    public static Task LogInformationAsync(this ILogger logger, string message);
    public static Task LogTraceAsync(this ILogger logger, string message);
    public static Task LogWarningAsync(this ILogger logger, string message);
    public static void LogCritical(this ILogger logger, string message);
    public static void LogDebug(this ILogger logger, string message);
    public static void LogError(this ILogger logger, Exception ex);
    public static void LogError(this ILogger logger, string message, Exception ex);
    public static void LogError(this ILogger logger, string message);
    public static void LogInformation(this ILogger logger, string message);
    public static void LogTrace(this ILogger logger, string message);
    public static void LogWarning(this ILogger logger, string message);
}

Objekt ILogger vytvořený ILoggerFactorynabízí rozhraní API pro protokolování informací na různých úrovních. Mezi tyto úrovně protokolování patří:

public enum LogLevel
{
    Trace,
    Debug,
    Information,
    Warning,
    Error,
    Critical,
    None,
}

Tady je příklad použití rozhraní API protokolování:

...
IServiceProvider provider = null; // Get the service provider...

var factory = provider.GetLoggerFactory();

var logger = factory.CreateLogger<TestingFramework>();

// ...

if (logger.IsEnabled(LogLevel.Information))
{
    await logger.LogInformationAsync(
        $"Executing request of type '{context.Request}'");
}

// ...

Mějte na paměti, že pokud chcete zabránit zbytečnému přidělení, měli byste zkontrolovat, jestli je úroveň povolená pomocí rozhraní API ILogger.IsEnabled(LogLevel).

Služba `IMessageBus`

Služba Message Bus je centrální mechanismus, který usnadňuje výměnu informací mezi testovacím rámcem a jeho rozšířeními.

Sběrnice zpráv testovací platformy využívá vzor publikování a odběru.

Celková struktura sdílené sběrnice je následující:

Jak je znázorněno v diagramu, který zahrnuje rozšíření a testovací prostředí, existují dvě možné akce: odesílání informací do sběrnice nebo využívání informací ze sběrnice.

IMessageBus splněný s přenesením akce do sběrnice a rozhraní API:

public interface IMessageBus
{
    Task PublishAsync(
        IDataProducer dataProducer, 
        IData data);
}

public interface IDataProducer : IExtension
{
    Type[] DataTypesProduced { get; }
}

public interface IData
{
    string DisplayName { get; }
    string? Description { get; }
}

Zvažte následující podrobnosti o parametrech:

IDataProducer: IDataProducer sděluje sběrnici zpráv, jaké Type informací může poskytnout, a stanovuje vlastnictví prostřednictvím dědičnosti ze základního rozhraní IExtension. To znamená, že nemůžete náhodně posílat data do zprávového sběrnice; musíte předem deklarovat datový typ, který vyprodukujete. Pokud odešlete neočekávaná data, aktivuje se výjimka.
IData: Toto rozhraní slouží jako zástupný symbol, kde potřebujete zadat pouze popisné podrobnosti, jako je název a popis. Rozhraní nezojevuje mnoho informací o povaze dat, což je záměrné. Z toho vyplývá, že testovací architektura a rozšíření mohou do sběrnice odesílat libovolný typ dat a tato data mohou být využita libovolným registrovaným rozšířením nebo samotnou testovací architekturou.

Tento přístup usnadňuje evoluci procesu výměny informací, což brání narušení změn, pokud rozšíření nezná nová data. Umožňuje, aby různé verze rozšíření a testovací architektura fungovaly v harmonii na základě jejich vzájemného porozumění.

Opačný konec sběrnice se označuje jako consumer, který se přihlásí k odběru určitého typu dat a může je tak využívat.

Důležitý

Vždy používejte await pro volání PublishAsync. Pokud tak neučiníte, IData nemusí být správně zpracována testovací platformou a rozšířeními, což může vést k jemným chybám. Je to teprve poté, co se vrátíte z čekají, že můžete mít jistotu, že IData byla zařazena do fronty pro zpracování ve sběrnici zpráv. Bez ohledu na bod rozšíření, na kterém pracujete, se ujistěte, že jste před ukončením rozšíření počkal/a na všechna volání PublishAsync. Pokud například implementujete testing framework, neměli byste volat Complete na požadavky, dokud nečekáte na všechna volání PublishAsync pro tento konkrétní požadavek.

Služba `IOutputDevice`

Testovací platforma zapouzdřuje myšlenku výstupního zařízení, což umožňuje testovacímu rámci a jeho rozšířením prezentovat informace tím, že přenáší jakýkoli druh dat do aktuálně využívaného zobrazovacího systému.

Nejtradičnější příklad výstupního zařízení je výstup konzole.

Poznámka

Zatímco testovací platforma je navržena tak, aby podporovala vlastní výstupní zařízení, v současné době není tento bod rozšíření k dispozici.

Chcete-li přenést data do výstupního zařízení, musíte získat IOutputDevice z IServiceProvider.

Rozhraní API se skládá z:

public interface IOutputDevice
{
    Task DisplayAsync(
        IOutputDeviceDataProducer producer, 
        IOutputDeviceData data);
}

public interface IOutputDeviceDataProducer : IExtension
{
}

public interface IOutputDeviceData
{
}

IOutputDeviceDataProducer rozšiřuje IExtension a poskytuje informace o odesílateli do výstupního zařízení.

IOutputDeviceData slouží jako zástupné rozhraní. Koncept IOutputDevice spočívá ve zpřístupnění složitějších informací než jen barevného textu. Může to být například složitý objekt, který může být graficky reprezentován.

Testovací platforma ve výchozím nastavení nabízí tradiční barevný textový model pro objekt IOutputDeviceData:

public class TextOutputDeviceData : IOutputDeviceData
{
    public TextOutputDeviceData(string text)
    public string Text { get; }
}

public sealed class FormattedTextOutputDeviceData : TextOutputDeviceData
{
    public FormattedTextOutputDeviceData(string text)
    public IColor? ForegroundColor { get; init; }
    public IColor? BackgroundColor { get; init; }
}

public sealed class SystemConsoleColor : IColor
{
    public ConsoleColor ConsoleColor { get; init; }
}

Tady je příklad, jak použít barevný text s aktivním výstupním zařízením .

IServiceProvider provider = null; // Get the service provider...

var outputDevice = provider.GetOutputDevice();

await outputDevice.DisplayAsync(
    this, 
    new FormattedTextOutputDeviceData($"TestingFramework version '{Version}' running tests with parallelism of {_dopValue}")
    {
        ForegroundColor = new SystemConsoleColor
        {
            ConsoleColor = ConsoleColor.Green
        }
    });

Kromě standardního použití barevného textu je hlavní výhodou IOutputDevice a IOutputDeviceData, že výstupní zařízení je pro uživatele zcela nezávislé a neznámé. To umožňuje vývoj složitých uživatelských rozhraní. Je například zcela možné implementovat webové aplikace v reálném čase, která zobrazuje průběh testů.

Služba `IPlatformInformation`

Poskytuje informace o platformě, jako je název, verze, hodnota hash potvrzení a datum sestavení.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-03-11

Sdílet prostřednictvím

Microsoft.Testing.Platform Services

Služba IConfiguration

Konfigurační soubor JSON

Proměnné prostředí

Služba ICommandLineOptions

Služba ILoggerFactory

Služba IMessageBus

Služba IOutputDevice

Služba IPlatformInformation