@nx-boat-tools/dotnet v0.1.0-alpha.2

Nx Boat Tools - .Net

The "net" in the Nx Boat Tools toolbox. The dotnet plugin adds .Net project support to Nx but aims to do so in a very dotnet CLI familiar way. Currently, Nx Boat Tools can be used to build, package, publish, and clean .Net web APIs, console applications, and class libraries. It can also be used to run .Net web APIs and console applications for testing.

• Why not use the community nx-dotnet plugin
• How to install
• Supported .Net Versions
• Executors
  • run-dotnet-command
  • build
  • clean
  • package
  • publish
  • run
  • test
  • version
• Generators
  • project
  • classlib
  • console
  • grpc
  • webapi
  • test
  • test-project
  • project-ref

Why not use the community nx-dotnet plugin?

The nx-dotnet plugin is a more mature plugin and definetly has its benefits. It supports test projects and specifying the language to use while Nx Boat Tools currently does not. It also supports any template type supported by the dotnet CLI but it does this by running dotnet new each time a project is created. Nx Boat Tools instead runs dotnet new as a base and can tweak and add onto the created files if needed. This files then get baked into a release to be used with the generators. We feel this is a better practice and also opens the door to some additional features we hope to add down the road.

💡  How to install

npm install -D @nx-boat-tools/dotnet

# OR

yarn add -D @nx-boat-tools/dotnet

🔖  Supported .Net Versions

The dotnet plugin currently generates projects using .Net 5.0. The dotnet executors use the .Net CLI and should work with any project using .NET Core 2.x or later.

🏃  Executors

run-dotnet-command

The run-dotnet-command is the heart of most of the dotnet executors and is meant to reflect the underlying dotnet CLI. Its job is to take in the various parameters, form the CLI command to run, and then execute it.

Available options:

Example:

Although the run-dotnet-command executor can be called directly, it's mostly intended to just be called from the other dotnet executors. Below is an example of this being done by the clean executor.

//executor.ts

export default async function runExecutor(
  options: CleanDotnetExecutorSchema,
  context: ExecutorContext
) {
  const dotnetOptions: DotNetCommandExecutorSchema = {
    ...options,
    action: 'clean',
  };

  await runDotnetCommand(dotnetOptions, context);

  return {
    success: true,
  };
}

build

The build executor reflects calling the dotnet build command with the dotnet CLI. It builds a dotnet project or solution and all its dependencies. See here for additional information on the underlying CLI command.

Available options:

Example:

The following workspace configuration illustrates a possible dotnet build target for a given project.

//workspace.json

{
  //...
  "projects": {
    "example": {
      //...
      "targets": {
        "build": {
          "executor": "@nx-boat-tools/dotnet:build",
          "options": {
            "srcPath": "apps/example/example.sln",
            "outputPath": "dist/apps/example",
            "configuration": "Debug"
          },
          "configurations": {
            "prod": {
              "configuration": "Release",
              "additionalArgs": "--nologo"
            }
          }
        }
      }
    }
  }
}

To build our dotnet project we just need to execute the build target...

nx build example
# OR
nx run example:build

Both of the above would run the following dotnet CLI command

dotnet build projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example

Here's another example but this time using a configuration...

nx run example:build:prod

Which would run the following dotnet CLI command

dotnet build projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example --configuration Release --nologo

clean

The clean executor reflects calling the dotnet clean command with the dotnet CLI. It cleans the output of a project or solution. See here for additional information on the underlying CLI command.

Available options:

Example:

The following workspace configuration illustrates a possible dotnet clean target for a given project.

//workspace.json

{
  //...
  "projects": {
    "example": {
      //...
      "targets": {
        "clean": {
          "executor": "@nx-boat-tools/dotnet:clean",
          "options": {
            "srcPath": "apps/example/example.sln",
            "outputPath": "dist/apps/example",
            "configuration": "Debug"
          },
          "configurations": {
            "prod": {
              "configuration": "Release",
              "additionalArgs": "--nologo"
            }
          }
        }
      }
    }
  }
}

To perform a clean on our dotnet project we just need to execute the clean target...

nx clean example
# OR
nx run example:clean

Both of the above would run the following dotnet CLI command

dotnet clean projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example

Here's another example but this time using a configuration...

nx run example:clean:prod

Which would run the following dotnet CLI command

dotnet clean projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example --configuration Release --nologo

