Skip to content

Latest commit

 

History

History
157 lines (99 loc) · 7.59 KB

getting-and-building-the-code.md

File metadata and controls

157 lines (99 loc) · 7.59 KB
Raw

Main branch

The following instructions are for current main branch only.

Prerequisites

EF Core does not generally need any prerequisites installed to build the code. However, running tests requires certain local databases to be available:

  • The SQL Server tests require a local SQL Server installation. This can be:
    • SQL Server LocalDb, usually obtained by installing the latest Visual Studio 2019 public preview with the "ASP.NET and web development" workload selected.
    • SQL Server Express or Developer Edition. When not using LocalDb, make sure to set the environment variable Test__SqlServer__DefaultConnection to the connection string that EF Core tests should use.
  • The Cosmos tests require that the Azure Cosmos Emulator is installed. Use the default installation options. Make sure to re-start the emulator each time you restart your machine.
    • The Cosmos tests are optional and will be skipped if the emulator is not available. If you are not making Cosmos changes, then you may choose to skip installing the emulator and let the continuous integration system handle Cosmos testing.
    • Tip: Turn off "Rate Limiting" in the emulator to make the Cosmos tests run faster.

Switch off Cosmos Rate Limiting

Fork the repository

If you plan to contribute changes back to EF Core, then first create a fork of the EFCore repo on GitHub.

Clone the repository

Using your favorite git client, clone the repository. For example, to clone the main repo:

git clone https://github.com/dotnet/efcore.git

Or if you have created a fork called efcore in your personal GitHub:

git clone https://github.com/myusername/efcore.git

Build

To build the code just call build[.cmd/.sh]. This is an important step since it will install a preview .NET SDK alongside EF Core. This ensures EF Core is being built with the expected SDK and msbuild version. Running build also restores packages and builds all projects. Tests are not run.

build

The build script has different arguments to perform specific actions. The full list of arguments can be found via build -h command. Arguments for common actions are listed in table below. The repository root directory also contains cmd/sh files to invoke some of them directly.

build argument action script file
-restore Restore packages. restore.cmd
-build Build all projects. build.cmd
-test Build and run all tests. test.cmd
-pack Build and produce NuGet packages. None

Using Visual Studio

The command line build (see above) must be run before using the solution with Visual Studio.

The build script installs a preview .NET Core SDK. In order to make sure Visual studio (or any other IDE) is using same SDK, certain environment variables need to be set. To configure your local environment and open solution file in Visual Studio, run following command:

startvs.cmd EFCore.slnf

You can inspect the script and use similar configuration for other IDEs.

Note that startvs actually opens whatever the default application is for .sln files. If you have multiple IDEs or multiple versions of Visual Studio installed, then make sure that the appropriate default is set, or edit the script to be explicit.

Run tests

Our tests are written using xUnit.net, and can be run with most test runners we have tried. Tests can be run on the command line (after build) by running test:

test

Solving common build errors

  1. Check that the package source URLs listed in the Nuget.config file in the root of the repository are accessible.
  2. Clean the source directory. git clean -xid will clean files in the EF source directory.
  3. Clear nuget packages and caches. nuget.exe locals all -clear will delete the NuGet caches. (You can get nuget.exe from https://dist.nuget.org/index.html or use dotnet nuget).

Earlier versions (2.x or older)

Prerequisites

The following prerequisites are required to work with the EF Core code:

Clone the repository

Using your favorite git client, clone the repository.

git clone https://github.com/dotnet/efcore.git

Build initialization

Run at least the following before using Visual Studio for the first time:

build /t:Compile

If you get a ⚠️ warning about KoreBuild using different dotnet than the one which exists in PATH variable, then you need to update your PATH variable such that dotnet installed by KoreBuild in %USERPROFILE% appears before any other dotnet installed. Only after that opening solution in Visual Studio will work correctly. See Updating PATH to use preview .NET Core SDK under Build from Visual Studio for more information on steps.

Build from the command line

To build and run tests:

build

To build and create packages without running tests:

build /t:Package

Build from Visual Studio

  • Just open the .sln file. (After running the build initialization from the command line and updating your Path if needed.)
  • NuGet packages will already have been restored, so you can switch off auto package restore in Visual Studio.

Updating PATH to use preview .NET Core SDK

  • Since KoreBuild installs preview version of .NET Core SDK in %USERPROFILE% folder, your path needs to use that dotnet for VS to work correctly. Especially the preview version of dotnet should appear before any other dotnet in your PATH variable. You can either set your environment variables globally and just open solution in VS normally or you can set PATH variable locally in command line and open solution from command line.

Following are steps to update PATH locally & open solution in VS in PowerShell. Similar steps can be used in any other command terminal. (drop /x64 if you are on 32 bit machine)

.\build /t:Compile
$env:PATH="$env:USERPROFILE/.dotnet/x64;"+$env:PATH
.\EFCore.sln

Solving common build errors

  1. Check that the package source URLs listed in the Nuget.config file in the root of the repository are accessible.
  2. Clean the source directory. git clean -xid will clean files in the EF source directory.
  3. Clear nuget packages and caches. nuget.exe locals all -clear will delete the NuGet caches. (You can get nuget.exe from https://dist.nuget.org/index.html or use dotnet nuget).
  4. Reinstall .NET Core CLI. Our build script automatically installs a version to %USERPROFILE%\.dotnet.

Run tests

Our tests are written using xUnit.net 2.0, and can be run with TestDriven.Net. You may need to tweak the TestDriven.NET installation to get it working with the latest VS.

Other test runners may also work--people have had luck with the ReSharper test runner and the CodeRush runner.

ReSharper

Some people on the team use ReSharper to increase productivity. Currently the EAP builds of the latest release seem to be working well. Some people see better performance if ReSharper testing support is disabled.