DSC v3 - Registry List, Registry Adapter and Community Resource Update Meeting

29:234 speakers
27:18
duration
11
chapters
4
speakers
10
Terms
DSC v3registry listregistry adapteradaptive manifestclass-based resourcesJSON schema

Speakers

4
Speaker A71%31 turns
Speaker B2%4 turns
Speaker C19%19 turns
Speaker D9%10 turns

Key ideas

7
  • DSC 3.2 is GA and 3.3 Preview 1 is available with new features.
  • RegistryList resource allows applying multiple registry entries in one resource for clarity and performance; switching to it is recommended.
  • List-type resources should be added when users typically manipulate multiple items at once; no harm in having both singleton and list variants.
  • Registry adapter enables authoring DSC v3 resources that expose friendly schema while writing required registry types/values under the hood.
  • Adaptive resource manifests can include content (not just paths) and must be supported explicitly by adapters.

Key highlights

7
  • Announcement: DSC 3.2 GA and DSC 3.3 Preview 1 released.
  • New registry list resource consolidates multiple registry operations into a single array-based resource property 'registry entries'.
  • Registry adapter concept: adaptive resource manifest may include inline 'content' consumed by adapters to map user-friendly properties to registry keys/values.
  • Adapter must map user inputs (booleans, enums, strings) to correct registry types (DWORD, binary, string) and handle inconsistent upstream representations.
  • Standardized naming suffix 'List' helps identify array-taking resources via 'DSC resource list'.

Decisions

4
  • Recommend using registry list resource (3.3 preview) instead of multiple singleton registry resources for grouped registry operations.
  • Standardize on suffix 'List' for resources that accept arrays to make discovery and identification easier (DSC resource list).
  • Adaptive resource manifests may include inline 'content' and adapters should support this model; partial adapters must explicitly support content to use it.
  • Community goal: progressively update DSC community resources toward class-based implementations to leverage v3 features and schema discovery.

Action items

3
  • Post link to the DSC 3.2 blog post in chatJason
  • Ask Mikey about the origin of the fictional Tomo exampleJason
  • Convert existing PowerShell script-based resources to class-based DSC resources (start evaluation and conversion)Marvin

Terms

10
DSC (Desired State Configuration) — Microsoft configuration management platform for declaring system state.
Registry resource — A DSC resource that reads/writes Windows registry keys/values.
Registry list — A new array-style registry resource that accepts multiple registry entries in one resource invocation for performance and organization.
Adapter (registry adapter, PowerShell adapter) — A component that maps adapted resource manifests to underlying implementation; must understand 'content' when provided.
Adaptive resource manifest — A resource definition format that can include inline content (schema and mapping) which adapters consume.

Main content

11 chapters · 27:18
0:00

1. Meeting Opening and Announcements

Speaker A0:00

Jason, you also have permission to admit people?

Speaker B0:05

Yes, I do, and I am.

Speaker A0:07

Okay, then I don't have to worry about that. Let me double-check what is on my screen for a second. All right, so since I don't have any prepared content, I'm just going to talk to a couple of things. Let me share my screen. This one, I think. Yep. And I'll make this bigger in a second.

Okay. Let's get rid of that. All right, so I guess one quick announcement. DSC 3.2 was GA. Was it last week, Jason? I don't remember exactly now.

Speaker B0:59

Yeah, it was last week.

Speaker A1:01

Yeah. You want to post the link to your blog post in the chat?

Speaker B1:04

Yeah, I sure will.

Speaker A1:06

At the same time, 3.3 Preview 1 came out, I believe also last week. One of the new things in there—ignore what's on the screen. I'm going to talk about this later. This is something I'm currently working on. What you're looking at is just VS Code opening the repo, the DC repo. So, I'm trying to find resources registry. This one. Oh, I need to wait. Was that one merged? Let me double check something here. Let me go. I thought that PO was merged. I'm gonna have to rebase to pick it up. It must have been merged, right? Yeah, it was. Okay, so this will be interesting because I'll probably hit some merge conflicts.

