Skip to content

Commit f5681ac

Browse files
thomhurstthomhurst
authored
Merge pull request #2078 from thomhurst/docs/v3-api-migration-guide
docs: Update all documentation to V3 API patterns
2 parents 3dab8c7 + cdf4bb0 commit f5681ac

21 files changed

Lines changed: 1398 additions & 210 deletions

‎docs/architecture/interface-audit.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ This document provides a comprehensive audit of all `IPipeline*` interfaces in M
202202
- **Location:** `src/ModularPipelines/Context/IModuleContext.cs`
203203
- **Visibility:** Public
204204
- **Inherits From:** IPipelineContext
205-
- **Members:** GetModule<TModule, TResult>(), GetModuleIfRegistered<TModule, TResult>(), SubModule()
205+
- **Members:** GetModule<TModule>() (preferred), GetModule<TModule, TResult>(), GetModuleIfRegistered<TModule>(), GetModuleIfRegistered<TModule, TResult>(), SubModule()
206206
- **Purpose:** Primary interface for module developers
207207
- **Usages:** ~65 references (modules, examples, build)
208208
- **Recommendation:** **Keep public** - Primary user-facing interface

‎docs/architecture/interface-hierarchy.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,8 @@ public class MyModule : Module<string>
5555
| `Checksum` | File checksums |
5656
| `Environment` | Environment info |
5757
| `BuildSystemDetector` | CI system detection |
58-
| `GetModule<TModule, TResult>()` | Get another module's result |
58+
| `GetModule<TModule>()` | Get another module's result (preferred) |
59+
| `GetModule<TModule, TResult>()` | Get another module's result (explicit types) |
5960
| `SubModule()` | Track sub-operations |
6061

6162
### Extension Methods

