This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
We welcome 3rd party pull requests. For significant changes we strongly recommend opening an issue to start a design discussion first.
- Use Windows PowerShell or PowerShell Core (including on Linux/OSX) to run .ps1 scripts. Some scripts set environment variables to help you, but they are only retained if you use PowerShell as your shell.
- .NET Core SDK with the version matching our global.json file. The version you install must be at least the version specified in the global.json file, and must be within the same hundreds version for the 3rd integer: x.y.Czz (x.y.C must match, and zz must be at least as high).
The easiest way to get this is to run the
initscript at the root of the repo. Use the-InstallLocality Machineand approve admin elevation if you wish so the SDK is always discoverable from VS. See theinitscript usage doc for more details. - Optional: Visual Studio 2019
The only prerequisite for building, testing, and deploying from this repository
is the .NET SDK.
You should install the version specified in global.json or a later version within
the same major.minor.Bxx "hundreds" band.
For example if 2.2.300 is specified, you may install 2.2.300, 2.2.301, or 2.2.310
while the 2.2.400 version would not be considered compatible by .NET SDK.
See .NET Core Versioning for more information.
The easiest way to restore packages may be to run init.ps1 which automatically authenticates
to the feeds that packages for this repo come from, if any.
dotnet restore or nuget restore also work but may require extra steps to authenticate to any applicable feeds.
This project can be built with the follow commands from a Visual Studio Developer Command Prompt, assuming the working directory is the root of this repository:
msbuild srcUse nbgv tag to create a tag for a particular commit that you mean to release.
Learn more about nbgv and its tag and prepare-release commands.
Push the tag.
When your repo is hosted by GitHub and you are using GitHub Actions, you should create a GitHub Release using the standard GitHub UI.
Having previously used nbgv tag and pushing the tag will help you identify the precise commit and name to use for this release.
After publishing the release, the .github\workflows\release.yml workflow will be automatically triggered, which will:
- Find the most recent
.github\workflows\build.ymlGitHub workflow run of the tagged release. - Upload the
deployablesartifact from that workflow run to your GitHub Release. - If you have
NUGET_API_KEYdefined as a secret variable for your repo or org, any nuget packages in thedeployablesartifact will be pushed to nuget.org.
When your repo builds with Azure Pipelines, use the azure-pipelines/release.yml pipeline.
Trigger the pipeline by adding the auto-release tag on a run of your main azure-pipelines.yml pipeline.
API and hand-written docs are found under the docfx/ directory. and are built by docfx.
You can make changes and host the site locally to preview them by switching to that directory and running the dotnet docfx --serve command.
After making a change, you can rebuild the docs site while the localhost server is running by running dotnet docfx again from a separate terminal.
The .github/workflows/docs.yml GitHub Actions workflow publishes the content of these docs to github.io if the workflow itself and GitHub Pages is enabled for your repository.
This repo uses Renovate to keep dependencies current.
Configuration is in the .github/renovate.json file.
Learn more about configuring Renovate.
When changing the renovate.json file, follow these validation steps.
If Renovate is not creating pull requests when you expect it to, check that the Renovate GitHub App is configured for your account or repo.