Skip to content

Commit d289655

Browse files
GijsreynGijsreyn
committed
Add reference documentation for DSC.PackageManagement/Apt
1 parent 6131a28 commit d289655

File tree

3 files changed

+363
-70
lines changed

3 files changed

+363
-70
lines changed

‎docs/reference/resources/DSC/PackageManagement/APT/examples/manage-packages-with-apt.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
description: >
3+
Demonstrates how to manage packages with the DSC.PackageManagement/Apt resource
4+
ms.date: 06/30/2025
5+
ms.topic: reference
6+
title: Manage packages with APT
7+
---
8+
9+
# Manage packages with APT
10+
11+
This example demonstrates how to use the `DSC.PackageManagement/Apt` resource to manage packages on Linux systems
12+
that use the APT package manager.
13+
14+
## Test if package is installed
15+
16+
The following snippet shows how you can use the resource with the [dsc resource test][01] command
17+
to check whether the `nginx` package exists.
18+
19+
```bash
20+
dsc resource test --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}'
21+
```
22+
23+
When the package is not installed, DSC returns the following result.
24+
25+
> [!NOTE]
26+
> Note that the version and source values can differ depending on your system's package repositories and available
27+
> package versions.
28+
29+
```yaml
30+
desiredState:
31+
packageName: nginx
32+
actualState:
33+
_exist: "true"
34+
packageName: nginx
35+
version: 1.24.0-2ubuntu7.3
36+
source: noble-updates,noble-security,now
37+
inDesiredState: false
38+
differingProperties:
39+
- _exist
40+
```
41+
42+
## Ensure a package with version is installed
43+
44+
To ensure the system is in the desired state with a particular version, use the [dsc resource set][02]
45+
command.
46+
47+
```bash
48+
dsc resource set --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx", "version":"1.24.0-2ubuntu7"}'
49+
```
50+
51+
When the resource install the package, DSC returns the following result:
52+
53+
```yaml
54+
beforeState:
55+
packageName: "nginx"
56+
version: "1.24.0-2ubuntu7"
57+
_exist: false
58+
afterState:
59+
keyPath: HKCU\DscExamples\ManagedKey
60+
version: "1.24.0-2ubuntu7"
61+
changedProperties:
62+
- _exist
63+
```
64+
65+
You can test the instance again to confirm that the package exists:
66+
67+
```bash
68+
dsc resource test --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx", "version":"1.24.0-2ubuntu7"}'
69+
```
70+
71+
```yaml
72+
desiredState:
73+
packageName: nginx
74+
version: 1.24.0-2ubuntu7
75+
actualState:
76+
_exist: true
77+
packageName: nginx
78+
version: 1.24.0-2ubuntu7
79+
source: noble-updates,noble-security,now
80+
inDesiredState: true
81+
differingProperties: []
82+
```
83+
84+
## Uninstall a package
85+
86+
To uninstall a package, set the `_exist` property to `false`:
87+
88+
```bash
89+
dsc resource set --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx", "_exist": false}'
90+
```
91+
92+
The `DSC.PackageManagement/Apt` resource implements the [setHandleExist][03], indicating the resource
93+
will be deleted.
94+
95+
To verify the package no longer exists, use the `dsc resource get` command
96+
97+
```powershell
98+
dsc resource get --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}'
99+
```
100+
101+
```yaml
102+
actualState:
103+
packageName: nginx
104+
_exist: false
105+
```
106+
107+
<!-- Link reference definitions -->
108+
[01]: ../../../../../cli/resource/test.md
109+
[02]: ../../../../../cli/resource/set.md
110+
[03]: ../../../../../../concepts/resources/capabilities.md#sethandlesexist