package

The package executor reflects calling the dotnet pack command with the dotnet CLI. It packages the project or solution into a NuGet package. See here for additional information on the underlying CLI command.

🚩  Note:

The csproj file(s) will be updated to set the IsPackable property to true. This will allow all project types to be packaged and not just classlib projects.

Available options:

Example:

The following workspace configuration illustrates a possible dotnet package target for a given project.

//workspace.json

{
  //...
  "projects": {
    "example": {
      //...
      "targets": {
        "package": {
          "executor": "@nx-boat-tools/dotnet:package",
          "options": {
            "srcPath": "apps/example/example.sln",
            "outputPath": "dist/apps/example",
            "configuration": "Debug"
          },
          "configurations": {
            "prod": {
              "configuration": "Release",
              "additionalArgs": "--nologo"
            }
          }
        }
      }
    }
  }
}

To package our dotnet project into a NuGet package we just need to execute the package target...

nx package example
# OR
nx run example:package

Both of the above would run the following dotnet CLI command

dotnet package projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example

Here's another example but this time using a configuration...

nx run example:package:prod

Which would run the following dotnet CLI command

dotnet package projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example --configuration Release --nologo

publish

The publish executor reflects calling the dotnet publish command with the dotnet CLI. It publishes the project and its dependencies to a folder for deployment. See here for additional information on the underlying CLI command.

Available options:

Example:

The following workspace configuration illustrates a possible dotnet publish target for a given project.

//workspace.json

{
  //...
  "projects": {
    "example": {
      //...
      "targets": {
        "publish": {
          "executor": "@nx-boat-tools/dotnet:publish",
          "options": {
            "srcPath": "apps/example/example.sln",
            "outputPath": "dist/apps/example",
            "configuration": "Debug"
          },
          "configurations": {
            "prod": {
              "configuration": "Release",
              "additionalArgs": "--nologo"
            }
          }
        }
      }
    }
  }
}

To get the dotnet project ready for deployment we just need to execute the publish target...

nx publish example
# OR
nx run example:publish

Both of the above would run the following dotnet CLI command

dotnet publish projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example

Here's another example but this time using a configuration...

nx run example:publish:prod

Which would run the following dotnet CLI command

dotnet publish projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example --configuration Release --nologo

run

The run executor reflects calling the dotnet run command with the dotnet CLI. It runs a project without doing any compliling, etc. See here for additional information on the underlying CLI command.

Available options:

Example:

The following workspace configuration illustrates a possible dotnet run target for a given project.

//workspace.json

{
  //...
  "projects": {
    "example": {
      //...
      "targets": {
        "runSrc": {
          "executor": "@nx-boat-tools/dotnet:run",
          "options": {
            "srcPath": "apps/example/example.sln",
            "outputPath": "dist/apps/example",
            "configuration": "Debug"
          },
          "configurations": {
            "prod": {
              "configuration": "Release",
              "additionalArgs": "--nologo"
            }
          }
        }
      }
    }
  }
}

To run our dotnet project we just need to execute the runSrc target...

nx runSrc example
# OR
nx run example:runSrc

Both of the above would run the following dotnet CLI command

dotnet run projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example

Here's another example but this time using a configuration...

nx run example:runSrc:prod

Which would run the following dotnet CLI command

dotnet run projectRoot/apps/example/example.sln --output projectRoot/dist/apps/example --configuration Release --nologo

test

The test executor is a utility function that updates the versions in all csproj files associaciated with the project to match the version specified in the project's package.json

Available options:

Example:

The following workspace configuration illustrates a possible dotnet test target for a given project.

//workspace.json

{
  //...
  "projects": {
    "example": {
      //...
      "targets": {
        "testSrc": {
          "executor": "@nx-boat-tools/dotnet:test",
          "options": {
            "srcPath": "apps/example/tests/Example.Tests/Example.Tests.csproj",
            "outputPath": "dist/apps/example",
            "configuration": "Debug"
          },
          "configurations": {
            "prod": {
              "configuration": "Release"
            }
          }
        }
      }
    }
  }
}

To test our dotnet project we just need to execute the testSrc target...

nx test example
# OR
nx run example:test

Both of the above would run the following dotnet CLI command