All right, let's just see what happens in real time. Oh, fine. Check this in for now. Let's see, updating adapter. All right. And then let's rebase. Yeah. All right. Well, I'm going to hit this anyway. So, I'll just— you can watch me do a quick— is this gonna be quick? I think in this case I need to accept both. And there's gonna be 3. There should be 3 since the registry list. And, oh, I see. It's because I made a different change. Oh, man. All right, let me, let me do it differently. I'm going to do this later. Let me— maybe I should abort this. It's gonna take a little more time to unwind this problem. Don't save. Instead, I'm gonna push my changes, get back to that later. Let me just check out the main branch. It'll be easier.

So, just to my main branch. All right. Let's go back here. I'm not going to build it because that's going to take time, but I can talk to it. There's a new resource that was added called registry list. Basically, it works the same as the existing registry resource, except rather than if you have multiple registry changes you want to make at the same time or read or whatever the case may be, you can now have it as an array.

4:54

2. Registry List Resource: Design and Usage

Speaker A4:54

The best way to look at this is in the tests. For example, here, whereas before you would have multiple instances of the registry resource and then each one have their own key path and values and whatever the case may be, in this case, you just have a single top-level property called registry entries, and then you can just have as many key paths and values as you want. Now, obviously, as you can see here, if you have multiple values under the same key, you just have to repeat it.

Now, the benefit is that from a configuration doc perspective, you can have all your registry stuff in one place. But also from a performance perspective, it doesn't have to spawn the registry resource every time. It just spawns it once and it takes care of all of them at the same time. I do recommend if you're using a registry resource to switch to this registry list one. Obviously, there's only an available 3.3 preview one. We're not going to backport to 3.2, although it's compatible with 3.2. Hopefully, you're just testing against 3.3 anyways.

That covers that. Any questions before I talk about the other thing? Which now I need to get back to my other branch, which I called registry adapter. This I think is actually more interesting.

Speaker C6:15

Steve.

Speaker A6:16

Hi, go ahead.

Speaker C6:17

Yeah, quick question. What are some of the design decisions that resource authors have to take into account when they make like a list resource themselves?

Speaker A6:28

Yeah, so that's a good question. So in general, if you look into, for example, Windows Service versus like Windows Firewall, right? So in the firewall case, we also have a list type resource. Where is it? Firewall rule list. Again, this is in 3.2. A lot of it is just going to come from the engineer's initial thinking of how people use it.

And as you saw in the registry case, there's no harm at all in having both a single one and an array one. In the case of registry list, like in terms of the code, fundamentally, it's just reusing the same schema as a single registry, but it's in an array, so it just has the loop. I mean, fundamentally, the amount of changes needed to support registry list was very small. You can look at the PR on the repo if you want to see that.

But what I would say is, like, for example, in the case of service, because I wrote both of these, service doesn't have a service list today. We could create a service list if there's a need for it. But my thinking is that most people aren't touching a lot of services at the same time.

Whereas in the case of firewall, especially for set, you're probably going to apply multiple firewall rules at the same time. Similarly, I think for— let's see, Windows Update, I think is also a list. Yeah, because you probably want to either find out all the updates that should be applied, haven't been applied, so you have a list of them, or you want to forcibly install a bunch of updates at the same time versus one by one.

8:06

3. Design Considerations for List vs Singleton Resources

Speaker A8:06

So it is kind of something, I guess, from experience. But again, I want to call out there's no harm in having both a singleton. So in this case, we could have had a Microsoft.Windows.Update resource as well as an update list. There's no conflict at all having both of those.

The key thing here is we do standardize on the suffix list to give an easy indicator when you do DSC resource list. I think I have it working. Build here, maybe. Right, so if you do DSC resource list, then you can easily identify which ones take an array versus a singleton.

By the way, whenever you see me run DSC on my system, it's gonna be a little bit slower because this is a debug build, not the release build, which has performance optimizations. And you can kind of see there's also a ton of test resources from the repo.

All right. Any questions on that topic, or did I answer that completely?

Speaker C9:03

You're good, thanks. All.

Speaker A9:04

right, so let me talk about this new thing I'm currently working on, which is I'm going to start with Windows Personalization Resource. So this will be a resource that comes with it because I needed something real to test against.

All right, so as I was working through the registry stuff, and then, or rather Registry List Resource, because there's a bunch of internal partners using a DSC v3, and they shared some of their configurations with me, and I just saw like a ton of registry access.

