feat(core): support for workspace solution files (#254)

Author: AgentEnder

.vscode/extensions.json

@@ -1,6 +1,5 @@
 {
   "recommendations": [
-    "ms-vscode.vscode-typescript-tslint-plugin",
     "esbenp.prettier-vscode",
     "firsttris.vscode-jest-runner",
     "mike-co.import-sorter"

apps/docs-site/docusaurus.config.js

@@ -85,6 +85,9 @@ module.exports = {
       contextualSearch: false,
       appId: 'BH4D9OD16A',
     },
+    prism: {
+      additionalLanguages: ['json5', 'typescript', 'bash'],
+    },
   },
   presets: [
     [

apps/docs-site/project.json

@@ -9,6 +9,12 @@
         "outputPath": "dist/apps/docs-site"
       }
     },
+    "prebuild": {
+      "executor": "@nrwl/workspace:run-commands",
+      "options": {
+        "commands": ["echo"]
+      }
+    },
     "serve": {
       "executor": "@nx-plus/docusaurus:dev-server",
       "options": {

docs/core/generators/application.md

@@ -37,3 +37,9 @@ Generate a dotnet project under the application directory.
 ### standalone
 
 - (boolean): Should the project use project.json? If false, the project config is inside workspace.json
+
+### solutionFile
+
+- (string): The name of the solution file to add the project to
+
+- (boolean): Should the project be added to the default solution file?

docs/core/generators/library.md

@@ -33,3 +33,9 @@ Generate a dotnet project under the library directory.
 ### standalone
 
 - (boolean): Should the project use project.json? If false, the project config is inside workspace.json
+
+### solutionFile
+
+- (string): The name of the solution file to add the project to
+
+- (boolean): Should the project be added to the default solution file?

docs/core/generators/test.md

@@ -29,3 +29,9 @@ Generate a .NET test project for an existing application or library
 ### standalone
 
 - (boolean): Should the project use project.json? If false, the project config is inside workspace.json
+
+### solutionFile
+
+- (string): The name of the solution file to add the project to
+
+- (boolean): Should the project be added to the default solution file?

docs/core/guides/_category_.yml

@@ -0,0 +1,2 @@
+label: 'Guides'
+position: 1

docs/core/guides/handling-solutions.md

@@ -0,0 +1,37 @@
+# Handling Solution Files
+
+## Workspace Level
+
+As of v1.7.0, `nx-dotnet` supports adding projects to a workspace level solution file automatically. When generating an app, lib, or test project you can pass `--solutionFile` to add the project to the default solution at the workspace root. Alternatively, you can pass `--solutionFile {path/to/sln}` to add the project to a custom solution file. This should look something like:
+
+```bash
+npx nx g @nx-dotnet/core:app my-api --template webapi --solutionFile MyCompany.sln
+```
+
+To add projects to a solution file by default, you can set the generator defaults in [nx.json](https://nx.dev/l/a/core-concepts/configuration#nxjson) as below:
+
+```json5
+{
+  // ... more nx.json configuration
+  generators: {
+    // ... other default configurations
+    '@nx-dotnet/core:app': {
+      solutionFile: true,
+    },
+  },
+}
+```
+
+## Subgraph Solutions
+
+In a large monorepo, IDEs or other tooling may slow down when presented with a large solution file. Currently, `nx-dotnet` does not assist in managing this issue, but there are a few easy steps to take that can help optimize your workflow. Which path you take will depend on both the tooling you use, and the pains that you are enountering.
+
+Either of the two approaches listed below could be expanded on in the future, but currently are not in the scope of the nx-plugin.
+
+### Separate solution files
+
+One option would be totally separated solution files for project graphs that are not connected. The main thing to be cautious with in an approach like this, is that if the dependency graph changes and the two subgraphs become connected it would be possible to make changes that break a project not currently visible to the IDE. For example, lets say you have 3 projects `A`, `B`, and `Shared`. If `A` and `B` both depend on `Shared`, and you have separate solutions each containing either `A` or `B` alongside the `Shared` project, a developer could modify the code in `Shared` and break the project that was not included in the opened solution file. As such, any solution that contained `Shared` _must_ contain all projects that depend on it to maintain good DX.
+
+### Solution filters
+
+Some IDEs such as Visual Studio support solution filters. These filters would allow for all projects to be visible to the IDE, but can have some performance benefits. The caveats to using separate files can still exist though, but these could be easier to maintain in the long run. Here is a link to the [msdn docs for solution filters](https://docs.microsoft.com/en-us/visualstudio/ide/filtered-solutions?view=vs-2022).

e2e/core-e2e/project.json

@@ -6,7 +6,7 @@
     "e2e": {
       "executor": "@nrwl/nx-plugin:e2e",
       "options": {
-        "target": "core:build",
+        "target": "core:noop",
         "jestConfig": "e2e/core-e2e/jest.config.js"
       }
     }

e2e/core-e2e/tests/nx-dotnet.spec.ts

@@ -1,13 +1,9 @@
-import {
-  joinPathFragments,
-  names,
-  WorkspaceJsonConfiguration,
-} from '@nrwl/devkit';
+import { joinPathFragments, names } from '@nrwl/devkit';
 import {
   checkFilesExist,
   ensureNxProject,
+  listFiles,
   readFile,
-  readJson,
   runNxCommandAsync,
   uniq,
 } from '@nrwl/nx-plugin/testing';
@@ -20,6 +16,7 @@ import { findProjectFileInPathSync } from '@nx-dotnet/utils';
 import { readDependenciesFromNxDepGraph } from '@nx-dotnet/utils/e2e';
 import { execSync } from 'child_process';
 import { ensureDirSync } from 'fs-extra';
+import { Workspaces } from '@nrwl/tao/src/shared/workspace';
 
 const e2eDir = 'tmp/nx-e2e/proj';
 
@@ -234,7 +231,7 @@ describe('nx-dotnet e2e', () => {
 
       await runNxCommandAsync(`generate @nx-dotnet/core:import-projects`);
 
-      const workspace = readJson<WorkspaceJsonConfiguration>('workspace.json');
+      const workspace = new Workspaces(e2eDir).readWorkspaceConfiguration();
 
       expect(workspace.projects[testApp].targets?.serve).toBeDefined();
       expect(workspace.projects[testApp].targets?.build).toBeDefined();
@@ -250,4 +247,62 @@ describe('nx-dotnet e2e', () => {
       checkFilesExist(`dist/apps/${testApp}`);
     });
   });
+
+  describe('solution handling', () => {
+    // For solution handling, defaults fall back to if a file exists.
+    // This ensures that the tests are ran in a clean state, without previous
+    // test projects interfering with the test.
+    beforeEach(() => {
+      ensureNxProject('@nx-dotnet/core', 'dist/packages/core');
+    }, 1500000);
+
+    it("shouldn't create a solution by default if not specified", async () => {
+      const app = uniq('app');
+      await runNxCommandAsync(
+        `generate @nx-dotnet/core:app ${app} --language="C#" --template="webapi"`,
+      );
+
+      expect(() => checkFilesExist(`apps/${app}`)).not.toThrow();
+      expect(listFiles('.').filter((x) => x.endsWith('.sln'))).toHaveLength(0);
+    });
+
+    it('should create a default solution file if specified as true', async () => {
+      const app = uniq('app');
+      await runNxCommandAsync(
+        `generate @nx-dotnet/core:app ${app} --language="C#" --template="webapi" --solutionFile`,
+      );
+
+      expect(() => checkFilesExist(`apps/${app}`)).not.toThrow();
+      expect(listFiles('.').filter((x) => x.endsWith('.sln'))).toHaveLength(1);
+    });
+
+    it('should create specified solution file if specified as string', async () => {
+      const app = uniq('app');
+      await runNxCommandAsync(
+        `generate @nx-dotnet/core:app ${app} --language="C#" --template="webapi" --solutionFile="MyCompany.sln"`,
+      );
+
+      expect(() =>
+        checkFilesExist(`apps/${app}`, `MyCompany.sln`),
+      ).not.toThrow();
+    });
+
+    it('should add successive projects to default solution file', async () => {
+      const app1 = uniq('app');
+      await runNxCommandAsync(
+        `generate @nx-dotnet/core:app ${app1} --language="C#" --template="webapi" --solutionFile`,
+      );
+
+      const app2 = uniq('app2');
+      await runNxCommandAsync(
+        `generate @nx-dotnet/core:app ${app2} --language="C#" --template="webapi" --solutionFile`,
+      );
+
+      const slnFile = readFile('proj.nx-dotnet.sln');
+
+      expect(() => checkFilesExist(`apps/${app1}`)).not.toThrow();
+      expect(slnFile).toContain(app1);
+      expect(slnFile).toContain(app2);
+    });
+  });
 });