dotnet test projectRoot/apps/example/tests/Example.Tests/Example.Tests.csproj --output projectRoot/dist/apps/example --results-directory projectRoot/coverage/apps/example --collector "XPlat Code Coverage" --configuration Debug

Here's another example but this time using the prod configuration...

nx run example:test:prod

Which would run the following dotnet CLI command

dotnet test projectRoot/apps/example/tests/Example.Tests/Example.Tests.csproj --output projectRoot/dist/apps/example --results-directory projectRoot/coverage/apps/example --collector "XPlat Code Coverage" --configuration Release

version

The version executor is a utility function that updates the versions in all csproj files associaciated with the project to match the version specified in the project's package.json

Available options:

Example:

The following workspace configuration illustrates a possible dotnet run target for a given project.

//workspace.json

{
  //...
  "projects": {
    "example": {
      //...
      "targets": {
        "dotnetVersion": {
          "executor": "@nx-boat-tools/dotnet:version",
          "options": {
            "srcPath": "apps/example/example.sln"
          }
        }
      }
    }
  }
}

✍️  Generators

project

The project generator is the heart of all of the dotnet generators. Its job is to take in the various parameters, create the project files based on the corresponding template, and add the project to the workspace.json will all the appropriate dotnet targets for the dotnet project type.

Available options:

Generated files:

What files are generated depend on the projectType that's specified but should mostly reflect the same files you'd get from running dotnet new {projectType}. Other than the addition of a package.json file for the project, the biggest difference is whether or not the solution file is created or if another one is appended to.

Updates to project configuration:

The project is added to the project configuration with the following high-level targets defined:

• build - This runs the dotnet build executor for the project
• dotnetVersion - This runs the version executor to ensure the csproj versions match the project's package.json
• package - This runs the dotnet package executor
• clean - this calls the dotnet clean executor to clean up build output
• run - this calls the dotnet run target to run the application
• version - This updates the project version utilizing the @jscutlery/semver community plugin. The dotnetVersion is added to the postTargets parameter so the csproj files are updated at the same time.

🚩  Note: The run target is not added when classlib is specified for projectType

The following is a full example of what's added to the project configuration for a dotnet project, in this case for a projectType of console:

//workspace.json

{
  //...
  "projects": {
    "console-app": {
      "root": "apps/console-app",
      "projectType": "application",
      "sourceRoot": "apps/console-app/src",
      "targets": {
        "build": {
          "executor": "@nx-boat-tools/dotnet:build",
          "options": {
            "srcPath": "./workspace-name.sln",
            "outputPath": "dist/apps/console-app",
            "configuration": "Debug"
          },
          "configurations": {
            "dev": {},
            "prod": {}
          }
        },
        "clean": {
          "executor": "@nx-boat-tools/dotnet:clean",
          "options": {
            "srcPath": "./workspace-name.sln",
            "outputPath": "dist/apps/console-app",
            "configuration": "Debug"
          },
          "configurations": {
            "dev": {},
            "prod": {}
          }
        },
        "dotnetVersion": {
          "executor": "@nx-boat-tools/dotnet:version",
          "options": {
            "srcPath": "./workspace-name.sln"
          },
          "configurations": {
            "dev": {},
            "prod": {}
          }
        },
        "package": {
          "executor": "@nx-boat-tools/dotnet:package",
          "options": {
            "srcPath": "./workspace-name.sln",
            "outputPath": "dist/apps/console-app",
            "configuration": "Debug"
          },
          "configurations": {
            "dev": {},
            "prod": {}
          }
        },
        "run": {
          "executor": "@nx-boat-tools/dotnet:run",
          "options": {
            "srcPath": "./workspace-name.sln",
            "outputPath": "dist/apps/console-app",
            "configuration": "Debug"
          },
          "configurations": {
            "dev": {},
            "prod": {}
          }
        },
        "version": {
          "executor": "@@jscutlery/semver:version",
          "options": {
            "commitMessageFormat": "chore(${projectName}): release version ${version}",
            "postTargets": ["dotnetVersion"]
          }
        }
      },
      "tags": ""
    }
  }
}

classlib

Creates a dotnet class library project.

Available options:

Generated files:

Other than the addition of a package.json file for the project, the generated files should mostly reflect the same files you'd get from running dotnet new classlib. The biggest difference is whether or not the solution file is created or if another one is appended to. The project directory for classlib projects will be under the libs folder in the workspace.

Creating a classlib project