All right, here's what I would say in general is if you can avoid touching the registry directly, that is always preferred. If you can have an abstraction over the resource, over the registry, that is much better than touching it directly.

All right, now there are cases where you can't do that or don't want— I don't say don't want to, can't do it, then of course that's why the registry resource exists. However, I was trying, as I was looking through some of the internal people using DSC, here's one example that I found is they're doing a bunch of personalization.

So there's a bunch of Microsoft-documented registry settings for basically Windows Explorer and Start menu. What the docs call personalization, this is why I called it that as well. And you can kind of see the key path here ends in personalized, right? There's a whole bunch of it. In fact, this file doesn't have all of them. I only wanted to pick up enough of different cases to test my adapter.

10:24

4. Registry Adapter and Windows Personalization Resource

Speaker A10:24

What you're seeing here is a registry manifest for an adapted resource working against the new— what I'm currently authoring, a registry adapter. The purpose of this is that you can have a single file. Unlike the PowerShell adapter, for example, where you have adapted resource manifest and you have the PS1 or PSN1, in this case, it was more beneficial to have the content for the resource itself inside the manifest.

Instead of a path, there's going to be a new property you can have in an adaptive resource manifest, which is content, and this will be given to the adapter. Adapters will have to support this explicitly, so partial adapter won't support this. But in this case, what I want to be able to do is have some schema defined for the Registry adapter so that you can easily author a DCv3 resource that only touches the registry but is presented as a DSC resource that the end user doesn't have to know is touching the registry.

In this case, there's a couple of things that are needed. These are all documented by Microsoft, but for example, when you're authoring a configuration using this resource, you're going to say, app uses light theme, so you don't have to worry about these implementation details. And then this will be a boolean, which I'll show down below when I go into JSON schema, and you're going to provide true or false.

But in the registry, whoever wrote this decided instead of making it a boolean, because boolean types do exist in the registry, they made it a 0 and 1, right? So there, and it's a DWORD, so it's a number. So basically I need to know, the registry adapter needs to know, hey, what is the actual type that it needs to put into the registry? What is the path and what is the value name and then what the values are. That's why you see this repeated.

The true/false one is common for this, but then there's this binary case as well. This one is how to enable or disable or hide certain things like documents, downloads from showing in the Start menu. In this case, we don't want to expose this GUID to the user. This is basically enum that is more human-friendly so you can do stuff like user profile network, whatever.

But the adapter needs to know, hey, here's the actual binary content that needs to be put in the registry to make this take effect. Interestingly enough, let's see. There are some other ones. I presume multiple different engineers worked on this stuff in Windows because there are ones that actually have an actual Boolean, so that's what this is.

Then for some reason, this person chose to represent 0 and 1 as strings versus as a number. It's like the worst of all worlds in my opinion. But this needs to be handled as well. Basically, the way this will work is the adapter will look at the value provided on the input JSON or YAML and then apply the actual appropriate registry value type in the registry.

Anything else in here? There's also another enum example. For an author who wants to leverage this in the future, again, I'm hoping this will show up in preview too. Is you need both this definition of content, and your content also needs to match your JSON schema. So you have to write some JSON schema for this to work because the adapter won't know what is allowed and what isn't allowed for your resource.

So, in this case, these are all the properties. You can kind of see this again, ignoring what actually gets stored in the registry, what's presented to the user. That this is a boolean. This Visible places thing is an array of strings, but the strings have these specific values that are allowed.

And here's another one where this is multi-monitor taskbar grouping mode. It has 3 potential values, but if you look back in the code, what's actually stored in the registry is these numbers 0, 1, and 2, even though these are strings. So actually, I probably need to put this in quotes to make this work correctly.

14:27

5. Personalization, Registry Settings, and WMI Mapping

Speaker A14:27

All right. Okay, anyways, so this is coming, and I'm— one other thing that came up in my mind is like this personalization one. Like, I don't think it makes sense to ship it as part of the DC platform itself. So I think the working group, one thing we may have to discuss next time is: does it make sense to have like a— I don't want to call it a resource kit, even though that was the name of this call, but something like that where it's just a bunch of resources you can optionally install.

But I'll worry about that later once I get this working. But you can get the idea. If there's other things in the registry, I think Windows Update agent settings are also documented publicly by Microsoft. I'll probably have that one later as well and whatever else I can find in the registry. You'll get resources.

