diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml new file mode 100644 index 0000000..4c81a4e --- /dev/null +++ b/.github/workflows/build-and-test.yml @@ -0,0 +1,37 @@ +name: Build, Test & Coverage + +on: + push: + branches: [ master ] + pull_request: + workflow_dispatch: + +jobs: + build-and-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET 10 SDK + uses: actions/setup-dotnet@v4 + with: + dotnet-version: '10.x' + + - name: Restore dependencies + run: dotnet restore + working-directory: ./src + + - name: Build all projects + run: dotnet build --configuration Release --no-restore + working-directory: ./src + + - name: Run tests with code coverage + run: dotnet test --configuration Release --no-build /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura /p:CoverletOutput=../../coverage/coverage.cobertura.xml + working-directory: ./src + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v5 + with: + token: ${{ secrets.CODECOV_TOKEN }} + directory: ./coverage/ + fail_ci_if_error: true diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index a698370..0000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: CI - Build, Test & Coverage - -on: - push: - branches: [ master ] - pull_request: - workflow_dispatch: - -jobs: - build-and-test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Use .NET 9 SDK - uses: actions/setup-dotnet@v4 - with: - dotnet-version: 9.x - - - name: Restore dependencies - run: dotnet restore - - - name: Build all projects - run: dotnet build --no-restore - - - name: Run tests with code coverage - run: dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=lcov /p:CoverletOutput=./coverage/ - - - name: Upload coverage to Coveralls - uses: coverallsapp/github-action@v1.1.2 - with: - github-token: ${{ github.token }} - path-to-lcov: ${{ github.workspace }}/src/dotenv.net.Tests/coverage/coverage.info diff --git a/README.md b/README.md index 6d60222..4e92a27 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![CI - Build, Test & Coverage](https://github.com/bolorundurowb/dotenv.net/actions/workflows/build.yml/badge.svg)](https://github.com/bolorundurowb/dotenv.net/actions/workflows/build.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![Coverage Status](https://coveralls.io/repos/github/bolorundurowb/dotenv.net/badge.svg?branch=master)](https://coveralls.io/github/bolorundurowb/dotenv.net?branch=master) +[![codecov](https://codecov.io/gh/bolorundurowb/dotenv.net/graph/badge.svg?token=Qw8xSiEHNp)](https://codecov.io/gh/bolorundurowb/dotenv.net) ![NuGet Version](https://img.shields.io/nuget/v/dotenv.net) @@ -19,7 +19,7 @@ Whether you're building a small project or a large-scale application, **dotenv.n - **Simple and Pain-Free** 🎯: Easily load and read `.env` files with minimal setup. - **Flexible Configuration** 🔧: Customize how environment variables are loaded with a variety of options. - **Dependency Injection Support** 🧩: Works seamlessly with popular DI frameworks. -- **Cross-Platform** 🌍: Fully compatible with .NET Core, .NET 5, and beyond. +- **Cross-Platform** 🌍: Fully compatible with .NET Core, .NET 5, .NET 6, .NET 9 and beyond. - **Open Source** 💡: Actively maintained and supported by the community. --- @@ -42,7 +42,7 @@ You can install **dotenv.net** via NuGet: - **Manual Installation** (via `.csproj`): ```xml - + ``` --- @@ -61,13 +61,43 @@ You can install **dotenv.net** via NuGet: DotEnv.Load(); ``` - This will automatically locate and load the `.env` file in the same directory as your application. + This will automatically locate and load the `.env` file in the same directory as your application's executable. + +--- + +### Fluent API 🎨 + +For a more expressive syntax, **dotenv.net** provides a fluent API: + +```csharp +// Load environment variables with custom options +DotEnv.Fluent() + .WithExceptions() + .WithEnvFiles("./path/to/env") + .WithTrimValues() + .WithEncoding(Encoding.ASCII) + .WithOverwriteExistingVars() + .WithProbeForEnv(probeLevelsToSearch: 6) + .WithSupportExportSyntax() + .Load(); + +// Read environment variables +var envVars = DotEnv.Fluent() + .WithoutExceptions() + .WithEnvFiles() // Defaults to .env + .WithoutTrimValues() + .WithEncoding(Encoding.UTF8) + .WithoutOverwriteExistingVars() + .WithoutProbeForEnv() + .WithoutSupportExportSyntax() + .Read(); +``` --- ### Advanced Configuration ⚙️ -**dotenv.net** offers a wide range of configuration options to tailor the loading process to your needs: +**dotenv.net** offers a wide range of configuration options to tailor the loading process to your needs using the `DotEnvOptions` class: - **Specify Custom `.env` File Paths**: ```csharp @@ -112,36 +142,6 @@ Console.WriteLine(envVars["KEY"]); // Outputs the value associated with 'KEY' --- -### Fluent API 🎨 - -For a more expressive syntax, **dotenv.net** provides a fluent API: - -```csharp -// Load environment variables with custom options -DotEnv.Fluent() - .WithExceptions() - .WithEnvFiles("./path/to/env") - .WithTrimValues() - .WithEncoding(Encoding.ASCII) - .WithOverwriteExistingVars() - .WithProbeForEnv(probeLevelsToSearch: 6) - .WithSupportExportSyntax() - .Load(); - -// Read environment variables -var envVars = DotEnv.Fluent() - .WithoutExceptions() - .WithEnvFiles() // Defaults to .env - .WithoutTrimValues() - .WithDefaultEncoding() - .WithoutOverwriteExistingVars() - .WithoutProbeForEnv() - .WithoutSupportExportSyntax() - .Read(); -``` - ---- - ### Environment Variable Helpers 🛠️ The `Utilities` namespace provides additional methods for reading environment variables in a typed manner: diff --git a/src/dotenv.net.Tests/ReaderTests.cs b/src/dotenv.net.Tests/ReaderTests.cs index b75b8d3..826642b 100644 --- a/src/dotenv.net.Tests/ReaderTests.cs +++ b/src/dotenv.net.Tests/ReaderTests.cs @@ -201,8 +201,6 @@ public void GetProbedEnvPath_FileNotFoundAndIgnoreExceptionsFalse_ShouldThrow() exception.Message.ShouldContain($"after searching {levelsToSearch} directory level(s) upwards."); exception.Message.ShouldContain("Searched paths:"); exception.Message.ShouldContain(_startPath); - exception.Message.ShouldContain("net9.0"); - exception.Message.ShouldContain("Debug"); } [Fact] diff --git a/src/dotenv.net.Tests/dotenv.net.Tests.csproj b/src/dotenv.net.Tests/dotenv.net.Tests.csproj index 79ff41d..a6ce9ee 100644 --- a/src/dotenv.net.Tests/dotenv.net.Tests.csproj +++ b/src/dotenv.net.Tests/dotenv.net.Tests.csproj @@ -1,23 +1,23 @@  - net9.0 + net10.0 false latest enable - + all runtime; build; native; contentfiles; analyzers; buildtransitive - + runtime; build; native; contentfiles; analyzers all - + - + all runtime; build; native; contentfiles; analyzers; buildtransitive diff --git a/dotenv.net.sln b/src/dotenv.net.sln similarity index 87% rename from dotenv.net.sln rename to src/dotenv.net.sln index 33d9e2b..9f4a3e2 100644 --- a/dotenv.net.sln +++ b/src/dotenv.net.sln @@ -2,9 +2,9 @@ # Visual Studio 2013 VisualStudioVersion = 12.0.0.0 MinimumVisualStudioVersion = 10.0.0.1 -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "dotenv.net", "src\dotenv.net\dotenv.net.csproj", "{ABC30C21-62C1-4DF5-B352-4D33BCDD9845}" +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "dotenv.net", "dotenv.net\dotenv.net.csproj", "{ABC30C21-62C1-4DF5-B352-4D33BCDD9845}" EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "dotenv.net.Tests", "src\dotenv.net.Tests\dotenv.net.Tests.csproj", "{FC5ED4B3-DFDC-45E9-889C-847433F08E0E}" +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "dotenv.net.Tests", "dotenv.net.Tests\dotenv.net.Tests.csproj", "{FC5ED4B3-DFDC-45E9-889C-847433F08E0E}" EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution diff --git a/src/dotenv.net/DotEnv.cs b/src/dotenv.net/DotEnv.cs index 7c150fe..867c0ad 100644 --- a/src/dotenv.net/DotEnv.cs +++ b/src/dotenv.net/DotEnv.cs @@ -3,18 +3,22 @@ namespace dotenv.net; +/// +/// Provides static methods to configure, read, and load environment variables from .env files. +/// public static class DotEnv { /// - /// Initialize the fluent configuration API + /// Initialises the fluent configuration API. /// + /// A new instance of . public static DotEnvOptions Fluent() => new(); /// - /// Read and return the values in the provided env files + /// Reads the values from the provided env files based on the specified options. /// - /// The options required to configure the env loader - /// The key value pairs read from the env files + /// The options required to configure the env loader. If null, default options are used. + /// A dictionary containing the key-value pairs read from the env files. public static IDictionary Read(DotEnvOptions? options = null) { options ??= new DotEnvOptions(); @@ -35,9 +39,9 @@ public static IDictionary Read(DotEnvOptions? options = null) } /// - /// Load the values in the provided env files into the environment variables + /// Loads the values from the provided env files into the system environment variables. /// - /// The options required to configure the env loader + /// The options required to configure the env loader. If null, default options are used. public static void Load(DotEnvOptions? options = null) { options ??= new DotEnvOptions(); diff --git a/src/dotenv.net/DotEnvOptions.cs b/src/dotenv.net/DotEnvOptions.cs index b95b454..7535826 100644 --- a/src/dotenv.net/DotEnvOptions.cs +++ b/src/dotenv.net/DotEnvOptions.cs @@ -5,6 +5,9 @@ namespace dotenv.net; +/// +/// Represents the configuration options for reading and loading .env files. +/// public class DotEnvOptions { private static readonly string[] DefaultEnvPath = [DefaultEnvFileName]; @@ -17,12 +20,12 @@ public class DotEnvOptions public bool IgnoreExceptions { get; private set; } /// - /// The paths to the env files. The default is [.env] + /// The paths to the env files. The default is [.env]. /// public IEnumerable EnvFilePaths { get; private set; } /// - /// The Encoding that the env file was created with. The default is UTF-8. + /// The encoding that the env file was created with. The default is UTF-8. /// public Encoding Encoding { get; private set; } @@ -48,21 +51,21 @@ public class DotEnvOptions public int? ProbeLevelsToSearch { get; private set; } /// - /// Whether the optional dotenv export syntax should be supported. The default is false + /// Whether the optional dotenv export syntax should be supported. The default is false. /// public bool SupportExportSyntax { get; private set; } /// - /// Default constructor for the dot env options + /// Initialises a new instance of the class. /// - /// Whether to ignore exceptions - /// The env file paths to load - /// The encoding the env files are in - /// Whether to trim whitespace from the read values - /// Whether to overwrite a given env var if it is already set - /// Whether to search up the directories looking for an env file - /// How high up the directory chain to search - /// Whether to support env vars in the export syntax + /// Whether to ignore exceptions during the loading process. + /// The paths to the env files to load. + /// The encoding the env files are in. + /// Whether to trim whitespace from the read values. + /// Whether to overwrite a given env var if it is already set. + /// Whether to search up the directories looking for an env file. + /// How high up the directory chain to search. + /// Whether to support env vars in the export syntax. public DotEnvOptions(bool ignoreExceptions = true, IEnumerable? envFilePaths = null, Encoding? encoding = null, bool trimValues = false, bool overwriteExistingVars = true, bool probeForEnv = false, int? probeLevelsToSearch = null, bool supportExportSyntax = false) @@ -97,9 +100,9 @@ public DotEnvOptions(bool ignoreExceptions = true, IEnumerable? envFileP } /// - /// Ignore exceptions thrown + /// Enables exception throwing when errors occur. /// - /// configured dot env options + /// The current instance. public DotEnvOptions WithExceptions() { IgnoreExceptions = false; @@ -107,9 +110,9 @@ public DotEnvOptions WithExceptions() } /// - /// Throw exceptions when triggered + /// Disables exception throwing when errors occur. /// - /// configured dot env options + /// The current instance. public DotEnvOptions WithoutExceptions() { IgnoreExceptions = true; @@ -117,9 +120,11 @@ public DotEnvOptions WithoutExceptions() } /// - /// Search up the directory for a .env file. Searches up 4 directory levels by default. + /// Enables searching up the directory tree for a .env file. /// - /// configured dot env options + /// How high up the directory chain to search. + /// The current instance. + /// Thrown when EnvFiles is already set. public DotEnvOptions WithProbeForEnv(int probeLevelsToSearch = DefaultProbeAscendLimit) { if (EnvFilePaths?.FirstOrDefault() != DefaultEnvFileName) @@ -131,9 +136,9 @@ public DotEnvOptions WithProbeForEnv(int probeLevelsToSearch = DefaultProbeAscen } /// - /// Rely on the provided env files. Defaults to false. + /// Disables searching up the directory tree for a .env file. /// - /// configured dot env options + /// The current instance. public DotEnvOptions WithoutProbeForEnv() { ProbeForEnv = false; @@ -142,9 +147,9 @@ public DotEnvOptions WithoutProbeForEnv() } /// - /// Overwrite an environment variable even if it has been set + /// Enables overwriting existing environment variables. /// - /// configured dot env options + /// The current instance. public DotEnvOptions WithOverwriteExistingVars() { OverwriteExistingVars = true; @@ -152,9 +157,9 @@ public DotEnvOptions WithOverwriteExistingVars() } /// - /// Only write an environment variable if it hasn't been et + /// Disables overwriting existing environment variables. /// - /// configured dot env options + /// The current instance. public DotEnvOptions WithoutOverwriteExistingVars() { OverwriteExistingVars = false; @@ -162,9 +167,9 @@ public DotEnvOptions WithoutOverwriteExistingVars() } /// - /// Trim whitespace from the values read + /// Enables trimming of whitespace from retrieved values. /// - /// configured dot env options + /// The current instance. public DotEnvOptions WithTrimValues() { TrimValues = true; @@ -172,9 +177,9 @@ public DotEnvOptions WithTrimValues() } /// - /// Leave read values as is + /// Disables trimming of whitespace from retrieved values. /// - /// configured dot env options + /// The current instance. public DotEnvOptions WithoutTrimValues() { TrimValues = false; @@ -182,9 +187,11 @@ public DotEnvOptions WithoutTrimValues() } /// - /// Change the encoding for reading the env files + /// Sets the encoding to be used when reading the env files. /// - /// configured dot env options + /// The encoding to use. + /// The current instance. + /// Thrown when encoding is null. public DotEnvOptions WithEncoding(Encoding encoding) { if (encoding == null) @@ -195,9 +202,9 @@ public DotEnvOptions WithEncoding(Encoding encoding) } /// - /// Support export syntax entries + /// Enables support for the 'export' syntax in env files. /// - /// Configured DotEnvOptions + /// The current instance. public DotEnvOptions WithSupportExportSyntax() { SupportExportSyntax = true; @@ -205,9 +212,9 @@ public DotEnvOptions WithSupportExportSyntax() } /// - /// Disallow support export syntax entries + /// Disables support for the 'export' syntax in env files. /// - /// Configured DotEnvOptions + /// The current instance. public DotEnvOptions WithoutSupportExportSyntax() { SupportExportSyntax = false; @@ -215,9 +222,12 @@ public DotEnvOptions WithoutSupportExportSyntax() } /// - /// Set the env files to be read, if none is provided, we revert to the default '.env' + /// Sets the env files to be read. /// - /// configured dot env options + /// The paths to the env files. + /// The current instance. + /// Thrown when ProbeForEnv is already set to true. + /// Thrown when envFilePaths is null. public DotEnvOptions WithEnvFiles(params string[] envFilePaths) { if (ProbeForEnv) @@ -231,13 +241,13 @@ public DotEnvOptions WithEnvFiles(params string[] envFilePaths) } /// - /// Return the values in the env files without writing to the environment + /// Reads the env files and returns the values without writing to the system environment. /// - /// configured dot env options + /// A dictionary containing the read environment variables. public IDictionary Read() => DotEnv.Read(this); /// - /// ReadFileLines the env files and write to the system environment variables + /// Reads the env files and writes the values to the system environment variables. /// public void Load() => DotEnv.Load(this); } \ No newline at end of file diff --git a/src/dotenv.net/Utilities/EnvReader.cs b/src/dotenv.net/Utilities/EnvReader.cs index 1d1fad0..e36d6bc 100644 --- a/src/dotenv.net/Utilities/EnvReader.cs +++ b/src/dotenv.net/Utilities/EnvReader.cs @@ -3,16 +3,16 @@ namespace dotenv.net.Utilities; /// -/// Holds reader helper methods +/// Provides helper methods for reading strongly-typed values from the environment. /// public static class EnvReader { /// - /// Retrieve a string value from the current environment + /// Retrieves a string value from the current environment. /// - /// The key to retrieve the value via - /// A string representing the value - /// When the value could not be found + /// The key to retrieve the value via. + /// A string representing the value. + /// Thrown when the value could not be found. public static string GetStringValue(string key) { if (TryGetStringValue(key, out var value)) @@ -22,11 +22,11 @@ public static string GetStringValue(string key) } /// - /// Retrieve an integer value from the current environment + /// Retrieves an integer value from the current environment. /// - /// The key to retrieve the value via - /// An integer representing the value - /// When the value could not be found or is not an integer + /// The key to retrieve the value via. + /// An integer representing the value. + /// Thrown when the value could not be found or is not a valid integer. public static int GetIntValue(string key) { if (TryGetIntValue(key, out var value)) @@ -36,11 +36,11 @@ public static int GetIntValue(string key) } /// - /// Retrieve a double value from the current environment + /// Retrieves a double value from the current environment. /// - /// The key to retrieve the value via - /// A double representing the value - /// When the value could not be found or is not a valid double + /// The key to retrieve the value via. + /// A double representing the value. + /// Thrown when the value could not be found or is not a valid double. public static double GetDoubleValue(string key) { if (TryGetDoubleValue(key, out var value)) @@ -50,11 +50,11 @@ public static double GetDoubleValue(string key) } /// - /// Retrieve a decimal value from the current environment + /// Retrieves a decimal value from the current environment. /// - /// The key to retrieve the value via - /// A decimal representing the value - /// When the value could not be found or is not a valid decimal + /// The key to retrieve the value via. + /// A decimal representing the value. + /// Thrown when the value could not be found or is not a valid decimal. public static decimal GetDecimalValue(string key) { if (TryGetDecimalValue(key, out var value)) @@ -64,11 +64,11 @@ public static decimal GetDecimalValue(string key) } /// - /// Retrieve a boolean value from the current environment + /// Retrieves a boolean value from the current environment. /// - /// The key to retrieve the value via - /// A boolean representing the value - /// When the value could not be found or is not a valid bool + /// The key to retrieve the value via. + /// A boolean representing the value. + /// Thrown when the value could not be found or is not a valid boolean. public static bool GetBooleanValue(string key) { if (TryGetBooleanValue(key, out var value)) @@ -78,11 +78,11 @@ public static bool GetBooleanValue(string key) } /// - /// Try to retrieve a value from the current environment + /// Tries to retrieve a string value from the current environment. /// - /// The key to retrieve the value via - /// The string value retrieved or null - /// A value representing the retrieval success status + /// The key to retrieve the value via. + /// When this method returns, contains the string value retrieved, or null if the retrieval failed. + /// True if the value was successfully retrieved; otherwise, false. public static bool TryGetStringValue(string key, out string? value) { var retrievedValue = Environment.GetEnvironmentVariable(key); @@ -98,11 +98,11 @@ public static bool TryGetStringValue(string key, out string? value) } /// - /// Try to retrieve an int value from the current environment + /// Tries to retrieve an integer value from the current environment. /// - /// The key to retrieve the value via - /// The int value retrieved or null - /// A value representing the retrieval success status + /// The key to retrieve the value via. + /// When this method returns, contains the integer value retrieved, or 0 if the retrieval failed. + /// True if the value was successfully retrieved and parsed; otherwise, false. public static bool TryGetIntValue(string key, out int value) { var retrievedValue = Environment.GetEnvironmentVariable(key); @@ -115,11 +115,11 @@ public static bool TryGetIntValue(string key, out int value) } /// - /// Try to retrieve a double value from the current environment + /// Tries to retrieve a double value from the current environment. /// - /// The key to retrieve the value via - /// The double value retrieved or null - /// A value representing the retrieval success status + /// The key to retrieve the value via. + /// When this method returns, contains the double value retrieved, or 0.0 if the retrieval failed. + /// True if the value was successfully retrieved and parsed; otherwise, false. public static bool TryGetDoubleValue(string key, out double value) { var retrievedValue = Environment.GetEnvironmentVariable(key); @@ -132,11 +132,11 @@ public static bool TryGetDoubleValue(string key, out double value) } /// - /// Try to retrieve a decimal value from the current environment + /// Tries to retrieve a decimal value from the current environment. /// - /// The key to retrieve the value via - /// The decimal value retrieved or null - /// A value representing the retrieval success status + /// The key to retrieve the value via. + /// When this method returns, contains the decimal value retrieved, or 0.0m if the retrieval failed. + /// True if the value was successfully retrieved and parsed; otherwise, false. public static bool TryGetDecimalValue(string key, out decimal value) { var retrievedValue = Environment.GetEnvironmentVariable(key); @@ -149,11 +149,11 @@ public static bool TryGetDecimalValue(string key, out decimal value) } /// - /// Try to retrieve a boolean value from the current environment + /// Tries to retrieve a boolean value from the current environment. /// - /// The key to retrieve the value via - /// The boolean value retrieved or null - /// A value representing the retrieval success status + /// The key to retrieve the value via. + /// When this method returns, contains the boolean value retrieved, or false if the retrieval failed. + /// True if the value was successfully retrieved and parsed; otherwise, false. public static bool TryGetBooleanValue(string key, out bool value) { var retrievedValue = Environment.GetEnvironmentVariable(key); @@ -166,13 +166,13 @@ public static bool TryGetBooleanValue(string key, out bool value) } /// - /// Determine if an environment key has a set value or not + /// Determines whether an environment key has a set value. /// - /// The key to retrieve the value via - /// A value determining if a value is set or not + /// The key to check. + /// True if a value is set; otherwise, false. public static bool HasValue(string key) { var retrievedValue = Environment.GetEnvironmentVariable(key); return !string.IsNullOrEmpty(retrievedValue); } -} +} \ No newline at end of file diff --git a/src/dotenv.net/dotenv.net.csproj b/src/dotenv.net/dotenv.net.csproj index 4e6aa51..9377d6a 100644 --- a/src/dotenv.net/dotenv.net.csproj +++ b/src/dotenv.net/dotenv.net.csproj @@ -1,7 +1,7 @@  - ©2017-2025 , Bolorunduro Winner-Timothy. All Rights reserved. - - support quotation escape support + ©2017-2026 , Bolorunduro Winner-Timothy. All Rights reserved. + - improve method xml documentation Winner-Timothy Bolorunduro true dotenv.net @@ -12,7 +12,7 @@ https://github.com/bolorundurowb/dotenv.net default README.md - 4.0.0 + 4.0.1 git dotnet, environment, variables, env, dotenv, net core, autofac true