The following illustrates how to add a dotnet classlib project with various options:

#Create a project named my-classlib in libs/my-classlib and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:classlib my-classlib

#Create a project named my-classlib in libs/my-classlib with the solution at libs/my-classlib/MyClasslib.sln
nx g @nx-dev-tools/dotnet:classlib my-classlib --ownSolution=true

#Create a project named my-classlib in libs/internal/my-classlib and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:classlib my-classlib --directory=internal

console

Creates a dotnet console application project.

Available options:

Generated files:

Other than the addition of a package.json file for the project, the generated files should mostly reflect the same files you'd get from running dotnet new console. The biggest difference is whether or not the solution file is created or if another one is appended to. The project directory for console projects will be under the apps folder in the workspace.

Creating a console project

The following illustrates how to add a dotnet console project with various options:

#Create a project named my-console-app in apps/my-console-app and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:console my-console-app

#Create a project named my-console-app in apps/my-console-app with the solution at apps/my-console-app/MyConsoleApp.sln
nx g @nx-dev-tools/dotnet:console my-console-app --ownSolution=true

#Create a project named my-console-app in apps/internal/my-console-app and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:console my-console-app --directory=internal

grpc

Creates a dotnet grpc application project.

Available options:

Generated files:

Other than the addition of a package.json file for the project, the generated files should mostly reflect the same files you'd get from running dotnet new grpc. The biggest difference is whether or not the solution file is created or if another one is appended to. The project directory for grpc projects will be under the apps folder in the workspace.

Creating a grpc project

The following illustrates how to add a dotnet grpc project with various options:

#Create a project named my-grpc-app in apps/my-grpc-app and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:grpc my-grpc-app

#Create a project named my-grpc-app in apps/my-grpc-app with the solution at apps/my-grpc-app/MyGrpcApp.sln
nx g @nx-dev-tools/dotnet:grpc my-grpc-app --ownSolution=true

#Create a project named my-grpc-app in apps/internal/my-grpc-app and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:grpc my-grpc-app --directory=internal

webapi

Creates a dotnet web API project.

Available options:

Generated files:

Other than the addition of a package.json file for the project, the generated files should mostly reflect the same files you'd get from running dotnet new webapi. The biggest difference is whether or not the solution file is created or if another one is appended to. The project directory for webapi projects will be under the apps folder in the workspace.

Creating a webapi project

The following illustrates how to add a dotnet webapi project with various options:

#Create a project named my-api in apps/my-api and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:webapi my-api

#Create a project named my-api in apps/my-api with the solution at apps/my-api/MyApi.sln
nx g @nx-dev-tools/dotnet:webapi my-api --ownSolution=true

#Create a project named my-api in apps/internal/my-api and adds it to the workspace.sln
nx g @nx-dev-tools/dotnet:webapi my-api --directory=internal

test

Adds a dotnet test project to an existing Nx project. The type of test project can be mstest, nunit, or xunit and is specified by the testType option which corresponds to test template values used in the dotnet new command.

Available options:

Generated files:

The generated files should mostly reflect the same files you'd get from running dotnet new mstest, dotnet new nunit, or dotnet new xunit respectively. The project will be created in a tests directory within the project's root, for example: apps/my-project/tests.

Updates to project configuration:

The project's entry in the project configuration will be updated as follows:

• test - This calls a chain-execute with the a target for the test being added. The target name depends on if the testPrefix option was specified. If it was, then the target name is test plus the prefix in camel-casing. For example, given a prefix of integration, the target name would be testIntegration. If the testPrefix option was not specified, the target name will be testSrc.

The following is a full example of what's added to the project configuration when adding dotnet tests:

//workspace.json

{
  //...
  "projects": {
    "my-app": {
      "root": "apps/my-app",
      "projectType": "application",
      "sourceRoot": "apps/my-app/src",
      "targets": {
        "test": {
          "executor": "@nx-boat-tools/common:chain-execute",
          "options": {
            "targets": ["testUnit", "testIntegration"]
          }
        },
        "testIntegration": {
          "executor": "@nx-boat-tools/dotnet:test",
          "options": {
            "srcPath": "apps/my-app/tests/MyApp.IntegrationTests/MyApp.IntegrationTests.csproj",
            "outputPath": "dist/apps/my-app"
          }
        },
        "testUnit": {
          "executor": "@nx-boat-tools/dotnet:test",
          "options": {
            "srcPath": "apps/my-app/tests/MyApp.UnitTests/MyApp.UnitTests.csproj",
            "outputPath": "dist/apps/my-app"
          }
        },
        "version": {
          "executor": "@@jscutlery/semver:version",
          "options": {
            "commitMessageFormat": "chore(${projectName}): release version ${version}"
          }
        }
      },
      "tags": ""
    }
  }
}