The other benefit here is like because you have the JSON schema, if you're using like VS Code against the JSON schema, then you'll get these tooltips that tell you these descriptions of what these settings mean. So you get other niceties.

Questions or comments on this? All right. And by the way, one other thing I may do in the future with this type of model is also for WMI. Because in WMI land, you're going to get a whole bunch of less— well, how should I put this? If you're familiar with WMI, you'll see a bunch of stuff like Win32_Sim_ and stuff like that.

I think the way we want to present it in DSC is to not worry about the WMI and SIM-specific stuff and rather present it like this where we have a mapping. So I think it would make sense to have something similar as a— like, update the WMI adapter to have a similar model where you can author DC resources that just touch WMI in a more human-friendly way than what we have today, which requires a lot of knowledge about WMI.

16:25

6. AMA and Demo: Adaptive Resource Manifest & DSC Resource Authoring

Speaker A16:25

All right, that's pretty much the end of what I have unless there's a question or comments about anything. Maybe we can turn this into an AMA. Heiss?

Speaker C16:34

Yeah, quick question. I was going through the announcement itself, and there was like this fictional example on Tomo.

Speaker A16:44

Yeah.

Speaker C16:45

Can you mention something about it, or explain something about it?

Speaker A16:50

I think, Jason, isn't that built off something that Mikey had done?

Speaker B16:55

Yeah, Heiss, this was something that Mikey and I were putting together, and the code was something that we just invented. As far as I know, I mean, I'll ask Mikey, but I don't think it came from anything in particular.

Speaker C17:14

Okay. I can still do a quick demo, by the way.

Speaker A17:16

Oh yeah, go ahead if you want. We got plenty of time.

Speaker C17:19

I think I demoed it already a couple of calls away, but we decided to move it to the community.

So, let me see if I can share my screen. Is it visible?

Speaker A17:46

Yes.

Speaker C17:47

All right. I'm trying this out in the SQL Server DSC one because I wanted to see how it will behave. We decided to— So we just launched a new DSC resource authoring module from the DSC community, and currently, I'm running it locally, actually.

So I think many are familiar with the whole standard layout of either script-based or class-based DSC resources. This module mainly targets class-based DSC resources because that's the way forward when you want to use it through the DSC engine itself.

But I think everyone is familiar with running the build automation script that comes from this sample template, right? I also included— and this sits within the module itself, but I'm currently testing it out locally— but this is the task itself.

So if I'm now building the module itself, everything gets scaffolded, and you get one big module. But it now also includes the adapted resource manifest. So whenever I'm adding that now to the DSC resource path, you can easily list them out, but you can also get the schema itself, which is not possible when you do it— what is it, explicit through the adapter? I guess so.

Speaker A19:32

Yeah, I guess you can put it that way.

Speaker C19:34

Yeah, so this is pretty easy because you can easily hook in the task in the build.yaml. I think I configured it. Let me see. In the build one.

So if you have like this default scaffolding project, you can hook it in and it creates an adapted resource manifest. And the beautiful thing about this is when it's packed and it's installed in the PS module path, it will also automatically be discovered. Because that was also shipped within 3.2, I think.

Speaker A20:14

Yeah, that should be in 3.2.

Speaker C20:16

Yeah. That's basically it. Any questions?

20:22

7. Community Resources: Class-based Migration and Tooling

Speaker A20:22

Let me, let me make sure folks who are not as involved in the project understand. Like, the adaptive resource manifest concept means that DC can find it much faster and easier than waiting on the PowerShell adapter to find it. Right?

But you also get the benefits of having the proper schema for the resource if it's authored. So, Heinz, is the goal here to eventually have all of the DSC community resources updated?

Speaker C20:51

Yes.

Speaker A20:52

Cool. Looking forward to that.

Speaker C20:56

Not all the community ones have class-based DSC resources yet. I think that's still like an initiative going on by—

Speaker A21:06

Okay.

Speaker C21:07

Community members itself. But yeah.

Speaker A21:14

I wonder how well Copilot could transform those into class-based that aren't today.

Speaker C21:29

Most likely.

Speaker A21:31