‎docs/reference/resources/DSC/PackageManagement/APT/index.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
description: DSC.PackageManagement/Apt resource reference documentation
3+
ms.date: 06/30/2025
4+
ms.topic: reference
5+
title: DSC.PackageManagement/Apt
6+
---
7+
8+
# DSC.PackageManagement/Apt
9+
10+
## Synopsis
11+
12+
Manage packages with the advanced package tool (APT) on Linux systems.
13+
14+
## Metadata
15+
16+
```yaml
17+
Version : 0.1.0
18+
Kind : resource
19+
Tags : [Linux, apt, PackageManagement]
20+
Author : Microsoft
21+
```
22+
23+
## Instance definition syntax
24+
25+
```yaml
26+
resources:
27+
- name: <instance name>
28+
type: DSC.PackageManagement/Apt
29+
properties:
30+
# Required properties
31+
packageName: string
32+
# Instance properties
33+
_exist: boolean
34+
version: string
35+
```
36+
37+
## Description
38+
39+
The `DSC.PackageManagement/Apt` resource enables you to idempotently manage packages with the Advanced Package Tool (APT) on
40+
Linux systems. The resource can:
41+
42+
- Install packages
43+
- Uninstall packages
44+
- Check if a package is installed
45+
- Verify the version of an installed package
46+
47+
> [!NOTE]
48+
> This resource only works on Linux systems that use the APT package manager, such as Ubuntu and Debian.
49+
50+
## Requirements
51+
52+
- A Linux system with APT installed
53+
- Administrative privileges (root or sudo access) to install and remove packages
54+
55+
## Capabilities
56+
57+
The resource has the following capabilities:
58+
59+
- `get` - You can use the resource to retrieve the actual state of an instance.
60+
- `set` - You can use the resource to enforce the desired state for an instance.
61+
- `export` - You can use the resource to export the current state of the system.
62+
63+
For more information about resource capabilities, see
64+
[DSC resource capabilities][01].
65+
66+
## Examples
67+
68+
1. [Manage packages with APT](./examples/manage-packages-with-apt.md) - Shows how to install, uninstall,
69+
and check packages with the `DSC.PackageManagement/Apt` resource.
70+
71+
## Properties
72+
73+
The following list describes the properties for the resource.
74+
75+
- **Required properties:** <a id="required-properties"></a> The following properties are always
76+
required when defining an instance of the resource. An instance that doesn't define each of these
77+
properties is invalid. For more information, see the "Required resource properties" section in
78+
[DSC resource properties][02]
79+
80+
- [packageName](#packagename) - The name of the package to query or install.
81+
82+
- **Key properties:** <a id="key-properties"></a> The following properties uniquely identify an
83+
instance. If two instances of a resource have the same values for their key properties, the
84+
instances are conflicting. For more information about key properties, see the "Key resource
85+
properties" section in [DSC resource properties][03].
86+
87+
- [packageName](#packagename) (required) - The name of the package to query or install.
88+
- [version](#version) (optional) - The version of the package to install.
89+
90+
- **Instance properties:** <a id="instance-properties"></a> The following properties are optional.
91+
They define the desired state for an instance of the resource.
92+
93+
- [_exist](#_exist) - Defines whether the package should exist.
94+
- [version](#version) - The version of the package to install.
95+
96+
- **Read-only properties:** <a id="read-only-properties"></a> The resource returns the following
97+
properties, but they aren't configurable. For more information about read-only properties, see
98+
the "Read-only resource properties" section in [DSC resource properties][04].
99+
100+
- [source](#source) - Indicates the source of the package.
101+
102+
### packageName
103+
104+
<details><summary>Expand for <code>packageName</code> property metadata</summary>
105+
106+
```yaml
107+
Type : string
108+
IsRequired : true
109+
IsKey : true
110+
IsReadOnly : false
111+
IsWriteOnly : false
112+
```
113+
114+
</details>
115+
116+
Defines the name of the package to query or install. This property is required and serves as the key for uniquely
117+
identifying the package.
118+
119+
### _exist
120+
121+
<details><summary>Expand for <code>_exist</code> property metadata</summary>
122+
123+
```yaml
124+
Type : boolean
125+
IsRequired : false
126+
IsKey : false
127+
IsReadOnly : false
128+
IsWriteOnly : false
129+
DefaultValue : true
130+
```
131+
132+
</details>
133+
134+
The `_exist` canonical resource property determines whether a package should exist. When the
135+
value for `_exist` is `true`, the resource installs the package if it doesn't exist. When
136+
the value for `_exist` is `false`, the resource removes or uninstalls the package if it does exist.
137+
The default value for this property when not specified for an instance is `true`.
138+
139+
### version
140+
141+
<details><summary>Expand for <code>version</code> property metadata</summary>
142+
143+
```yaml
144+
Type : string
145+
IsRequired : false
146+
IsKey : false
147+
IsReadOnly : false
148+
IsWriteOnly : false
149+
```
150+
151+
</details>
152+
153+
Defines the version of the package to install. If not specified, the latest available version will be installed.
154+
155+
### source
156+
157+
<details><summary>Expand for <code>source</code> property metadata</summary>
158+
159+
```yaml
160+
Type : string
161+
IsRequired : false
162+
IsKey : false
163+
IsReadOnly : true
164+
IsWriteOnly : false
165+
```
166+
167+
</details>
168+
169+
Indicates the source of the package. This is a read-only property returned by the resource after a `get` operation.
170+
171+
## Exit codes
172+
173+
The resource returns the following exit codes from operations:
174+
175+
- [0](#exit-code-0) - Success
176+
- [1](#exit-code-1) - Invalid parameter
177+
178+
### Exit code 0
179+
180+
Indicates the resource operation completed without errors.
181+
182+
### Exit code 1
183+
184+
Indicates the resource operation failed due to an invalid parameter. When the resource returns this
185+
exit code, it also emits an error message with details about the invalid parameter.
186+
187+
## See also
188+
189+
- [For more information about APT](https://wiki.debian.org/Apt)
190+
191+
<!-- Link definitions -->
192+
[01]: ../../../../../concepts/resources/capabilities.md
193+
[02]: ../../../../../concepts/resources/properties.md#required-resource-properties
194+
[03]: ../../../../../concepts/resources/properties.md#key-resource-properties
195+
[04]: ../../../../../concepts/resources/properties.md#read-only-resource-properties

0 commit comments

Comments
 (0)