Creating a test project

The following illustrates how to add a dotnet test project with various options:

#Add a dotnet mstest project to the Nx my-api project
nx g @nx-dev-tools/dotnet:test my-api

#Add a dotnet mstest project to the Nx my-api project with a test prefix
nx g @nx-dev-tools/dotnet:test my-api --testPrefix=acceptance

#Add a dotnet 7.0 xunit project to the Nx my-api project with a test prefix
nx g @nx-dev-tools/dotnet:test my-api --testType=xunit --testPrefix=acceptance --frameworkVersion=latest

test-project

Creates an Nx project specifically for a dotnet test project. The type of test project can be mstest, nunit, or xunit and is specified by the testType option which corresponds to test template values used in the dotnet new command.

Available options:

Generated files:

Other than the addition of a package.json file for the project, the generated files should mostly reflect the same files you'd get from running dotnet new mstest, dotnet new nunit, or dotnet new xunit respectively. The dotnet project will be created in a tests directory within the project's root, for example: apps/my-project/tests.

Updates to project configuration:

The project is added to the project configuration with the following high-level targets defined:

• test - This calls a chain-execute with the a target for the test being added. The target name depends on if the testPrefix option was specified. If it was, then the target name is test plus the prefix in camel-casing. For example, given a prefix of integration, the target name would be testIntegration. If the testPrefix option was not specified, the target name will be testSrc.

• version - This updates the project version utilizing the @jscutlery/semver community plugin.

The following is a full example of what's added to the project configuration when adding a dotnet test project:

//workspace.json

{
  //...
  "projects": {
    "my-app": {
      "root": "apps/my-app",
      "projectType": "application",
      "sourceRoot": "apps/my-app/src",
      "targets": {
        "test": {
          "executor": "@nx-boat-tools/common:chain-execute",
          "options": {
            "targets": ["testUnit", "testIntegration"]
          }
        },
        "testIntegration": {
          "executor": "@nx-boat-tools/dotnet:test",
          "options": {
            "srcPath": "apps/my-app/tests/MyApp.IntegrationTests/MyApp.IntegrationTests.csproj",
            "outputPath": "dist/apps/my-app"
          }
        },
        "testUnit": {
          "executor": "@nx-boat-tools/dotnet:test",
          "options": {
            "srcPath": "apps/my-app/tests/MyApp.UnitTests/MyApp.UnitTests.csproj",
            "outputPath": "dist/apps/my-app"
          }
        },
        "version": {
          "executor": "@@jscutlery/semver:version",
          "options": {
            "commitMessageFormat": "chore(${projectName}): release version ${version}"
          }
        }
      },
      "tags": ""
    }
  }
}

Creating a test-project project

The following illustrates how to add a dotnet test-project project with various options:

#Create a dotnet mstest project
nx g @nx-dev-tools/dotnet:test-project my-api

#Create a dotnet mstest project with a test prefix
nx g @nx-dev-tools/dotnet:test-project my-api --testPrefix=acceptance

#Create a dotnet 7.0 xunit project with a test prefix
nx g @nx-dev-tools/dotnet:test-project my-api --testType=xunit --testPrefix=acceptance --frameworkVersion=latest

project-ref

The project-ref generator adds a dotnet project reference from one existing Nx dotnet project to another.

Available options:

Generated files:

The csproj file of the target project (the one where the reference will be added) will be updated to contain a ProjectReference to the csproj file of the refence project. If a package.json exits for both Nx projects, a dependency will be added to the target project's package.json and will point to the version specified in the reference project's package.json.

🚩  Note: Projects with their own solution file are not currently supported. Both the target and reference projects must utilize the root solution file.

Updates to project configuration:

The project-ref generator does not affect project configuration.

Creating a test-project project

The following illustrates how to add a dotnet test-project project with various options:

#Adds a project reference from the project named my-project to the project named some-lib
nx g @nx-dev-tools/dotnet:project-ref --project=my-project --reference=some-lib