### Install NuGet Package (GitHub Packages) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md Commands to add the GitHub Packages feed and install the library from it. ```bash dotnet nuget add source --username USERNAME --password "${{ secrets.GITHUB_TOKEN }}" --store-password-in-clear-text --name github "https://nuget.pkg.github.com/NAMESPACE/index.json" dotnet add package mypackage ``` -------------------------------- ### Project Setup and Configuration Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md This section outlines initial setup steps after generating a new project from the starter kit. It covers updating documentation, reviewing contribution guidelines, adjusting .NET framework targets, and configuring package management settings. ```markdown > [!TIP] > What to do next after generating the template The template makes a lot of assumptions, so after generating the project, there's a couple of things you can tweak. * Update the `Readme.md` and `PackageReadme.md` with information about your library * Review the guidelines in `CONTRIBUTING.md` to see if it aligns with how you want to handle contributions * Review the issue templates under `.github/issue_template` * Set-up labels in GitHub matching those in the `release.yml` so you can label pull requests accordingly * Adjust the .NET frameworks this library should target * Adjust the root namespace and assembly names * For the source-only packages, update the `.nuspec` file so it represents your information. * Alter the coverage service that is being used. * Determine if you want to use API verification against snapshots * Study the Nuke `build.cs` file or invoking it through `build.ps1 -plan` to see how it works * See if all dependencies are up-to-date * Configure NuGet auditing (see next paragraph) * Fine-tune the allowed open-source licenses and packages in the `.\packageguard\config.json` * Store the PackageGuard cache that appears under `.\packageguard` after a first build in source control to speed-up successive runs * Adjust the `funding.yml` to allow people to sponsor your project * Review the code of conduct to see if it matches your opinions ``` ```markdown > [!NOTE] > Before the first time the build script has run on your new solution, the `.nuspec` file is still called `nuspec`. This was needed because `dotnet pack` refuses to include the `.nuspec` file in the template package this repository produces. This file is automatically renamed after the first time the `build.ps1` script is run. ``` ```markdown > [!TIP] > Also check-out the [main repository](https://github.com/dennisdoomen/dotnet-library-starter-kit) for additional information on these generated solutions. ``` -------------------------------- ### Install .NET Library Templates Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Installs the .NET library templates for creating new library projects. This command is used to add the starter kit templates to your local .NET SDK. ```bash dotnet new install DotNetLibraryPackageTemplates ``` -------------------------------- ### Install NuGet Package (Azure DevOps) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md Command to install the library as a NuGet package from an Azure DevOps feed. ```bash dotnet add package Fnv.IntegrationPlatform.Crm ``` -------------------------------- ### Install NuGet Package (Open Source) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md Command to install the library as a NuGet package when it's open source. ```bash dotnet add package mypackage ``` -------------------------------- ### Example C# Library Usage Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md This snippet demonstrates how to use the library with example C# code. It serves as a basic illustration of the library's functionality. ```csharp Some example code showing your library ``` -------------------------------- ### Unit Test Example (Arrange-Act-Assert) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/CONTRIBUTING.md An example demonstrating the Arrange-Act-Assert syntax for writing unit tests. This pattern is crucial for ensuring changes are covered by tests and maintaining code quality. ```csharp https://github.com/fluentassertions/fluentassertions/blob/daaf35b9b59b622c96d0c034e8972a020b2bee55/Tests/FluentAssertions.Shared.Specs/BasicEquivalencySpecs.cs#L33 ``` -------------------------------- ### Nuke Build Script Example Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Demonstrates a C# build script using Nuke, a common tool for automating .NET build processes. This script can be executed locally or within CI/CD pipelines. ```csharp using Nuke.Common; using Nuke.Common.CI; using Nuke.Common.Execution; using Nuke.Common.IO; using Nuke.Common.Tools.DotNet; using Nuke.Common.Tools.Git; using Nuke.Common.Tools.GitVersion; using Nuke.Extensions.Configuration; using Nuke.Extensions.Tasks; [Serializable] [PublicAPI] public abstract class Build : NukeBuild { [Parameter("Configuration to build - Default is 'Debug' (local) or 'Release' (CI)")] readonly Configuration Configuration = IsLocalBuild ? Configuration.Debug : Configuration.Release; [Solution("*.sln")] readonly Solution Solution; [GitVersion(Framework = "net8.0", Updateólogos = true)] readonly GitVersion GitVersion; Target Clean => _ => _ .Executes(() => { Solution.GetProject("MyProject").DeleteOutputs(); }); Target Compile => _ => _ .DependsOn(Clean) .Executes(() => { DotNetTasks.DotNetBuild(s => s .SetConfiguration(Configuration) .SetProjectFile(Solution.MyProject) .SetVersion(GitVersion.MajorMinorPatch) .SetAssemblyVersion(GitVersion.AssemblySemVer) .SetFileVersion(GitVersion.AssemblySemVer) .SetInformationalVersion(GitVersion.InformationalVersion) .EnableNoRestore()); }); Target Test => _ => _ .DependsOn(Compile) .Executes(() => { DotNetTasks.DotNetTest(s => s .SetConfiguration(Configuration) .SetProjectFile(Solution.MyProject) .EnableNoBuild()); }); Target Pack => _ => _ .DependsOn(Test) .Executes(() => { DotNetTasks.DotNetPack(s => s .SetConfiguration(Configuration) .SetProjectFile(Solution.MyProject) .SetVersion(GitVersion.MajorMinorPatch) .SetPackageVersion(GitVersion.MajorMinorPatch) .SetAssemblyVersion(GitVersion.AssemblySemVer) .SetFileVersion(GitVersion.AssemblySemVer) .SetInformationalVersion(GitVersion.InformationalVersion) .EnableNoBuild() .EnableNoRestore()); }); Target Publish => _ => _ .DependsOn(Pack) .Requires(() => Configuration.Equals(Configuration.Release)) .Executes(() => { DotNetTasks.DotNetNuGetPush(s => s .SetSource("https://api.nuget.org/v3/index.json") .SetApiKey(Environment.GetEnvironmentVariable("NUGET_API_KEY")) .Combine(Solution.MyProject.Directory / "*.nupkg")); }); public static int Main() => Execute(x => x.Compile); } ``` -------------------------------- ### Update .NET Templates Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Updates all installed .NET templates, including the library starter kit, to their latest available versions. This ensures you are using the most recent features and fixes. ```bash dotnet new update ``` -------------------------------- ### Build and Run Commands Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Provides command-line instructions for building, running unit tests, and packaging the code. It also mentions the `--help` and `--plan` options for more detailed usage. ```powershell build.ps1 nuke --help --plan ``` -------------------------------- ### Project Description - About Section Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md Provides a placeholder for describing the library's features, supported .NET versions, and dependencies. ```markdown ## About ### What's this? Add stuff like: * MyPackage offers * what .NET, C# other versions of dependencies it supports ``` -------------------------------- ### Build and Package Script Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md Command to build, run unit tests, and package the code using the provided PowerShell script. ```powershell build.ps1 ``` -------------------------------- ### Build with Nuke Tool Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md Command to build, run unit tests, and package the code using the Nuke build tool. ```bash nuke ``` -------------------------------- ### Dotnet CLI Commands for Library Management Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Common .NET CLI commands used for managing and building libraries, including restoring dependencies, building, testing, packing, and publishing NuGet packages. ```bash # Restore dependencies dotnet restore # Build the project in Release configuration dotnet build --configuration Release # Run tests dotnet test --configuration Release # Pack the project into a NuGet package dotnet pack --configuration Release --output ./artifacts # Publish the NuGet package to nuget.org dotnet nuget push "./artifacts/*.nupkg" --source "https://api.nuget.org/v3/index.json" --api-key YOUR_API_KEY ``` -------------------------------- ### API Verification Snapshot Testing Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Demonstrates the concept of API verification using snapshot testing. It explains how a `.txt` file represents the public API and how changes trigger test failures, requiring updates to snapshots via `AcceptApiChanges.ps1`. ```csharp public class ApiVerificationTests { // Generates a .txt file representing the public API. // Fails if API structure changes compared to the snapshot. // Use AcceptApiChanges.ps1 to update snapshots. } ``` -------------------------------- ### GitHub Actions Workflow for .NET Libraries Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md A GitHub Actions workflow file that automates the build, test, packaging, and publishing process for a .NET library. It integrates with GitVersion for automatic versioning. ```yaml name: Build on: push: branches: - main pull_request: branches: - main jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup .NET uses: actions/setup-dotnet@v4 with: dotnet-version: '8.0.x' - name: Install GitVersion uses: git-version/setup-git-version@v1.0.1 with: use-latest-main-branch-tag: true - name: Restore dependencies run: dotnet restore - name: Build run: dotnet build --no-restore --configuration Release - name: Test run: dotnet test --no-build --configuration Release --logger "trx;LogFileName=TestResults.trx" - name: Upload test results uses: actions/upload-artifact@v4 with: name: test-results path: "**/TestResults.trx" - name: Pack run: dotnet pack --no-build --configuration Release --output ./artifacts - name: Upload NuGet package uses: actions/upload-artifact@v4 with: name: nuget-package path: "./artifacts/*.nupkg" - name: Publish to NuGet if: github.ref == 'refs/heads/main' && github.event_name == 'push' run: dotnet nuget push "./artifacts/*.nupkg" --source "https://api.nuget.org/v3/index.json" --api-key ${{secrets.NUGET_API_KEY}} ``` -------------------------------- ### Generate Open-Source NuGet Class Library Solution Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Creates a new solution for an open-source .NET class library. This template is configured for public distribution and includes a solution file. ```bash dotnet new oss-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary ``` -------------------------------- ### Build, Test, and Package Library Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Executes the build script to compile the library, run automated tests, and package it into a NuGet package. The package is placed in the Artifacts directory. ```powershell build.ps1 ``` -------------------------------- ### Generate Azure DevOps NuGet Class Library Solution Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Creates a new solution for a .NET class library intended for use with Azure DevOps. This template requires organization and project names for configuration. ```bash dotnet new azdo-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary --organization MyDevOpsOrganization --project MyDevOpsProject ``` -------------------------------- ### Configure NuGet Auditing in Directory.Build.Props Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Demonstrates how to configure NuGet auditing settings within the Directory.Build.Props file. This includes options to update dependencies, include specific warning codes, or disable auditing entirely. ```xml NU1901;NU1902;NU1903 ``` -------------------------------- ### Generate Internal NuGet Class Library Solution Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Creates a new solution for an internal .NET class library. This template is suitable for private libraries within an organization and includes a solution file. ```bash dotnet new nooss-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary ``` -------------------------------- ### Rider Verify Support Plugin Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/CONTRIBUTING.md Utilize the Verify Support plugin within JetBrains Rider to manage and accept changes to the public API, ensuring compliance with project standards. ```csharp /* * Verify Support plugin in JetBrains Rider can be used to manage API changes. * Ensure your changes are compatible with the project's public API. */ ``` -------------------------------- ### Generate Open-Source Source-Only NuGet Class Library Solution Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Creates a new solution for an open-source .NET class library that distributes source files. This is ideal for open-source projects where direct source integration is preferred. ```bash dotnet new oss-source-only-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary ``` -------------------------------- ### Issue Tracking Link Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/CONTRIBUTING.md Provides a link to the project's issues page for checking existing issues. The link dynamically changes based on the 'azdo' variable. ```html issues ``` -------------------------------- ### Assembly Metadata Configuration (C#) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/net47.verified.txt Configures assembly metadata, including the repository URL based on the build environment (Azure DevOps or GitHub) and makes the assembly's internals visible to a specified project. ```csharp [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://dev.azure.com/MyOrganization/MyProject/_git/MyPackage")] [assembly: System.Runtime.CompilerServices.InternalsVisibleTo("MyPackage.Specs")] namespace MyPackage { public class MyClass { public MyClass() { } } } ``` -------------------------------- ### Generate Internal Source-Only NuGet Class Library Solution Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Creates a new solution for an internal .NET class library that distributes source files instead of binaries. This approach avoids binary dependencies and allows for easier integration. ```bash dotnet new nooss-source-only-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary ``` -------------------------------- ### Generate Azure DevOps Source-Only NuGet Class Library Solution Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/README.md Creates a new solution for a .NET class library that distributes source files for Azure DevOps projects. This option avoids binary dependencies and is suitable for source-integrated workflows. ```bash dotnet new azdo-source-only-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary --organization MyDevOpsOrganization --project MyDevOpsProject ``` -------------------------------- ### Build and Spellcheck Scripts Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/CONTRIBUTING.md Scripts to build the project and perform a spellcheck on the documentation. These are essential for maintaining code quality and accurate documentation. ```bash ./build.sh --target spellcheck ``` -------------------------------- ### Assembly Metadata Configuration (C#) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/netstandard2.0.verified.txt Configures assembly metadata, including the repository URL based on the build environment (Azure DevOps or GitHub) and makes the assembly's internals visible to a specified project. ```csharp [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://dev.azure.com/MyOrganization/MyProject/_git/MyPackage")] [assembly: System.Runtime.CompilerServices.InternalsVisibleTo("MyPackage.Specs")] namespace MyPackage { public class MyClass { public MyClass() { } } } ``` -------------------------------- ### Assembly Metadata Configuration (C#) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/netstandard2.1.verified.txt Configures assembly metadata, including the repository URL based on the build environment (Azure DevOps or GitHub) and makes the assembly's internals visible to a specified project. ```csharp [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://dev.azure.com/MyOrganization/MyProject/_git/MyPackage")] [assembly: System.Runtime.CompilerServices.InternalsVisibleTo("MyPackage.Specs")] namespace MyPackage { public class MyClass { public MyClass() { } } } ``` -------------------------------- ### Assembly Metadata Configuration Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/net8.0.verified.txt Configures assembly metadata, including the repository URL based on the build environment (Azure DevOps or GitHub) and specifies internal visibility for the test assembly. ```csharp {{~ if !source_only ~}} {{~ if azdo ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://dev.azure.com/MyOrganization/MyProject/_git/MyPackage")] {{~ else ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://github.com/your-user-name/my-package")] {{~ end ~}} {{~ end ~}} [assembly: System.Runtime.CompilerServices.InternalsVisibleTo("MyPackage.Specs")] ``` -------------------------------- ### Build and Spellcheck Scripts Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/CONTRIBUTING.md Scripts to build the project and perform a spellcheck on the documentation. These are essential for maintaining code quality and accurate documentation. ```powershell .\build.ps1 --target spellcheck ``` -------------------------------- ### Accept API Changes Scripts Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/CONTRIBUTING.md Scripts to accept changes to the public API. These scripts ensure that any modifications to the public API are properly recorded and integrated into the project. ```bash AcceptApiChanges.sh ``` -------------------------------- ### Basic Class Definition Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/net8.0.verified.txt Defines a simple class 'MyClass' within the 'MyPackage' namespace, with a default constructor. ```csharp namespace MyPackage { public class MyClass { public MyClass() { } } } ``` -------------------------------- ### Build Script Execution Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/README.md Explains the renaming of the `.nuspec` file to `nuspec` before the first build script execution and how it's automatically renamed afterward. This is a workaround for `dotnet pack` behavior. ```markdown > [!NOTE] > Before the first time the build script has run on your new solution, the `.nuspec` file is still called `nuspec`. This was needed because `dotnet pack` refuses to include the `.nuspec` file in the template package this repository produces. This file is automatically renamed after the first time the `build.ps1` script is run. ``` -------------------------------- ### API Change Acceptance Script Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/CONTRIBUTING.md Scripts to accept changes to the public API. These scripts are essential when modifying the project's public interface to ensure consistency and proper versioning. ```bash ./AcceptApiChanges.sh ``` -------------------------------- ### Accept API Changes Scripts Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/CONTRIBUTING.md Scripts to accept changes to the public API. These scripts ensure that any modifications to the public API are properly recorded and integrated into the project. ```powershell AcceptApiChanges.ps1 ``` -------------------------------- ### Conditional Repository URL (Handlebars) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/net47.verified.txt Conditionally sets the RepositoryUrl assembly metadata based on the 'azdo' variable, allowing for different repository URLs for Azure DevOps and GitHub. ```handlebars {{~ if !source_only ~}} {{~ if azdo ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://dev.azure.com/MyOrganization/MyProject/_git/MyPackage")] {{~ else ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://github.com/your-user-name/my-package")] {{~ end ~}} {{~ end ~}} ``` -------------------------------- ### API Change Acceptance Script Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/CONTRIBUTING.md Scripts to accept changes to the public API. These scripts are essential when modifying the project's public interface to ensure consistency and proper versioning. ```powershell .AcceptApiChanges.ps1 ``` -------------------------------- ### Conditional Repository URL (Handlebars) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/netstandard2.1.verified.txt Conditionally sets the RepositoryUrl assembly metadata based on the 'azdo' variable, allowing for different repository URLs for Azure DevOps and GitHub. ```handlebars {{~ if !source_only ~}} {{~ if azdo ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://dev.azure.com/MyOrganization/MyProject/_git/MyPackage")] {{~ else ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://github.com/your-user-name/my-package")] {{~ end ~}} {{~ end ~}} ``` -------------------------------- ### Conditional Repository URL (Handlebars) Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/MyPackage.ApiVerificationTests/ApprovedApi/netstandard2.0.verified.txt Conditionally sets the RepositoryUrl assembly metadata based on the 'azdo' variable, allowing for different repository URLs for Azure DevOps and GitHub. ```handlebars {{~ if !source_only ~}} {{~ if azdo ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://dev.azure.com/MyOrganization/MyProject/_git/MyPackage")] {{~ else ~}} [assembly: System.Reflection.AssemblyMetadata("RepositoryUrl", "https://github.com/your-user-name/my-package")] {{~ end ~}} {{~ end ~}} ``` -------------------------------- ### API Suggestion Issue Template Link Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/CONTRIBUTING.md Provides a link to the API suggestion issue template for proposing API changes. This is conditional on the 'azdo' variable being true. ```html API Suggestion issue template ``` -------------------------------- ### Bug Report Issue Template Link Source: https://github.com/dennisdoomen/dotnet-library-starter-kit/blob/main/templates/Source/CONTRIBUTING.md Provides a link to the bug report issue template for submitting bug reports. This is conditional on the 'azdo' variable being true. ```html Bug Report issue template ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.