Microsoft.Diagnostics.NETCore.Client API

  • 아티클

이 섹션에서는 진단 클라이언트 라이브러리의 API에 대해 설명합니다.

DiagnosticsClient 클래스

public DiagnosticsClient
{
    public DiagnosticsClient(int processId);

    public EventPipeSession StartEventPipeSession(
        IEnumerable<EventPipeProvider> providers,
        bool requestRundown = true,
        int circularBufferMB = 256);

    public Task<EventPipeSession> StartEventPipeSessionAsync(
        IEnumerable<EventPipeProvider> providers,
        bool requestRundown,
        int circularBufferMB = 256,
        CancellationToken token = default);

    public void WriteDump(
        DumpType dumpType,
        string dumpPath,
        bool logDumpGeneration = false);

    public async Task WriteDumpAsync(
        DumpType dumpType,
        string dumpPath,
        bool logDumpGeneration,
        CancellationToken token);

    public void AttachProfiler(
        TimeSpan attachTimeout,
        Guid profilerGuid,
        string profilerPath,
        byte[] additionalData = null);

    public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

    public void ResumeRuntime();

    public void SetEnvironmentVariable(
        string name,
        string value);

    public Dictionary<string, string> GetProcessEnvironment();

    public static IEnumerable<int> GetPublishedProcesses();
}

생성자

public DiagnosticsClient(int processId);

processId의 프로세스 ID로 실행되는 호환되는 .NET 프로세스에 대한 DiagnosticsClient의 새 인스턴스를 만듭니다.

processID: 대상 애플리케이션의 프로세스 ID입니다.

StartEventPipeSession 메서드

public EventPipeSession StartEventPipeSession(
    IEnumerable<EventPipeProvider> providers,
    bool requestRundown = true,
    int circularBufferMB = 256);
public Task<EventPipeSession> StartEventPipeSessionAsync(
    IEnumerable<EventPipeProvider> providers,
    bool requestRundown,
    int circularBufferMB = 256,
    CancellationToken token = default);

지정된 공급자 및 설정을 사용하여 EventPipe 추적 세션을 시작합니다.

  • providers: 추적을 시작할 EventPipeProvider의 IEnumerable입니다.
  • requestRundown: 대상 앱의 런타임에서 런다운 공급자 이벤트를 요청할지 여부를 지정하는 bool입니다.
  • circularBufferMB: 이벤트 수집 시 대상 앱의 런타임에서 사용하는 순환 버퍼의 총 크기를 지정하는 int입니다.
  • token(비동기 오버로드): 취소 요청을 모니터링할 토큰입니다.
public EventPipeSession StartEventPipeSession(EventPipeProvider provider, bool requestRundown = true, int circularBufferMB = 256)
public Task<EventPipeSession> StartEventPipeSessionAsync(EventPipeProvider provider, bool requestRundown, int circularBufferMB = 256, CancellationToken token = default)
  • provider: 추적을 시작할 EventPipeProvider입니다.
  • requestRundown: 대상 앱의 런타임에서 런다운 공급자 이벤트를 요청할지 여부를 지정하는 bool입니다.
  • circularBufferMB: 이벤트 수집 시 대상 앱의 런타임에서 사용하는 순환 버퍼의 총 크기를 지정하는 int입니다.
  • token(비동기 오버로드): 취소 요청을 모니터링할 토큰입니다.

참고 항목

런다운 이벤트에는 스레드 샘플의 메서드 이름 확인과 같이 사후 분석에 필요할 수 있는 페이로드가 포함됩니다. 이를 원하지 않는 경우가 아니라면 requestRundown을 true로 설정하는 것이 좋습니다. 대규모 애플리케이션에서는 시간이 걸릴 수 있습니다.

WriteDump 메서드

public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration=false);

대상 애플리케이션의 사후 평가 디버깅을 위해 덤프를 요청합니다. 덤프의 형식은 DumpType 열거형을 사용하여 지정할 수 있습니다.

  • dumpType: 요청할 덤프의 유형입니다.
  • dumpPath: 쓸 덤프의 경로입니다.
  • logDumpGeneration: true로 설정하면 대상 애플리케이션이 덤프 생성 중에 진단 로그를 기록합니다.
public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

대상 애플리케이션의 사후 평가 디버깅을 위해 덤프를 요청합니다. 덤프의 형식은 DumpType 열거형을 사용하여 지정할 수 있습니다.

  • dumpType: 요청할 덤프의 유형입니다.
  • dumpPath: 쓸 덤프의 경로입니다.
  • flags: 로깅 및 크래시 보고서 플래그입니다. 6.0 미만의 런타임에서는 LoggingEnabled만 지원됩니다.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

대상 애플리케이션의 사후 평가 디버깅을 위해 덤프를 요청합니다. 덤프의 형식은 DumpType 열거형을 사용하여 지정할 수 있습니다.

  • dumpType: 요청할 덤프의 유형입니다.
  • dumpPath: 쓸 덤프의 경로입니다.
  • logDumpGeneration: true로 설정하면 대상 애플리케이션이 덤프 생성 중에 진단 로그를 기록합니다.
  • token: 취소 요청을 모니터링할 토큰입니다.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

대상 애플리케이션의 사후 평가 디버깅을 위해 덤프를 요청합니다. 덤프의 형식은 DumpType 열거형을 사용하여 지정할 수 있습니다.

  • dumpType: 요청할 덤프의 유형입니다.
  • dumpPath: 쓸 덤프의 경로입니다.
  • flags: 로깅 및 크래시 보고서 플래그입니다. 6.0 미만의 런타임에서는 LoggingEnabled만 지원됩니다.
  • token: 취소 요청을 모니터링할 토큰입니다.

AttachProfiler 메서드