Yeah. I mean, for the script-based ones, it's really transforming the MOF into a class and then having the class methods call the script functions.

Speaker C21:42

Yeah, but I think it's a good one if, like, the RDK itself comes in, right? That will be the baseline on converting script-based to class-based because then it inherently uses all the types, I guess, from the RDK. Which makes it more future-proof, but that's opinions.

22:05

8. Opening and call for questions

Speaker A22:05

Yep. Right. Anything else, or any questions or topics people want to have covered? Marvin? Go ahead and unmute.

Speaker D22:27

Yeah, so apologies. I've been out of the loop for a minute here.

So we have—we use DSC to do configuration of our GCP instances or whatever automation.

Anyways, it's all written in Windows—it's all written in PowerShell DSC.

Speaker A22:52

Okay.

22:53

9. Marvin's DSC conversion needs and language considerations

Speaker D22:53

So I need to start looking at, you know, since this is where we're going with it, I need to start looking at converting all that stuff over to DSC3.

Where— and the last time I did look, all I saw in the way of samples or tutorials was something written in Go on like the PowerShell DSC samples thing.

Speaker A23:17

Yes.

Speaker D23:18

Is something updated? Is there some updated documentation somewhere that I'm missing?

Speaker A23:24

No, not yet. And let me ask you this: what programming language would help you most?

Speaker D23:32

Um, honestly, in all honesty, I think, I think for us it's not like they're gonna do— it's not like they're ever gonna— in our organization, they're never gonna go, oh, let's use DSC3 on Linux. So that's probably not going to happen. It's probably going to continue to be a Windows thing.

Right. So it could, it could probably stay written in PowerShell or something like that, or, you know, C# even. You know, I, I, I guess I, I guess I'd like to just start looking at getting that stuff converted, you know, at a level so that, you know, we can at least start looking at it and see if it makes sense to make the switch.

Because obviously, I know we could probably still just do Windows PowerShell DSC, but, you know, I'd like to at least give an option here.

Speaker A24:28

Yeah, and the benefit is, even if you convert them to v3 compatible, it'll still work in the old world, right? So you're not breaking anything.

24:40

10. Documentation, resources, and recommendations for DSC v3

Speaker D24:40

Then, so that works. Is there like— so like, where's that documentation at? Because it doesn't seem to be on the documentation. It is a little bit.

Speaker A24:49

Behind. I'll be honest, I think the best examples are probably in the DSC community, OpenDSC, wherever Heiss is doing his work.

Speaker D24:59

Oh, okay.

Speaker A25:02

Yeah. I don't know if you have any links just available, Heiss, to provide a sample.

Speaker C25:09

If you're looking for doing things with .NET itself, for example, then I would look in the OpenDSC repository because that's by Thomas Nitu. He's also one of the working group members. He created a library for it. I think you can easily crank out a CLI, and you have like a command-based DSC resource.

If you're looking for just PowerShell resources, what Steve mentioned, I think like the class-based and the script-based still work as today, whereas class-based will be the focus. What I just demonstrated is to get more of the IntelliSense, the schema, and speeding up the discovery of resources.

Speaker D25:56

What I'm hearing is I should be trying to convert what we have to class-based resources. Is that what I'm hearing?

Speaker A26:03

Yeah, that'd be the first step in recommendation at this point.

Speaker D26:08

Easy enough. I can work on that.

Speaker A26:10

Thank you. Again, I want to call out that if you convert to class-based, it'll still work with your existing model. Quote unquote, broken anything, but it does allow for new scenarios in the future.

Speaker D26:21

Okay, fair enough. Thank you.

Speaker A26:24

I'd love to hear if you had any challenges. Feel free to bring it up here in the next meeting, right? And we can work through that. Okay.

Speaker C26:33

Marvin, this just got merged, so that's in the main branch. That might be a starting point for you.

Speaker D26:43

Appreciate it. Thank you.

26:48

11. Meeting Closing and Goodbyes

Speaker A26:48

All right, anything else from anyone? If not, we can, I guess, end this early.

All right, I guess for Heist, you have something, or— No,

Speaker C27:12

No, no, I would say I have a good one then.

Speaker A27:15

Okay.

Speaker C27:16

All right, thanks everyone.

Speaker A27:18

All right, see you guys next time. Bye-bye.