CsEffect.System 0.15.0

CsEffect.System

Built-in effect attribute library providing system-oriented effects for CsEffect consumers.

Overview

CsEffect.System provides a collection of pre-defined effect attributes for common system operations like I/O, console output, file operations, and HTTP requests. This package serves as both a useful library and a reference implementation for creating your own effect libraries.

Included Effects

IoEffectAttribute

A general-purpose I/O effect that acts as a superset for other I/O-related effects.

[IoEffect]
public void DoGeneralIo()
{
    // Can call any I/O operation
}

ConsoleEffectAttribute

Covers operations that write to or read from the system console.

Targets: System.Console

[ConsoleEffect]
public void WriteToConsole(string message)
{
    Console.WriteLine(message);
    Console.Write("Prompt: ");
}

FileEffectAttribute

Covers file system operations.

Targets: System.IO.File
Severity: Error (violations are treated as compilation errors)

[FileEffect]
public void SaveData(string path, string data)
{
    File.WriteAllText(path, data);
}

HttpEffectAttribute

Covers HTTP operations including client requests and message handling.

Targets: HttpClient, HttpMessageInvoker, HttpRequestMessage, HttpResponseMessage

[HttpEffect]
public async Task<string> FetchDataAsync(string url)
{
    using var client = new HttpClient();
    return await client.GetStringAsync(url);
}

Effect Hierarchy

The effects in this library follow a hierarchy where more general effects can satisfy more specific requirements:

IoEffectAttribute (base)
├── ConsoleEffectAttribute
├── FileEffectAttribute  
└── HttpEffectAttribute

This means:

• Methods marked with [IoEffect] can call methods requiring [ConsoleEffect], [FileEffect], or [HttpEffect]
• Methods marked with [ConsoleEffect] cannot call methods requiring [FileEffect] or [HttpEffect] without additional annotations

Usage

1. Install the package:

   <PackageReference Include="CsEffect.System" Version="0.2.0" />
   

2. Use the attributes:

   using CsEffect.System;
   
   [ConsoleEffect, FileEffect] // Multiple effects can be combined
   public void LogToFileAndConsole(string message)
   {
       Console.WriteLine(message);
       File.AppendAllText("log.txt", message + Environment.NewLine);
   }
   

3. Enable analysis (requires CsEffect analyzer):

   <PackageReference Include="CsEffect" Version="0.2.0" OutputItemType="Analyzer" />
   

Creating Your Own Effect Libraries

Use this package as a reference for creating domain-specific effect libraries:

1. Reference the analyzer:

   <ProjectReference Include="path\to\CsEffect.Analyzer.csproj" />
   

2. Create your effects:

   [EffectTargets(typeof(Database))]
   public sealed class DatabaseEffectAttribute : EffectAttribute { }
   

3. Consider severity:

   [EffectSeverity(EffectViolationLevel.Error)] // Make violations errors
   public sealed class CriticalEffectAttribute : EffectAttribute { }
   

Best Practices

• Use specific effects ([FileEffect]) rather than general ones ([IoEffect]) when possible
• Combine multiple effects when a method performs multiple types of operations
• Consider creating your own effect hierarchies for domain-specific operations
• Use [IoEffect] as a catch-all when you need to perform various I/O operations

License

MIT