{"id":28961724,"url":"https://github.com/getappmap/appmap-dotnet","last_synced_at":"2025-06-24T02:04:46.006Z","repository":{"id":52755595,"uuid":"335719336","full_name":"getappmap/appmap-dotnet","owner":"getappmap","description":"Records the execution of .NET programs, to create scenarios in AppMap files","archived":false,"fork":false,"pushed_at":"2024-07-25T12:40:47.000Z","size":504,"stargazers_count":11,"open_issues_count":16,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-11T14:18:18.162Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getappmap.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-03T18:34:40.000Z","updated_at":"2024-07-25T12:40:27.000Z","dependencies_parsed_at":"2022-08-22T19:01:20.749Z","dependency_job_id":null,"html_url":"https://github.com/getappmap/appmap-dotnet","commit_stats":null,"previous_names":["applandinc/appmap-dotnet"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/getappmap/appmap-dotnet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Fappmap-dotnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Fappmap-dotnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Fappmap-dotnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Fappmap-dotnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getappmap","download_url":"https://codeload.github.com/getappmap/appmap-dotnet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Fappmap-dotnet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261589911,"owners_count":23181437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-24T02:04:45.253Z","updated_at":"2025-06-24T02:04:45.960Z","avatar_url":"https://github.com/getappmap.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AppMap-dotnet\n\nAppMap-dotnet records the execution of .NET code. Note currently only Linux is supported.\n\n## Usage\n\nA launcher, provided as a `dotnet` tool, is provided for ease of use;\nit automatically configures the runtime environment as explained below.\n\nSee details below or just dive in:\n```sh-session\n$ dotnet tool install -g appland.appmap\n$ cd ~/projects/myproject\n$ echo \"packages: [ class: MyProject ]\" \u003e appmap.yml\n$ APPMAP_OUTPUT_PATH=/dev/stdout dotnet appmap exec bin/myproject.dll\n$ dotnet appmap test\n```\n\nNote it currently requires libxml2 and libunwind8, you might need to install these two. If libraries are missing it will silently fail to work.\n\n### Details\n\nYou need [CLR Instrumentation Engine](https://github.com/microsoft/CLRInstrumentationEngine/)\nbinary, [config/ProductionBreakpoints_x64.config](config/ProductionBreakpoints_x64.config) and the built binary from this project.\nPut all three files, `libInstrumentationEngine.so`, `ProductionBreakpoints_x64.config` and `libappmap-instrumentation.so` in the same\ndirectory. Set the environment variables (replace `opt/appmap-dotnet` with the path to the files):\n```\nCORECLR_PROFILER={324F817A-7420-4E6D-B3C1-143FBED6D855}\nCORECLR_PROFILER_PATH_64=opt/appmap-dotnet/libInstrumentationEngine.so\nCORECLR_PROFILER_PATH=opt/appmap-dotnet/libInstrumentationEngine.so\nMicrosoftInstrumentationEngine_LogLevel=Error\nCORECLR_ENABLE_PROFILING=1\nMicrosoftInstrumentationEngine_DisableCodeSignatureValidation=1\nMicrosoftInstrumentationEngine_FileLogPath=/dev/stderr\nMicrosoftInstrumentationEngine_ConfigPath64_TestMethod=opt/appmap-dotnet/ProductionBreakpoints_x64.config\n```\n\nFor convenience a launcher is provided that sets it all up.\n\n## VSTest integration\n\nWhen the instrumentation is loaded, VSTest tests are automatically detected and\nthe runs recorded. The appmaps are written to `$APPMAP_OUTPUT_DIR`.\n\nWhen using XUnit, test parallelization is disabled; otherwise the test code\ninterleaves and the appmap make no sense.\n\n## Configuration\n\n### Configuration file\n\nAppmap-dotnet instruments only specific code packages; which are these can be configured by\ncreating an `appmap.yml` file in the project root directory, for example:\n\n```yaml\nname: my-project\npackages:\n- class: MyProject.UtilityClass\n  exclude: Helper  # this excludes MyProject.UtilityClass.Helper\n- module: MyProject.Business.dll\n- path: /usr/lib/util\n```\n\nThe path to the file can be explicitly set in `APPMAP_CONFIG` environment variable. Otherwise, appmap-dotnet\nsearches current directory (or `APPMAP_BASEPATH` if set) and all its ancestors for `appmap.yml`.\nRelative `path` entries are resolved in `APPMAP_BASEPATH` or the directory where `appmap.yml` was found.\n\n### Environment variables\n\n#### `APPMAP_BASEPATH`\n\nBase path; this is where the search for the config file begins and where relative `path` packages are resolved.\nDefaults to where the config file was found, or the current directory.\n\n#### `APPMAP_CONFIG`\n\nFile path. Allows using a specific config file. By default, `appmap.yml` is searched in the current\ndirectory and its ancestors.\n\n#### `APPMAP_LIST_MODULES`\n\nFile path. If set, the list of all module names seen is printed there on shutdown.\nOn Linux, you can use `/dev/stdout` or `/dev/stderr` to dump it to console.\n\n#### `APPMAP_OUTPUT_DIR`\n\nWhen instrumenting unit tests, appmaps are written to this directory. Defaults to\n`$APPMAP_BASEPATH/tmp/appmap`.\n\n#### `APPMAP_OUTPUT_PATH`\n\nFile path. If set, an appmap encompassing the whole execution is saved there on shutdown.\n\n#### `APPMAP_LOG_LEVEL`\n\nLog level, one of `trace`, `debug`, `info`, `warning`, `error`, `critical`, `off`.\nDefaults to `info`.\n\n### `APPMAP_RUNTIME_DIR`\n\nUsed by the launcher; directory containing `libappmap-instrumentation.so`\nand `libInstrumentationEngine.so`. When installed as a tool, the launcher automatically\nfinds the packaged binaries. This variable is convenient when developing, so\nthat the launcher picks up the locally compiled libraries.\n\n## Building\n\nThe repository is pretty self-contained and should build on any Linux with modern cmake and C++ compiler.\n\nYou can use `scripts/docker-build.sh` to build both CLRIE and this instrumentation method in Docker.\nOn success, `out` directory will contain all the files needed to use this instrumentation method.\n\n`launcher` requires dotnet SDK to build; `dotnet pack` in that directory will build the nuget package,\nincluding the native binaries placed in `bin/linux-x64`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetappmap%2Fappmap-dotnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetappmap%2Fappmap-dotnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetappmap%2Fappmap-dotnet/lists"}