Guidelines for contributing to Microsoft's Service Fabric Services and Actors .NET SDK, covering API documentation, testing patterns, and project structure.
Guidelines for contributing to the Service Fabric Services and Actors .NET SDK for building highly-scalable distributed cloud applications.
You are working on the Microsoft Service Fabric SDK for .NET, which provides:
When writing or modifying code:
1. **XML Documentation Required**: Always add XML documentation for all public APIs
2. **Public APIs Only**: Only generate documentation for public-facing APIs
3. **Completeness**: Ensure all parameters, return values, and exceptions are documented
Example:
```csharp
/// <summary>
/// Creates a new reliable service instance.
/// </summary>
/// <param name="context">The service context.</param>
/// <returns>A new instance of the reliable service.</returns>
/// <exception cref="ArgumentNullException">Thrown when context is null.</exception>
public IReliableService CreateService(ServiceContext context)
{
// Implementation
}
```
Organize tests using a hierarchical class structure for clarity and organization:
```csharp
namespace Microsoft.ServiceFabric.TestedProject
{
public abstract class SystemUnderTestClassTest
{
// Setup common test context
public SystemUnderTestClassTest()
{
// Initialize common resources shared across test methods
}
public sealed class MethodName : SystemUnderTestClassTest
{
[Fact]
public void ShouldDoSomething()
{
// Arrange
var sut = new SystemUnderTestClass();
// Act
var result = sut.MethodName();
// Assert
Assert.NotNull(result);
}
}
public sealed class AnotherMethodName : SystemUnderTestClassTest
{
[Fact]
public void ShouldHandleEdgeCase()
{
// Arrange, Act, Assert
}
}
}
}
```
1. **Abstract Base Class**: Create an abstract base class named `{ClassUnderTest}Test`
2. **Shared Setup**: Use the base class constructor for common initialization
3. **Nested Classes**: Create sealed nested classes for each method being tested
4. **Method Names**: Use descriptive test method names starting with "Should"
5. **AAA Pattern**: Structure tests with Arrange, Act, Assert sections
6. **No "Tests" Suffix**: Do NOT add "Tests" suffix to test namespaces (causes unnecessary imports)
```csharp
namespace Microsoft.ServiceFabric.Services.Remoting
{
public abstract class ServiceRemotingMessageHeadersTest
{
protected ServiceRemotingMessageHeaders CreateHeaders()
{
return new ServiceRemotingMessageHeaders();
}
public sealed class AddHeader : ServiceRemotingMessageHeadersTest
{
[Fact]
public void ShouldAddHeaderSuccessfully()
{
// Arrange
var headers = CreateHeaders();
// Act
headers.AddHeader("key", new byte[] { 1, 2, 3 });
// Assert
Assert.True(headers.TryGetHeaderValue("key", out var value));
Assert.Equal(new byte[] { 1, 2, 3 }, value);
}
}
public sealed class TryGetHeaderValue : ServiceRemotingMessageHeadersTest
{
[Fact]
public void ShouldReturnFalseWhenHeaderNotFound()
{
// Arrange
var headers = CreateHeaders();
// Act
var result = headers.TryGetHeaderValue("nonexistent", out var value);
// Assert
Assert.False(result);
Assert.Null(value);
}
}
}
}
```
1. **Consistency**: Follow existing code patterns and conventions in the repository
2. **Build Verification**: Ensure all changes build successfully with MSBuild
3. **Package References**: Use NuGet for all external dependencies
4. **Target Frameworks**: Consider both .NET Framework and modern .NET when making changes
5. **Public API Changes**: Document any breaking changes or new public APIs thoroughly
1. Add XML documentation for all public APIs
2. Write comprehensive xUnit tests using the hierarchical structure
3. Ensure compatibility with both .NET Framework and .NET targets
4. Update relevant documentation files
5. Follow Service Fabric patterns for Reliable Services and Actors
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/service-fabric-reliable-services-and-actors-net-sdk/raw