public void AttachProfiler(
    TimeSpan attachTimeout,
    Guid profilerGuid,
    string profilerPath,
    byte[] additionalData=null);

ICorProfiler를 대상 애플리케이션에 연결하도록 요청합니다.

  • attachTimeout: 이후에 연결이 중단되는 TimeSpan입니다.
  • profilerGuid: 연결할 ICorProfiler의 Guid입니다.
  • profilerPath: 연결할 ICorProfiler dll에 대한 경로입니다.
  • additionalData: 프로파일러를 연결하는 동안 런타임에 전달할 수 있는 선택적 추가 데이터입니다.

SetStartupProfiler 메서드

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

프로파일러를 시작 프로파일러로 설정합니다. 시작 시 런타임이 일시 중지된 동안에만 이 명령을 실행할 수 있습니다.

  • profilerGuid: 연결할 프로파일러의 경우 Guid입니다.
  • profilerPath: 연결할 프로파일러의 경로입니다.

ResumeRuntime 메서드

public void ResumeRuntime();

시작 시 일시 중지된 후 실행을 다시 시작하도록 런타임에 지시합니다.

SetEnvironmentVariable 메서드

public void SetEnvironmentVariable(
    string name,
    string value);

대상 프로세스에 환경 변수를 설정합니다.

  • name설정할 환경 변수의 이름입니다.
  • value: 설정할 환경 변수의 값입니다.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

대상 프로세스에서 모든 환경 변수와 해당 값을 가져옵니다.

GetPublishedProcesses 메서드

public static IEnumerable<int> GetPublishedProcesses();

연결할 수 있는 모든 활성 .NET 프로세스의 프로세스 ID의 IEnumerable을 얻습니다.

EventPipeProvider 클래스

public class EventPipeProvider
{
    public EventPipeProvider(
        string name,
        EventLevel eventLevel,
        long keywords = 0,
        IDictionary<string, string> arguments = null)

    public string Name { get; }

    public EventLevel EventLevel { get; }

    public long Keywords { get; }

    public IDictionary<string, string> Arguments { get; }

    public override string ToString();

    public override bool Equals(object obj);

    public override int GetHashCode();

    public static bool operator ==(Provider left, Provider right);

    public static bool operator !=(Provider left, Provider right);
}

생성자

public EventPipeProvider(
    string name,
    EventLevel eventLevel,
    long keywords = 0,
    IDictionary<string, string> arguments = null)

지정된 공급자 이름, EventLevel, 키워드 및 인수를 가진 EventPipeProvider의 새 인스턴스를 만듭니다.

Name 속성

public string Name { get; }

공급자의 이름을 가져옵니다.

EventLevel 속성

public EventLevel EventLevel { get; }

지정된 EventPipeProvider의 인스턴스에 대한 EventLevel을 가져옵니다.

Keywords 속성

public long Keywords { get; }

EventSource의 키워드에 대한 비트맵을 나타내는 값을 가져옵니다.

Arguments 속성

public IDictionary<string, string> Arguments { get; }

지정된 EventPipeProvider를 나타내는 EventSource에 전달될 선택적 인수를 나타내는 키-값 쌍 문자열의 IDictionary를 가져옵니다.

설명

.NET Core 3.1에서 EventPipe는 EventPipe 세션 중에 공급자의 구성을 수정할 수 없으므로 이 클래스는 변경이 불가능합니다.

EventPipeSession 클래스

public class EventPipeSession : IDisposable
{
    public Stream EventStream { get; }
    public void Stop();
}

이 클래스는 진행 중인 EventPipe 세션을 나타냅니다. 이는 변경이 불가능하며 지정된 런타임의 EventPipe 세션에 대한 핸들 역할을 합니다.

EventStream 속성

public Stream EventStream { get; }

이벤트 스트림을 읽는 데 사용할 수 있는 Stream을 가져옵니다.

Stop 메서드

public void Stop();

지정된 EventPipe 세션을 중지합니다.

DumpType 열거형

public enum DumpType
{
    Normal = 1,
    WithHeap = 2,
    Triage = 3,
    Full = 4
}

요청할 수 있는 덤프 유형을 나타냅니다.

  • Normal: 프로세스의 모든 기존 스레드에 대한 모든 기존 추적의 스택 추적을 캡처하는 데 필요한 정보만 포함합니다. 제한된 GC 힙 메모리 및 정보입니다.
  • WithHeap: 프로세스의 모든 기존 스레드에 대한 스택 추적을 캡처하는 데 필요한 GC 힙 및 정보를 포함합니다.
  • Triage: 프로세스의 모든 기존 스레드에 대한 모든 기존 추적의 스택 추적을 캡처하는 데 필요한 정보만 포함합니다. 제한된 GC 힙 메모리 및 정보입니다.
  • Full: 프로세스에서 액세스할 수 있는 모든 메모리를 포함합니다. 원시 메모리 데이터는 끝에 포함되므로 원시 메모리 정보 없이 초기 구조를 직접 매핑할 수 있습니다. 이 옵션을 선택하면 매우 큰 덤프 파일이 생성될 수 있습니다.

예외

라이브러리에서 throw되는 예외는 형식 DiagnosticsClientException 또는 파생 형식입니다.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

라이브러리 또는 대상 프로세스의 런타임에서 명령이 지원되지 않는 경우 throw될 수 있습니다.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

대상 프로세스의 런타임이 라이브러리에서 사용하는 진단 IPC 프로토콜과 호환되지 않는 경우 throw될 수 있습니다.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

런타임 시작 시 진단 명령에 대해 런타임이 준비되기 전이나 런타임이 종료될 때와 같이 진단 IPC 명령에 런타임을 사용할 수 없는 경우 throw될 수 있습니다.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

런타임이 지정된 명령에 대한 오류로 응답할 때 throw될 수 있습니다.