‎docs/docs/examples/azure-example.md‎

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@ That would look like this:
1818
```csharp
1919
public class ProvisionUserAssignedIdentityModule : Module<UserAssignedIdentityResource>
2020
{
21-
protected override async Task<UserAssignedIdentityResource?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
21+
protected override async Task<UserAssignedIdentityResource?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
2222
{
2323
var userAssignedIdentityProvisionResponse = await context.Azure().Provisioner.Security.UserAssignedIdentity(
2424
new AzureResourceIdentifier("MySubscription", "MyResourceGroup", "MyUserIdentity"),
2525
new UserAssignedIdentityData(AzureLocation.UKSouth)
2626
);
27-
27+
2828
return userAssignedIdentityProvisionResponse.Value;
2929
}
3030
}
@@ -35,13 +35,13 @@ public class ProvisionUserAssignedIdentityModule : Module<UserAssignedIdentityRe
3535
```csharp
3636
public class ProvisionBlobStorageAccountModule : Module<StorageAccountResource>
3737
{
38-
protected override async Task<StorageAccountResource?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
38+
protected override async Task<StorageAccountResource?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
3939
{
4040
var blobStorageAccountProvisionResponse = await context.Azure().Provisioner.Storage.StorageAccount(
4141
new AzureResourceIdentifier("MySubscription", "MyResourceGroup", "MyStorage"),
4242
new StorageAccountCreateOrUpdateContent(new StorageSku(StorageSkuName.StandardGrs), StorageKind.BlobStorage, AzureLocation.UKSouth)
4343
);
44-
44+
4545
return blobStorageAccountProvisionResponse.Value;
4646
}
4747
}
@@ -53,16 +53,16 @@ public class ProvisionBlobStorageAccountModule : Module<StorageAccountResource>
5353
[DependsOn<ProvisionBlobStorageAccountModule>]
5454
public class ProvisionBlobStorageContainerModule : Module<BlobContainerResource>
5555
{
56-
protected override async Task<BlobContainerResource?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
56+
protected override async Task<BlobContainerResource?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
5757
{
58-
var blobStorageAccount = await GetModule<ProvisionBlobStorageAccountModule>();
58+
var blobStorageAccount = await context.GetModule<ProvisionBlobStorageAccountModule>();
5959

6060
var blobContainerProvisionResponse = await context.Azure().Provisioner.Storage.BlobContainer(
61-
blobStorageAccount.Value!.Id,
61+
blobStorageAccount.ValueOrDefault!.Id,
6262
"MyContainer",
6363
new BlobContainerData()
6464
);
65-
65+
6666
return blobContainerProvisionResponse.Value;
6767
}
6868
}
@@ -75,17 +75,17 @@ public class ProvisionBlobStorageContainerModule : Module<BlobContainerResource>
7575
[DependsOn<ProvisionUserAssignedIdentityModule>]
7676
public class AssignAccessToBlobStorageModule : Module<RoleAssignmentResource>
7777
{
78-
protected override async Task<RoleAssignmentResource?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
78+
protected override async Task<RoleAssignmentResource?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
7979
{
80-
var userAssignedIdentity = await GetModule<ProvisionUserAssignedIdentityModule>();
81-
82-
var storageAccount = await GetModule<ProvisionBlobStorageAccountModule>();
83-
80+
var userAssignedIdentity = await context.GetModule<ProvisionUserAssignedIdentityModule>();
81+
82+
var storageAccount = await context.GetModule<ProvisionBlobStorageAccountModule>();
83+
8484
var roleAssignmentResource = await context.Azure().Provisioner.Security.RoleAssignment(
85-
storageAccount.Value!.Id,
86-
new RoleAssignmentCreateOrUpdateContent(WellKnownRoleDefinitions.BlobStorageOwnerDefinitionId, userAssignedIdentity.Value!.Data.PrincipalId!.Value)
85+
storageAccount.ValueOrDefault!.Id,
86+
new RoleAssignmentCreateOrUpdateContent(WellKnownRoleDefinitions.BlobStorageOwnerDefinitionId, userAssignedIdentity.ValueOrDefault!.Data.PrincipalId!.Value)
8787
);
88-
88+
8989
return roleAssignmentResource.Value;
9090
}
9191
}
@@ -99,20 +99,20 @@ public class AssignAccessToBlobStorageModule : Module<RoleAssignmentResource>
9999
[DependsOn<ProvisionBlobStorageContainerModule>]
100100
public class ProvisionAzureFunction : Module<WebSiteResource>
101101
{
102-
protected override async Task<WebSiteResource?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
102+
protected override async Task<WebSiteResource?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
103103
{
104-
var userAssignedIdentity = await GetModule<ProvisionUserAssignedIdentityModule>();
104+
var userAssignedIdentity = await context.GetModule<ProvisionUserAssignedIdentityModule>();
105+
106+
var storageAccount = await context.GetModule<ProvisionBlobStorageAccountModule>();
107+
var blobContainer = await context.GetModule<ProvisionBlobStorageContainerModule>();
105108

106-
var storageAccount = await GetModule<ProvisionBlobStorageAccountModule>();
107-
var blobContainer = await GetModule<ProvisionBlobStorageContainerModule>();
108-
109109
var functionProvisionResponse = await context.Azure().Provisioner.Compute.WebSite(
110110
new AzureResourceIdentifier("MySubscription", "MyResourceGroup", "MyFunction"),
111111
new WebSiteData(AzureLocation.UKSouth)
112112
{
113113
Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.UserAssigned)
114114
{
115-
UserAssignedIdentities = { { userAssignedIdentity.Value!.Id, new UserAssignedIdentity() } }
115+
UserAssignedIdentities = { { userAssignedIdentity.ValueOrDefault!.Id, new UserAssignedIdentity() } }
116116
},
117117
SiteConfig = new SiteConfigProperties
118118
{
@@ -121,19 +121,19 @@ public class ProvisionAzureFunction : Module<WebSiteResource>
121121
new()
122122
{
123123
Name = "BlobStorageConnectionString",
124-
Value = storageAccount.Value!.Data.PrimaryEndpoints.BlobUri.AbsoluteUri
124+
Value = storageAccount.ValueOrDefault!.Data.PrimaryEndpoints.BlobUri.AbsoluteUri
125125
},
126126
new()
127127
{
128128
Name = "BlobContainerName",
129-
Value = blobContainer.Value!.Data.Name
129+
Value = blobContainer.ValueOrDefault!.Data.Name
130130
}
131131
}
132132
}
133133
// ... Other properties
134134
}
135135
);
136-
136+
137137
return functionProvisionResponse.Value;
138138
}
139139
```

‎docs/docs/examples/dotnet-test-build-publish.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Here's an example of publishing a NuGet package. Complete with generating semati
1111
```csharp
1212
public class NugetVersionGeneratorModule : Module<string>
1313
{
14-
protected override async Task<string?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
14+
protected override async Task<string?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
1515
{
1616
var gitVersionInformation = await context.Git().Versioning.GetGitVersioningInformation();
1717
return gitVersionInformation.FullSemVer;
@@ -24,15 +24,15 @@ public class NugetVersionGeneratorModule : Module<string>
2424
[DependsOn<NugetVersionGeneratorModule>]
2525
public class PackProjectsModule : Module<CommandResult[]>
2626
{
27-
protected override async Task<CommandResult[]?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
27+
protected override async Task<CommandResult[]?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
2828
{
29-
var packageVersion = await GetModule<NugetVersionGeneratorModule>();
29+
var packageVersion = await context.GetModule<NugetVersionGeneratorModule>();
3030

3131
var projects = context.Git().RootDirectory
3232
.GetFiles(x =>
3333
x.Extension == ".csproj" && !x.Name.Contains("test", StringComparison.InvariantCultureIgnoreCase))
3434
.ToList();
35-
35+
3636
return await projects
3737
.ToAsyncProcessorBuilder()
3838
.SelectAsync(async projectFile => await context.DotNet().Pack(new DotNetPackOptions
@@ -41,8 +41,8 @@ public class PackProjectsModule : Module<CommandResult[]>
4141
IncludeSource = true,
4242
Properties = new List<string>
4343
{
44-
$"PackageVersion={packageVersion.Value}",
45-
$"Version={packageVersion.Value}",
44+
$"PackageVersion={packageVersion.ValueOrDefault}",
45+
$"Version={packageVersion.ValueOrDefault}",
4646
},
4747
}, cancellationToken))
4848
.ProcessOneAtATime();
@@ -57,7 +57,7 @@ public class PackProjectsModule : Module<CommandResult[]>
5757
[DependsOn<PackProjectsModule>]
5858
public class RunUnitTestsModule : Module<DotNetTestResult[]>
5959
{
60-
protected override async Task<DotNetTestResult[]?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
60+
protected override async Task<DotNetTestResult[]?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
6161
{
6262
return await context.Git().RootDirectory
6363
.GetFiles(file => file.Path.EndsWith(".csproj", StringComparison.OrdinalIgnoreCase)
@@ -88,7 +88,7 @@ public class UploadPackagesToNugetModule : Module<CommandResult[]>
8888
_nugetSettings = nugetSettings;
8989
}
9090

91-
protected override async Task<CommandResult[]?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
91+
protected override async Task<CommandResult[]?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
9292
{
9393
ArgumentNullException.ThrowIfNull(_nugetSettings.Value.ApiKey);
9494

‎docs/docs/examples/single-file-csharp.md‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,35 +12,39 @@ To use ModularPipelines in a single file C# application, you can follow these st
1212
2. **Add ModularPipelines to your project**: You can add TUnit as a package reference in your file. At the top of your `example.cs`, add the following line:
1313

1414
```csharp
15-
#:package ModularPipelines@2.*
15+
#:package ModularPipelines@3.*
1616
```
1717

1818
Alternatively, you can specify a specific version:
1919

2020
```csharp
21-
#:package ModularPipelines@2.44.45
21+
#:package ModularPipelines@3.0.0
2222
```
2323

2424
3. **Write your C# code**: Below the package reference, you can write your C# code using ModularPipelines. Here’s a simple example that uses ModularPipelines to check the dotnet version:
2525

2626
```csharp
2727
#!/usr/bin/dotnet run
28-
#:package ModularPipelines.DotNet@2.44.*
28+
#:package ModularPipelines.DotNet@3.*
29+
using ModularPipelines;
2930
using ModularPipelines.Attributes;
3031
using ModularPipelines.Context;
3132
using ModularPipelines.DotNet.Extensions;
32-
using ModularPipelines.Host;
33+
using ModularPipelines.Extensions;
3334
using ModularPipelines.Models;
3435
using ModularPipelines.Modules;
3536

36-
await PipelineHostBuilder.Create()
37+
var builder = Pipeline.CreateBuilder(args);
38+
39+
builder.Services
3740
.AddModule<UpdateDotnetWorkloads>()
38-
.AddModule<CheckDotnetSdkModule>()
39-
.ExecutePipelineAsync();
41+
.AddModule<CheckDotnetSdkModule>();
42+
43+
await builder.Build().RunAsync();
4044

4145
public class UpdateDotnetWorkloads : Module<CommandResult>
4246
{
43-
protected override async Task<CommandResult?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
47+
protected override async Task<CommandResult?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
4448
{
4549
return await context.DotNet().DotNetWorkload.Update(token: cancellationToken);
4650
}
@@ -49,8 +53,7 @@ To use ModularPipelines in a single file C# application, you can follow these st
4953
[DependsOn<UpdateDotnetWorkloads>]
5054
public class CheckDotnetSdkModule : Module<CommandResult>
5155
{
52-
53-
protected override async Task<CommandResult?> ExecuteAsync(IPipelineContext context, CancellationToken cancellationToken)
56+
protected override async Task<CommandResult?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
5457
{
5558
return await context.DotNet().Sdk.Check(token: cancellationToken);
5659
}

0 commit comments

Comments
 (0)